@llm4ts/shell 2.45.0 → 2.47.0

package/src/OperatorActTools.ts

@@ -0,0 +1,407 @@
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Tool from "effect/ai/Tool"
+import * as Toolkit from "effect/ai/Toolkit"
+import { approveMarkdown } from "@llm4ts/flow/Approval"
+import { PersistenceError } from "@llm4ts/flow/FlowError"
+import {
+  InvalidKnob,
+  NotAllowed,
+  OperatorRun,
+  ReadFailed,
+  RunInProgress,
+  RunWaitResult,
+  UnknownEpic,
+  UnknownFlow,
+  UnknownRepo,
+  UnknownRun,
+  type OperatorKnobs,
+  type OperatorRunState
+} from "@llm4ts/flow/OperatorSchemas"
+import { retroApprovalOf, retroPaths } from "@llm4ts/flow/Retro"
+import { emptyTree } from "@llm4ts/runner/AgentTree"
+import {
+  TraceUnreadable,
+  foldTrace,
+  meaningfulEventsAfter,
+  runStatusOf,
+  type TraceFold
+} from "@llm4ts/runner/RunReaders"
+import { FlowLaunchError } from "./FlowProcess.ts"
+import { resolveRepo, type OperatorDeps } from "./OperatorTools.ts"
+import {
+  epicDirOf,
+  epicOfRun,
+  readEpicRunsStrict,
+  readFailed,
+  resolveRun,
+  tracePending,
+  type Repo
+} from "./OperatorRuns.ts"
+
+/**
+ * The operator's `run_wait` and act tools (`llm4ts mcp`, ADR 0041): waiting on
+ * a run without polling from the client, and starting, stopping, retro-ing and
+ * approving through the run supervisor. `run_wait` only reads, so it has its
+ * own toolkit the server registers beside the read tools; the act toolkit is
+ * registered only when the configuration allows runs or approvals.
+ */
+
+const repoParam = Schema.optional(Schema.String)
+
+// ---- run_wait -----------------------------------------------------------------------------
+
+export const runWaitTool = Tool.make("run_wait", {
+  description:
+    "Wait for a run's next meaningful events after sinceSeq: returns as soon as one appears or the run is no longer running, else after timeoutSeconds (default 120, at most 300) with no events.",
+  parameters: Schema.Struct({
+    runId: Schema.String,
+    sinceSeq: Schema.optional(Schema.Int),
+    timeoutSeconds: Schema.optional(Schema.Int)
+  }),
+  success: RunWaitResult,
+  failure: Schema.Union([UnknownRun, TraceUnreadable, ReadFailed])
+})
+  .annotate(Tool.Readonly, true)
+  .annotate(Tool.Destructive, false)
+
+export const waitToolkit = Toolkit.make(runWaitTool)
+
+const pollInterval = "500 millis"
+const defaultWaitSeconds = 120
+const maxWaitSeconds = 300
+
+const isActive = (state: OperatorRunState): boolean => state === "starting" || state === "running"
+
+const emptyFold = (): TraceFold => ({ lines: [], state: emptyTree(), seq: 0 })
+
+export const waitHandlers = (
+  deps: OperatorDeps
+): Toolkit.HandlersFrom<Toolkit.Tools<typeof waitToolkit>> =>
+  waitToolkit.of({
+    run_wait: ({ runId, sinceSeq, timeoutSeconds }) =>
+      Effect.gen(function* () {
+        const since = sinceSeq ?? 0
+        const timeoutMs =
+          Math.min(Math.max(0, timeoutSeconds ?? defaultWaitSeconds), maxWaitSeconds) * 1_000
+        const run = yield* resolveRun(deps, runId)
+        const epic = yield* epicOfRun(deps, run)
+        const startedAt = yield* Clock.currentTimeMillis
+        for (;;) {
+          const fold = (yield* tracePending(deps.files, run))
+            ? emptyFold()
+            : yield* foldTrace(deps.files, run.tracePath, epic?.dir)
+          // A supervised run's state is the supervisor's; a run found on disk ends with its trace.
+          const state: OperatorRunState =
+            run.supervised === undefined
+              ? fold.lines.some((line) => line.kind === "RunEnded")
+                ? "exited"
+                : run.state
+              : ((yield* deps.supervisor.get(runId))?.state ?? run.state)
+          const events = meaningfulEventsAfter(fold.lines, since)
+          const exited = !isActive(state)
+          const elapsed = (yield* Clock.currentTimeMillis) - startedAt
+          if (events.length > 0 || exited || elapsed >= timeoutMs) {
+            const status = runStatusOf(fold, { ...run, state }, yield* deps.now)
+            return RunWaitResult.make({
+              events,
+              seq: Math.max(fold.seq, since),
+              ...(status.ended === undefined ? {} : { ended: status.ended }),
+              exited,
+              summary: status.summary
+            })
+          }
+          yield* Effect.sleep(pollInterval)
+        }
+      })
+  })
+
+// ---- Act tools ----------------------------------------------------------------------------
+
+export const StartedRun = Schema.Struct({
+  runId: Schema.String,
+  tracePath: Schema.optionalKey(Schema.String),
+  pid: Schema.optionalKey(Schema.Int)
+})
+
+const startFailures = Schema.Union([
+  NotAllowed,
+  InvalidKnob,
+  UnknownRepo,
+  UnknownEpic,
+  UnknownRun,
+  UnknownFlow,
+  ReadFailed,
+  FlowLaunchError,
+  RunInProgress,
+  PersistenceError
+])
+
+const StartRunParams = Schema.Struct({
+  repo: repoParam,
+  flow: Schema.String,
+  task: Schema.optional(Schema.String),
+  epic: Schema.optional(Schema.String),
+  pack: Schema.optional(Schema.String),
+  executors: Schema.optional(Schema.Array(Schema.String)),
+  coder: Schema.optional(Schema.String),
+  judgeRounds: Schema.optional(Schema.Int),
+  mergeRevisions: Schema.optional(Schema.Int),
+  land: Schema.optional(Schema.String),
+  flags: Schema.optional(Schema.Array(Schema.String)),
+  requestId: Schema.optional(Schema.String)
+})
+
+export const startRunTool = Tool.make("start_run", {
+  description:
+    "Start a flow by name in the background with typed knobs; returns the run id at once. Repeating a call is safe only with the same requestId, which returns the run it already started; without one, every call starts a new run.",
+  parameters: StartRunParams,
+  success: StartedRun,
+  failure: startFailures
+}).annotate(Tool.Destructive, false)
+
+export const stopRunTool = Tool.make("stop_run", {
+  description:
+    "Stop a run this server started: SIGINT, then SIGTERM after a grace period; returns its final record.",
+  parameters: Schema.Struct({ runId: Schema.String }),
+  success: OperatorRun,
+  failure: Schema.Union([NotAllowed, UnknownRun])
+}).annotate(Tool.Destructive, true)
+
+export const retroStartTool = Tool.make("retro_start", {
+  description:
+    "Start epic-retro for an epic, optionally for one of its recorded runs; the retro report then waits for approve.",
+  parameters: Schema.Struct({
+    repo: repoParam,
+    epic: Schema.String,
+    run: Schema.optional(Schema.String)
+  }),
+  success: StartedRun,
+  failure: startFailures
+}).annotate(Tool.Destructive, false)
+
+export const approveTool = Tool.make("approve", {
+  description:
+    "Approve a retro report: ticks its approval marker so the next epic run applies its fixes.",
+  parameters: Schema.Struct({
+    repo: repoParam,
+    kind: Schema.Literals(["retro"]),
+    epic: Schema.String,
+    id: Schema.String
+  }),
+  success: Schema.Struct({ path: Schema.String, approved: Schema.Boolean }),
+  failure: Schema.Union([
+    NotAllowed,
+    UnknownRepo,
+    UnknownEpic,
+    UnknownRun,
+    ReadFailed,
+    PersistenceError
+  ])
+}).annotate(Tool.Destructive, false)
+
+export const actToolkit = Toolkit.make(startRunTool, stopRunTool, retroStartTool, approveTool)
+
+const knobsOf = (params: typeof StartRunParams.Type): OperatorKnobs => ({
+  ...(params.task === undefined ? {} : { task: params.task }),
+  ...(params.epic === undefined ? {} : { epic: params.epic }),
+  ...(params.pack === undefined ? {} : { pack: params.pack }),
+  ...(params.executors === undefined ? {} : { executors: params.executors }),
+  ...(params.coder === undefined ? {} : { coder: params.coder }),
+  ...(params.judgeRounds === undefined ? {} : { judgeRounds: params.judgeRounds }),
+  ...(params.mergeRevisions === undefined ? {} : { mergeRevisions: params.mergeRevisions }),
+  ...(params.land === undefined ? {} : { land: params.land }),
+  ...(params.flags === undefined ? {} : { flags: params.flags }),
+  ...(params.requestId === undefined ? {} : { requestId: params.requestId })
+})
+
+const namePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
+const packPattern = /^[\w.-]+(\/[\w.-]+)?$/u
+const branchPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/u
+
+const flagPattern = /^--[a-z][a-z0-9-]*(=[A-Za-z0-9][A-Za-z0-9._/-]*)?$/u
+const flagValuePattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/u
+/**
+ * Flags a client may never pass through `flags`, with or without `=value`.
+ * `-C` already fails the shape pattern; it is named so a looser pattern
+ * cannot reopen it.
+ */
+const reservedFlags: ReadonlyArray<string> = [
+  // Points the flow at another directory (`FlowArgs.ts`).
+  "--repo",
+  // Alias of --repo in the flow argument parser.
+  "-C",
+  // Reads the prompt from any file on the server.
+  "--prompt-file",
+  // Typed knob: epic.
+  "--epic",
+  // Typed knob: land.
+  "--land",
+  // Typed knob: judgeRounds.
+  "--judge-rounds",
+  // Typed knob: mergeRevisions.
+  "--merge-revisions",
+  // Lets soap flows send mutating calls to a real ESB.
+  "--allow-mutating",
+  // Auto-confirms prompts a human is meant to answer.
+  "--yes",
+  // Selects which environment's credentials a flow uses.
+  "--env",
+  // A filesystem path in epic-design.
+  "--target"
+]
+
+const reservedFlagOf = (entry: string): string | undefined =>
+  reservedFlags.find((flag) => entry === flag || entry.startsWith(`${flag}=`))
+
+/** Why a flags list is refused, or undefined when every entry has a safe shape. */
+const flagsProblem = (flags: ReadonlyArray<string>): string | undefined => {
+  let previousWasFlag = false
+  for (const entry of flags) {
+    const reserved = reservedFlagOf(entry)
+    if (reserved !== undefined) return `${reserved} may not be passed through flags`
+    const flag = flagPattern.exec(entry)
+    if (flag !== null) {
+      previousWasFlag = flag[1] === undefined
+      continue
+    }
+    if (!previousWasFlag || !flagValuePattern.test(entry)) {
+      return "every entry must be a --flag[=value] or a plain value right after a flag"
+    }
+    previousWasFlag = false
+  }
+  return undefined
+}
+
+const invalid = (knob: string, message: string): Effect.Effect<never, InvalidKnob> =>
+  Effect.fail(InvalidKnob.make({ knob, message }))
+
+/**
+ * Every client value that reaches the flow's argv or environment, checked
+ * before the supervisor sees it. Names stay names, never paths or flags:
+ * `pack` is a kit or kit/pack name (no `.`/`..` segment), `epic`, `coder` and
+ * executors are ids, `land` is a branch name. `task` is the flow's first
+ * positional argument, so it may not start with `-` (it would parse as a
+ * flag) or `@` (the flow parser reads `@<path>` as a prompt file on the
+ * server). `flags` is an allowlist of shapes: `--flag[=value]`, or a plain
+ * value right after a flag, never a reserved flag (`reservedFlags`).
+ */
+export const validateKnobs = (knobs: OperatorKnobs): Effect.Effect<OperatorKnobs, InvalidKnob> => {
+  if (
+    knobs.pack !== undefined &&
+    (!packPattern.test(knobs.pack) ||
+      knobs.pack.split("/").some((segment) => segment === "." || segment === ".."))
+  ) {
+    return invalid("pack", "pack must be a kit or kit/pack name, not a path")
+  }
+  if (knobs.epic !== undefined && !namePattern.test(knobs.epic)) {
+    return invalid("epic", "epic must be an epic id")
+  }
+  if (knobs.coder !== undefined && !namePattern.test(knobs.coder)) {
+    return invalid("coder", "coder must be an executor or connector id")
+  }
+  if (knobs.executors?.some((id) => !namePattern.test(id)) === true) {
+    return invalid("executors", "every executor must be an executor id")
+  }
+  if (knobs.land !== undefined && !branchPattern.test(knobs.land)) {
+    return invalid("land", "land must be a branch name")
+  }
+  const nonNegative = (value: number | undefined) =>
+    value === undefined || (Number.isInteger(value) && value >= 0)
+  if (!nonNegative(knobs.judgeRounds)) {
+    return invalid("judgeRounds", "judgeRounds must be an integer of 0 or more")
+  }
+  if (!nonNegative(knobs.mergeRevisions)) {
+    return invalid("mergeRevisions", "mergeRevisions must be an integer of 0 or more")
+  }
+  if (knobs.task !== undefined && (knobs.task.startsWith("-") || knobs.task.startsWith("@"))) {
+    return invalid("task", "task must not start with '-' or '@'")
+  }
+  const problem = knobs.flags === undefined ? undefined : flagsProblem(knobs.flags)
+  if (problem !== undefined) return invalid("flags", problem)
+  return Effect.succeed(knobs)
+}
+
+/** A run or retro id names one file, never a path. */
+const isPlainId = (id: string): boolean => /^[\w.-]+$/u.test(id) && id !== "." && id !== ".."
+
+export const actHandlers = (
+  deps: OperatorDeps
+): Toolkit.HandlersFrom<Toolkit.Tools<typeof actToolkit>> => {
+  const requireRun = deps.config.allowRun
+    ? Effect.void
+    : Effect.fail(NotAllowed.make({ message: "this server was not started with --allow-run" }))
+  const requireApprove = deps.config.allowApprove
+    ? Effect.void
+    : Effect.fail(NotAllowed.make({ message: "this server was not started with --allow-approve" }))
+
+  const startFlow = (repo: Repo, name: string, knobs: OperatorKnobs) =>
+    Effect.gen(function* () {
+      const flows = yield* deps.flows(repo.path).pipe(Effect.mapError(readFailed))
+      const flow = flows.find((candidate) => candidate.name === name)
+      if (flow === undefined) {
+        return yield* UnknownFlow.make({
+          message: `unknown flow '${name}' in ${repo.id}: list_flows names the flows it can start`
+        })
+      }
+      const run = yield* deps.supervisor.start({
+        repo,
+        flow: { name: flow.name, path: flow.path },
+        knobs,
+        baseEnvironment: deps.environment
+      })
+      return {
+        runId: run.runId,
+        ...(run.tracePath === undefined ? {} : { tracePath: run.tracePath }),
+        ...(run.pid === undefined ? {} : { pid: run.pid })
+      }
+    })
+
+  return actToolkit.of({
+    start_run: (params) =>
+      Effect.gen(function* () {
+        yield* requireRun
+        const repo = yield* resolveRepo(deps.config, params.repo)
+        const knobs = yield* validateKnobs(knobsOf(params))
+        return yield* startFlow(repo, params.flow, knobs)
+      }),
+
+    stop_run: ({ runId }) => Effect.andThen(requireRun, deps.supervisor.stop(runId)),
+
+    retro_start: ({ repo: repoId, epic, run }) =>
+      Effect.gen(function* () {
+        yield* requireRun
+        const repo = yield* resolveRepo(deps.config, repoId)
+        const dir = yield* epicDirOf(deps, repo, epic)
+        if (run !== undefined) {
+          const recorded = yield* readEpicRunsStrict(deps.files, dir)
+          if (!recorded.some((entry) => entry.runId === run)) {
+            return yield* UnknownRun.make({
+              message: `epic '${epic}' has no recorded run '${run}'`
+            })
+          }
+        }
+        // The client's values, checked like start_run's; the --epic flag itself is ours.
+        yield* validateKnobs({ epic, ...(run === undefined ? {} : { flags: ["--run", run] }) })
+        return yield* startFlow(repo, "epic-retro", {
+          flags: ["--epic", epic, ...(run === undefined ? [] : ["--run", run])]
+        })
+      }),
+
+    approve: ({ repo: repoId, epic, id }) =>
+      Effect.gen(function* () {
+        yield* requireApprove
+        const repo = yield* resolveRepo(deps.config, repoId)
+        const dir = yield* epicDirOf(deps, repo, epic)
+        const unknown = UnknownRun.make({ message: `no retro '${id}' for epic '${epic}'` })
+        if (!isPlainId(id)) return yield* unknown
+        const path = retroPaths(dir, id).report
+        const markdown = yield* deps.files.read(path).pipe(Effect.mapError(readFailed))
+        if (markdown === undefined) return yield* unknown
+        const approved = approveMarkdown(markdown)
+        if (approved !== markdown) yield* deps.files.writeAtomic(path, approved)
+        return { path, approved: retroApprovalOf(approved).approved }
+      })
+  })
+}

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
+})