@llm4ts/shell 2.45.0 → 2.46.0

package/src/OperatorConfig.ts

@@ -0,0 +1,148 @@
+import { homedir } from "node:os"
+import { basename, join, resolve } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { ShellUsageError } from "./ShellErrors.ts"
+
+export interface McpFlags {
+  readonly stdio: boolean
+  readonly http: boolean
+  readonly host: Option.Option<string>
+  readonly port: Option.Option<number>
+  readonly tokenFile: Option.Option<string>
+  readonly repo: ReadonlyArray<string>
+  readonly allowRun: boolean
+  readonly allowApprove: boolean
+  readonly parallelRuns: Option.Option<number>
+}
+
+export interface OperatorConfig {
+  readonly transport:
+    | { readonly _tag: "stdio" }
+    | {
+        readonly _tag: "http"
+        readonly host: string
+        readonly port: number
+        readonly token: string
+      }
+  readonly repos: ReadonlyArray<{ readonly id: string; readonly path: string }>
+  readonly allowRun: boolean
+  readonly allowApprove: boolean
+  readonly parallelRuns: number
+}
+
+export const McpConfigFile = Schema.Struct({
+  repos: Schema.Array(Schema.Struct({ id: Schema.String, path: Schema.String }))
+})
+
+/** The same name shape as an epic id: it names the repository's state directory. */
+const repoIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
+
+const usage = (message: string): ShellUsageError => new ShellUsageError({ message })
+
+/**
+ * Turns the `mcp` flags into the operator configuration. The token is read from the
+ * environment or a file and is never echoed in an error message.
+ */
+export const mcpOptionsFrom = (
+  flags: McpFlags,
+  environment: Readonly<Record<string, string | undefined>>,
+  cwd: string,
+  readFile: (path: string) => Effect.Effect<string | undefined>
+): Effect.Effect<OperatorConfig, ShellUsageError> =>
+  Effect.gen(function* () {
+    if (flags.stdio && flags.http) {
+      return yield* usage("mcp takes either --stdio or --http, not both")
+    }
+    const parallelRuns = Option.getOrElse(flags.parallelRuns, () => 1)
+    if (!Number.isInteger(parallelRuns) || parallelRuns < 1) {
+      return yield* usage("--parallel-runs must be a positive integer")
+    }
+
+    const transport = flags.http ? yield* httpTransport(flags, environment, cwd, readFile) : stdio
+
+    const repos = yield* reposFrom(flags, environment, cwd, readFile)
+    const seen = new Set<string>()
+    for (const repo of repos) {
+      if (seen.has(repo.id)) {
+        return yield* usage(`mcp repository id "${repo.id}" is used twice`)
+      }
+      seen.add(repo.id)
+    }
+
+    return {
+      transport,
+      repos,
+      allowRun: flags.allowRun,
+      allowApprove: flags.allowApprove,
+      parallelRuns
+    }
+  })
+
+const stdio: OperatorConfig["transport"] = { _tag: "stdio" }
+
+const httpTransport = (
+  flags: McpFlags,
+  environment: Readonly<Record<string, string | undefined>>,
+  cwd: string,
+  readFile: (path: string) => Effect.Effect<string | undefined>
+): Effect.Effect<OperatorConfig["transport"], ShellUsageError> =>
+  Effect.gen(function* () {
+    const fromEnvironment = environment.LLM4TS_MCP_TOKEN?.trim() ?? ""
+    const fromFile =
+      fromEnvironment.length === 0 && Option.isSome(flags.tokenFile)
+        ? ((yield* readFile(resolve(cwd, flags.tokenFile.value)))?.trim() ?? "")
+        : ""
+    const token = fromEnvironment.length > 0 ? fromEnvironment : fromFile
+    if (token.length === 0) {
+      return yield* usage("--http needs a token: LLM4TS_MCP_TOKEN or --token-file")
+    }
+    const port = Option.getOrElse(flags.port, () => 4321)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      return yield* usage("--port must be between 0 and 65535")
+    }
+    return {
+      _tag: "http" as const,
+      host: Option.getOrElse(flags.host, () => "127.0.0.1"),
+      port,
+      token
+    }
+  })
+
+const reposFrom = (
+  flags: McpFlags,
+  environment: Readonly<Record<string, string | undefined>>,
+  cwd: string,
+  readFile: (path: string) => Effect.Effect<string | undefined>
+): Effect.Effect<OperatorConfig["repos"], ShellUsageError> =>
+  Effect.gen(function* () {
+    if (flags.repo.length > 0) {
+      return flags.repo.map((path) => {
+        const absolute = resolve(cwd, path)
+        return { id: basename(absolute), path: absolute }
+      })
+    }
+    const configHome =
+      environment.XDG_CONFIG_HOME !== undefined && environment.XDG_CONFIG_HOME.length > 0
+        ? environment.XDG_CONFIG_HOME
+        : join(environment.HOME ?? homedir(), ".config")
+    const configPath = join(configHome, "llm4ts", "mcp.json")
+    const raw = yield* readFile(configPath)
+    if (raw === undefined) {
+      return yield* usage("mcp needs --repo <path> or ~/.config/llm4ts/mcp.json")
+    }
+    const file = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(McpConfigFile))(raw).pipe(
+      Effect.mapError(() => usage(`${configPath} is not a valid mcp config`))
+    )
+    if (file.repos.length === 0) {
+      return yield* usage("mcp needs --repo <path> or ~/.config/llm4ts/mcp.json")
+    }
+    const badId = file.repos.find(({ id }) => !repoIdPattern.test(id))
+    if (badId !== undefined) {
+      return yield* usage(
+        `${configPath}: repository id "${badId.id}" must match ${repoIdPattern.source}`
+      )
+    }
+    return file.repos.map(({ id, path }) => ({ id, path: resolve(cwd, path) }))
+  })

package/src/OperatorNode.ts

@@ -0,0 +1,147 @@
+import { readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import type * as Cause from "effect/Cause"
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import type { ServeError } from "effect/http/HttpServerError"
+import type { PersistenceError } from "@llm4ts/flow/FlowError"
+import { nodeListTraces } from "@llm4ts/runner/Costs"
+import { collectDoctorReport } from "@llm4ts/runner/Doctor"
+import { httpProbe, rosterReport } from "@llm4ts/runner/ExecutorRoster"
+import { interruptOnSignal, type SignalSource } from "@llm4ts/runner/FlowRunner"
+import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
+import { nodeTranscriptFiles } from "@llm4ts/runner/Transcripts"
+import { nodeListEpics } from "@llm4ts/runner/Watch"
+import { discoverFlows, type FlowTierPaths } from "./FlowCatalog.ts"
+import { nodeFlowProcess, type FlowProcessShape } from "./FlowProcess.ts"
+import type { OperatorConfig } from "./OperatorConfig.ts"
+import { runOperatorServer } from "./OperatorServer.ts"
+import type { OperatorDeps } from "./OperatorTools.ts"
+import { makeRunSupervisor } from "./RunSupervisor.ts"
+
+/**
+ * The Node side of `llm4ts mcp` (ADR 0041): the operator's dependencies over
+ * the real file system and processes, and `runMcp`, which serves until the
+ * server fails or a SIGINT/SIGTERM interrupts it, then stops the flows it
+ * started before returning.
+ */
+
+/** Everything `runMcp` needs besides the run supervisor, which it builds itself. */
+export interface McpRuntime<E> {
+  readonly operator: Omit<OperatorDeps, "supervisor">
+  readonly flowProcess: FlowProcessShape
+  /** The server; `runOperatorServer` on Node, a stand-in in tests. */
+  readonly serve: (config: OperatorConfig, deps: OperatorDeps) => Effect.Effect<never, E>
+  /** How long stopping a run waits after SIGINT before SIGTERM; the supervisor's default when absent. */
+  readonly graceMs?: number
+}
+
+/**
+ * Serves the operator until the server ends or a signal arrives. The first
+ * SIGINT or SIGTERM interrupts the server; closing the scope then runs the
+ * supervisor's finalizer, which stops every flow it started. A second signal
+ * exits at once (130 or 143). The handlers are removed on the way out.
+ */
+export const runMcp = <E>(
+  config: OperatorConfig,
+  runtime: McpRuntime<E>,
+  signals: SignalSource
+): Effect.Effect<void, E | PersistenceError> => {
+  const disposers: Array<() => void> = []
+  return Effect.scoped(
+    Effect.gen(function* () {
+      const supervisor = yield* makeRunSupervisor({
+        repos: config.repos,
+        environment: runtime.operator.environment,
+        files: runtime.operator.files,
+        process: runtime.flowProcess,
+        parallelRuns: config.parallelRuns,
+        ...(runtime.graceMs === undefined ? {} : { graceMs: runtime.graceMs })
+      })
+      const fiber = yield* Effect.forkScoped(
+        runtime.serve(config, { ...runtime.operator, supervisor })
+      )
+      disposers.push(interruptOnSignal(fiber, signals, "SIGINT"))
+      disposers.push(interruptOnSignal(fiber, signals, "SIGTERM"))
+      return yield* Fiber.join(fiber)
+    })
+  ).pipe(
+    Effect.ensuring(
+      Effect.sync(() => {
+        for (const dispose of disposers) dispose()
+      })
+    )
+  )
+}
+
+/** A file's text, or `undefined` when it cannot be read (the `mcp` config and token file). */
+export const nodeRead = (path: string): Effect.Effect<string | undefined> =>
+  Effect.sync(() => {
+    try {
+      return readFileSync(path, "utf8")
+    } catch {
+      return undefined
+    }
+  })
+
+/**
+ * Relative paths of every regular file under a directory, recursively; never
+ * directory names, and none when the directory is absent or unreadable.
+ */
+export const nodeListFiles = (directory: string): ReadonlyArray<string> => {
+  const found: Array<string> = []
+  const walk = (relative: string): void => {
+    let names: ReadonlyArray<{
+      readonly name: string
+      isDirectory(): boolean
+      isFile(): boolean
+    }>
+    try {
+      names = readdirSync(join(directory, relative), { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of names) {
+      const path = relative.length === 0 ? entry.name : join(relative, entry.name)
+      if (entry.isDirectory()) {
+        walk(path)
+      } else if (entry.isFile()) {
+        found.push(path)
+      }
+    }
+  }
+  walk("")
+  return found.sort()
+}
+
+/**
+ * The operator's dependencies on Node. `tierPaths` gives the flow tiers for a
+ * repository (the CLI's `shellTierPaths`, passed in to keep this module free
+ * of the CLI).
+ */
+export const nodeOperatorRuntime = (
+  config: OperatorConfig,
+  tierPaths: (repoPath: string) => FlowTierPaths,
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): McpRuntime<ServeError | Cause.IllegalArgumentError> => ({
+  operator: {
+    config,
+    files: nodePlainFileStore,
+    listTraces: nodeListTraces,
+    listEpics: nodeListEpics,
+    listFiles: nodeListFiles,
+    transcripts: nodeTranscriptFiles,
+    doctor: collectDoctorReport(),
+    roster: (repoPath) =>
+      rosterReport({ files: nodePlainFileStore, environment, workDir: repoPath }),
+    probe: httpProbe,
+    flows: (repoPath) =>
+      discoverFlows(tierPaths(repoPath)).pipe(Effect.provide(NodeFileSystem.layer)),
+    now: Clock.currentTimeMillis,
+    environment
+  },
+  flowProcess: nodeFlowProcess,
+  serve: runOperatorServer
+})

package/src/OperatorRuns.ts

@@ -0,0 +1,270 @@
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { EpicRun, epicRunsPath } from "@llm4ts/flow/EpicRuns"
+import { describeFlowError } from "@llm4ts/flow/FlowError"
+import { TraceLine } from "@llm4ts/flow/FlowRecorder"
+import {
+  OperatorRun,
+  ReadFailed,
+  UnknownEpic,
+  UnknownRun,
+  type OperatorRunState
+} from "@llm4ts/flow/OperatorSchemas"
+import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { readTrace } from "@llm4ts/flow/Replay"
+import { TraceUnreadable } from "@llm4ts/runner/RunReaders"
+import type { OperatorConfig } from "./OperatorConfig.ts"
+import type { RunSupervisorShape } from "./RunSupervisor.ts"
+
+/**
+ * Where the operator finds a run: the supervisor's registry first, then each
+ * served repository's epic `runs.jsonl` files and `.llm4ts/trace-*.jsonl`
+ * traces. A client never names a path; epics and runs are ids found on disk.
+ */
+
+/** What run lookup reads; the operator's full dependency record extends it. */
+export interface RunLookupDeps {
+  readonly config: OperatorConfig
+  readonly files: PlainFileStoreShape
+  /** Absolute trace paths under one `.llm4ts/` directory. */
+  readonly listTraces: (directory: string) => ReadonlyArray<string>
+  /** Folder names under `.llm4ts/epics/`. */
+  readonly listEpics: (directory: string) => ReadonlyArray<string>
+  readonly supervisor: RunSupervisorShape
+}
+
+export interface Repo {
+  readonly id: string
+  readonly path: string
+}
+
+export const stateRoot = (repo: Repo): string => join(repo.path, ".llm4ts")
+export const epicsDir = (repo: Repo): string => join(stateRoot(repo), "epics")
+export const transcriptsDir = (repo: Repo, runId: string): string =>
+  join(stateRoot(repo), "transcripts", runId)
+
+export const readFailed = (error: unknown): ReadFailed =>
+  ReadFailed.make({ message: describeFlowError(error) })
+
+/** The epic's state folder, only for an id found on disk, so no client text becomes a path. */
+export const epicDirOf = (
+  deps: RunLookupDeps,
+  repo: Repo,
+  epic: string
+): Effect.Effect<string, UnknownEpic> =>
+  deps.listEpics(epicsDir(repo)).includes(epic)
+    ? Effect.succeed(join(epicsDir(repo), epic))
+    : Effect.fail(UnknownEpic.make({ message: `unknown epic '${epic}' in ${repo.id}` }))
+
+const decodeEpicRun = Schema.decodeUnknownOption(Schema.fromJsonString(EpicRun))
+
+/**
+ * An epic's runs, oldest first. A missing file is no runs and a torn last line
+ * (a write in progress) is skipped, but any other line that does not decode
+ * fails `ReadFailed` naming the file.
+ */
+export const readEpicRunsStrict = (
+  files: PlainFileStoreShape,
+  stateDir: string
+): Effect.Effect<ReadonlyArray<EpicRun>, ReadFailed> => {
+  const path = epicRunsPath(stateDir)
+  return files.read(path).pipe(
+    Effect.mapError(readFailed),
+    Effect.flatMap((contents) => {
+      const rows = (contents ?? "").split("\n").filter((row) => row.trim().length > 0)
+      const runs: Array<EpicRun> = []
+      for (const [index, row] of rows.entries()) {
+        const decoded = Option.getOrUndefined(decodeEpicRun(row))
+        if (decoded !== undefined) {
+          runs.push(decoded)
+        } else if (index < rows.length - 1) {
+          return Effect.fail(
+            ReadFailed.make({ message: `malformed ${path}:${index + 1}: not an epic run record` })
+          )
+        }
+      }
+      return Effect.succeed(runs)
+    })
+  )
+}
+
+export interface EpicRunEntry {
+  readonly epic: string
+  readonly dir: string
+  readonly run: EpicRun
+}
+
+export const epicRunsOf = (
+  deps: RunLookupDeps,
+  repo: Repo
+): Effect.Effect<ReadonlyArray<EpicRunEntry>, ReadFailed> =>
+  Effect.forEach(deps.listEpics(epicsDir(repo)), (epic) => {
+    const dir = join(epicsDir(repo), epic)
+    return readEpicRunsStrict(deps.files, dir).pipe(
+      Effect.map((runs) => runs.map((run) => ({ epic, dir, run })))
+    )
+  }).pipe(Effect.map((all) => all.flat()))
+
+const decodeTraceLine = Schema.decodeUnknownOption(Schema.fromJsonString(TraceLine))
+
+export interface TraceHead {
+  readonly runId: string
+  readonly startedAt: number
+  readonly ended: boolean
+}
+
+/** The run a trace belongs to and whether it ended, from its first and last lines. */
+export const traceHead = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<TraceHead | undefined> =>
+  files.read(path).pipe(
+    Effect.catch(() => Effect.succeed(undefined)),
+    Effect.map((contents) => {
+      const rows = (contents ?? "").split(/\r?\n/u).filter((row) => row.trim().length > 0)
+      const first = Option.getOrUndefined(decodeTraceLine(rows[0] ?? ""))
+      if (first === undefined) return undefined
+      const last = Option.getOrUndefined(decodeTraceLine(rows[rows.length - 1] ?? ""))
+      return { runId: first.runId, startedAt: first.timestamp, ended: last?.kind === "RunEnded" }
+    })
+  )
+
+export const traceState = (head: TraceHead | undefined): OperatorRunState =>
+  head === undefined ? "lost" : head.ended ? "exited" : "running"
+
+export interface ResolvedRun {
+  readonly runId: string
+  readonly repo: Repo
+  readonly flow: string
+  readonly state: OperatorRunState
+  readonly tracePath: string
+  readonly supervised?: OperatorRun
+}
+
+/** A run id through the supervisor first, then each repository's epic runs and traces. */
+export const resolveRun = (
+  deps: RunLookupDeps,
+  runId: string
+): Effect.Effect<ResolvedRun, UnknownRun | ReadFailed> =>
+  Effect.gen(function* () {
+    const supervised = yield* deps.supervisor.get(runId)
+    if (supervised !== undefined) {
+      const repo = deps.config.repos.find((candidate) => candidate.id === supervised.repo)
+      if (repo === undefined) {
+        return yield* UnknownRun.make({
+          message: `run ${runId} belongs to repo '${supervised.repo}', which this server does not serve`
+        })
+      }
+      if (supervised.tracePath === undefined) {
+        return yield* UnknownRun.make({ message: `run ${runId} has no trace yet` })
+      }
+      return {
+        runId,
+        repo,
+        flow: supervised.flow,
+        state: supervised.state,
+        tracePath: supervised.tracePath,
+        supervised
+      }
+    }
+    for (const repo of deps.config.repos) {
+      for (const entry of yield* epicRunsOf(deps, repo)) {
+        if (entry.run.runId === runId) {
+          const head = yield* traceHead(deps.files, entry.run.tracePath)
+          return {
+            runId,
+            repo,
+            flow: "?",
+            state: traceState(head),
+            tracePath: entry.run.tracePath
+          }
+        }
+      }
+      for (const path of deps.listTraces(stateRoot(repo))) {
+        const head = yield* traceHead(deps.files, path)
+        if (head?.runId === runId) {
+          return { runId, repo, flow: "?", state: traceState(head), tracePath: path }
+        }
+      }
+    }
+    return yield* UnknownRun.make({ message: `unknown run '${runId}'` })
+  })
+
+/** The epic a run worked on: the epic whose `runs.jsonl` lists it. */
+export const epicOfRun = (
+  deps: RunLookupDeps,
+  run: ResolvedRun
+): Effect.Effect<EpicRunEntry | undefined, ReadFailed> =>
+  Effect.map(epicRunsOf(deps, run.repo), (entries) =>
+    entries.find((entry) => entry.run.runId === run.runId || entry.run.tracePath === run.tracePath)
+  )
+
+/** Runs found on disk (epic run lists and traces) that the supervisor does not hold. */
+export const discoveredRuns = (
+  deps: RunLookupDeps,
+  repo: Repo,
+  known: ReadonlySet<string>
+): Effect.Effect<ReadonlyArray<OperatorRun>, ReadFailed> =>
+  Effect.gen(function* () {
+    const found = new Map<string, OperatorRun>()
+    const add = (runId: string, tracePath: string, startedAt: number, state: OperatorRunState) => {
+      if (known.has(runId) || found.has(runId)) return
+      found.set(
+        runId,
+        new OperatorRun({
+          runId,
+          repo: repo.id,
+          flow: "?",
+          args: [],
+          knobs: {},
+          startedAt,
+          tracePath,
+          logDir: "",
+          state
+        })
+      )
+    }
+    for (const entry of yield* epicRunsOf(deps, repo)) {
+      const head = yield* traceHead(deps.files, entry.run.tracePath)
+      add(entry.run.runId, entry.run.tracePath, entry.run.startedAt, traceState(head))
+    }
+    for (const path of deps.listTraces(stateRoot(repo))) {
+      const head = yield* traceHead(deps.files, path)
+      if (head !== undefined) add(head.runId, path, head.startedAt, traceState(head))
+    }
+    return [...found.values()]
+  })
+
+/**
+ * A run's trace lines. A supervised run whose trace file does not exist yet
+ * (the flow has not written its first line) reads as an empty trace; any other
+ * missing or unreadable trace fails `TraceUnreadable`.
+ */
+export const runTraceLines = (
+  files: PlainFileStoreShape,
+  run: ResolvedRun
+): Effect.Effect<ReadonlyArray<TraceLine>, TraceUnreadable> =>
+  Effect.gen(function* () {
+    if (yield* tracePending(files, run)) return []
+    return yield* readTrace(files, run.tracePath).pipe(
+      Effect.mapError((error) =>
+        TraceUnreadable.make({ path: run.tracePath, message: describeFlowError(error) })
+      )
+    )
+  })
+
+/** Whether the run is supervised and its flow has not written a trace yet. */
+export const tracePending = (
+  files: PlainFileStoreShape,
+  run: ResolvedRun
+): Effect.Effect<boolean, TraceUnreadable> =>
+  run.supervised === undefined
+    ? Effect.succeed(false)
+    : files.read(run.tracePath).pipe(
+        Effect.map((contents) => contents === undefined),
+        Effect.mapError((error) =>
+          TraceUnreadable.make({ path: run.tracePath, message: describeFlowError(error) })
+        )
+      )