@llm4ts/shell 2.45.0 → 2.47.0

package/flows/port-guide.js

@@ -85,7 +85,10 @@ const program = Effect.gen(function* () {
         coder,
         reasoning: asReadOnly(coder),
         reviewers: [asReadOnly(coder)],
-        environment: process.env
+        environment: process.env,
+        // The trial ports are written under `.llm4ts/port/trial/` by the
+        // coder itself, so this run lifts the default deny of the run state.
+        deniedPaths: []
     }, (context) => Effect.gen(function* () {
         const events = context.events;
         const repo = yield* makeNodeWorkspace(input.workDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.45.0",
+  "version": "2.47.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,18 @@
     "./CoderChoice": "./dist/CoderChoice.js",
     "./FlowCatalog": "./dist/FlowCatalog.js",
     "./FlowLaunch": "./dist/FlowLaunch.js",
+    "./FlowProcess": "./dist/FlowProcess.js",
     "./Menu": "./dist/Menu.js",
+    "./OperatorActTools": "./dist/OperatorActTools.js",
+    "./OperatorConfig": "./dist/OperatorConfig.js",
+    "./OperatorNode": "./dist/OperatorNode.js",
+    "./OperatorRuns": "./dist/OperatorRuns.js",
+    "./OperatorServer": "./dist/OperatorServer.js",
+    "./OperatorTools": "./dist/OperatorTools.js",
     "./Refine": "./dist/Refine.js",
+    "./RunSupervisor": "./dist/RunSupervisor.js",
     "./Package": "./dist/Package.js",
+    "./ShellErrors": "./dist/ShellErrors.js",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -52,9 +61,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/flow": "2.45.0",
-    "@llm4ts/core": "2.45.0",
-    "@llm4ts/runner": "2.45.0"
+    "@llm4ts/core": "2.47.0",
+    "@llm4ts/flow": "2.47.0",
+    "@llm4ts/runner": "2.47.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Cli.ts

@@ -50,13 +50,14 @@ import {
   type FlowTierPaths
 } from "./FlowCatalog.ts"
 import { launchFlow } from "./FlowLaunch.ts"
+import { mcpOptionsFrom } from "./OperatorConfig.ts"
+import { nodeOperatorRuntime, nodeRead, runMcp } from "./OperatorNode.ts"
 import { mainMenu } from "./Menu.ts"
 import { ModDir, refineSession } from "./Refine.ts"
 import { packageVersion } from "./Package.ts"
+import { ShellUsageError } from "./ShellErrors.ts"
 
-export class ShellUsageError extends Schema.TaggedError<ShellUsageError>()("ShellUsage", {
-  message: Schema.String
-}) {}
+export { ShellUsageError }
 
 export class ShellActionError extends Schema.TaggedError<ShellActionError>()("ShellAction", {
   message: Schema.String
@@ -981,6 +982,65 @@ const geminiBridgeCommand = Command.make(
   )
 )
 
+const mcpCommand = Command.make(
+  "mcp",
+  {
+    stdio: Flag.Boolean("stdio").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Speak MCP on stdin/stdout (the default transport)")
+    ),
+    http: Flag.Boolean("http").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Serve MCP over HTTP at /mcp; needs a bearer token from LLM4TS_MCP_TOKEN or --token-file"
+      )
+    ),
+    host: Flag.String("host").pipe(
+      Flag.optional,
+      Flag.withDescription("HTTP host to bind (default 127.0.0.1)")
+    ),
+    port: Flag.Int("port").pipe(Flag.optional, Flag.withDescription("HTTP port (default 4321)")),
+    tokenFile: Flag.String("token-file").pipe(
+      Flag.optional,
+      Flag.withDescription("File holding the HTTP bearer token (when LLM4TS_MCP_TOKEN is unset)")
+    ),
+    repo: Flag.String("repo").pipe(
+      Flag.atLeast(0),
+      Flag.withDescription(
+        "Repository to serve, repeatable (default: the repos in ~/.config/llm4ts/mcp.json)"
+      )
+    ),
+    allowRun: Flag.Boolean("allow-run").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Offer the tools that start, stop and resume flows")
+    ),
+    allowApprove: Flag.Boolean("allow-approve").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Offer the approve tool, which ticks a retro report's approval marker")
+    ),
+    parallelRuns: Flag.Int("parallel-runs").pipe(
+      Flag.optional,
+      Flag.withDescription(
+        "Flows that write a checkout and may run at once per repository (default 1)"
+      )
+    )
+  },
+  (flags) =>
+    Effect.gen(function* () {
+      const config = yield* mcpOptionsFrom(flags, process.env, process.cwd(), nodeRead)
+      // SIGINT/SIGTERM interrupt the server; runMcp then stops the flows it started.
+      yield* runMcp(
+        config,
+        nodeOperatorRuntime(config, (cwd) => shellTierPaths({ cwd })),
+        process
+      )
+    })
+).pipe(
+  Command.withDescription(
+    "Serve llm4ts to an MCP client (Grok Bot, Claude Code, Cursor): status, diagnosis and, when allowed, runs (ADR 0041)"
+  )
+)
+
 const doctorCommand = Command.make("doctor", {}, () =>
   Effect.gen(function* () {
     const report = yield* makeDoctorProgram()
@@ -1014,6 +1074,7 @@ export const shellCommand = Command.make("llm4ts", {}, () =>
     graphCommand,
     rosterCommand,
     geminiBridgeCommand,
+    mcpCommand,
     doctorCommand
   ])
 )

package/src/FlowLaunch.ts

@@ -1,46 +1,9 @@
-import { spawn, spawnSync } from "node:child_process"
-import { existsSync } from "node:fs"
+import { spawnSync } from "node:child_process"
 import { constants } from "node:os"
-import { dirname, join, resolve } from "node:path"
-import { fileURLToPath } from "node:url"
 import * as Effect from "effect/Effect"
-import * as Schema from "effect/Schema"
+import { FlowLaunchError, needsResolveFallback, nodeFlowProcess } from "./FlowProcess.ts"
 
-export class FlowLaunchError extends Schema.TaggedError<FlowLaunchError>()("FlowLaunch", {
-  message: Schema.String
-}) {}
-
-/**
- * True when the flow script cannot resolve `@llm4ts/runner` from its own
- * location — a global flow, a built-in copy, or a bare repository. Project
- * flows inside a repository that installs `@llm4ts/*` resolve their own pin
- * and need no help (the project-wins policy of ADR 0006). Implemented as the
- * same `node_modules` directory walk ESM resolution performs, so the check
- * stays honest under test runners that patch the module system.
- */
-export const needsResolveFallback = (flowPath: string): boolean => {
-  let directory = dirname(resolve(flowPath))
-  while (true) {
-    if (existsSync(join(directory, "node_modules", "@llm4ts", "runner", "package.json"))) {
-      return false
-    }
-    const parent = dirname(directory)
-    if (parent === directory) {
-      return true
-    }
-    directory = parent
-  }
-}
-
-// In the published package the hook is the compiled sibling; when running
-// from src (tests), it is the TypeScript source, which the child can load
-// because it always runs with type stripping enabled.
-const resolveFallbackUrl = (() => {
-  const compiled = new URL("./ResolveFallback.js", import.meta.url)
-  return existsSync(fileURLToPath(compiled))
-    ? compiled.href
-    : new URL("./ResolveFallback.ts", import.meta.url).href
-})()
+export { FlowLaunchError, needsResolveFallback }
 
 export interface LaunchFlowOptions {
   readonly flowPath: string
@@ -76,40 +39,31 @@ const restoreTerminal = (stdio: "inherit" | "ignore"): void => {
  * the child's exit code (`128 + signal` when terminated by a signal).
  */
 export const launchFlow = (options: LaunchFlowOptions): Effect.Effect<number, FlowLaunchError> =>
-  Effect.callback<number, FlowLaunchError>((resume) => {
+  Effect.gen(function* () {
     const environment = { ...(options.environment ?? process.env) }
     if (options.coder !== undefined) {
       environment.LLM4TS_CODER = options.coder
     }
-    const nodeArgs = ["--experimental-strip-types"]
-    if (needsResolveFallback(options.flowPath)) {
-      nodeArgs.push("--import", resolveFallbackUrl)
-    }
-    const child = spawn(process.execPath, [...nodeArgs, options.flowPath, ...options.taskArgs], {
-      stdio: options.stdio ?? "inherit",
-      env: environment,
-      ...(options.cwd === undefined ? {} : { cwd: options.cwd })
-    })
+    const stdio = options.stdio ?? "inherit"
     const ignoreSigint = (): void => {}
     process.on("SIGINT", ignoreSigint)
     const restoreSigint = (): void => {
       process.removeListener("SIGINT", ignoreSigint)
     }
-    child.on("error", (error) => {
-      restoreSigint()
-      resume(Effect.fail(new FlowLaunchError({ message: error.message })))
-    })
-    child.on("exit", (code, signal) => {
-      restoreSigint()
-      restoreTerminal(options.stdio ?? "inherit")
-      if (signal !== null) {
-        resume(Effect.succeed(128 + (constants.signals[signal] ?? 15)))
-      } else {
-        resume(Effect.succeed(code ?? 1))
+    return yield* Effect.gen(function* () {
+      const handle = yield* nodeFlowProcess.start({
+        flowPath: options.flowPath,
+        args: options.taskArgs,
+        environment,
+        stdio,
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd })
+      })
+      const exit = yield* handle.exited.pipe(Effect.onInterrupt(() => handle.signal("SIGINT")))
+      restoreTerminal(stdio)
+      if (exit.signal !== undefined) {
+        const number = Object.entries(constants.signals).find(([name]) => name === exit.signal)
+        return 128 + (number?.[1] ?? 15)
       }
-    })
-    return Effect.sync(() => {
-      restoreSigint()
-      child.kill("SIGINT")
-    })
+      return exit.code ?? 1
+    }).pipe(Effect.ensuring(Effect.sync(restoreSigint)))
   })

package/src/FlowProcess.ts

@@ -0,0 +1,239 @@
+import { spawn } from "node:child_process"
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+
+export class FlowLaunchError extends Schema.TaggedError<FlowLaunchError>()("FlowLaunch", {
+  message: Schema.String
+}) {}
+
+/**
+ * True when the flow script cannot resolve `@llm4ts/runner` from its own
+ * location — a global flow, a built-in copy, or a bare repository. Project
+ * flows inside a repository that installs `@llm4ts/*` resolve their own pin
+ * and need no help (the project-wins policy of ADR 0006). Implemented as the
+ * same `node_modules` directory walk ESM resolution performs, so the check
+ * stays honest under test runners that patch the module system.
+ */
+export const needsResolveFallback = (flowPath: string): boolean => {
+  let directory = dirname(resolve(flowPath))
+  while (true) {
+    if (existsSync(join(directory, "node_modules", "@llm4ts", "runner", "package.json"))) {
+      return false
+    }
+    const parent = dirname(directory)
+    if (parent === directory) {
+      return true
+    }
+    directory = parent
+  }
+}
+
+// In the published package the hook is the compiled sibling; when running
+// from src (tests), it is the TypeScript source, which the child can load
+// because it always runs with type stripping enabled.
+const resolveFallbackUrl = (() => {
+  const compiled = new URL("./ResolveFallback.js", import.meta.url)
+  return existsSync(fileURLToPath(compiled))
+    ? compiled.href
+    : new URL("./ResolveFallback.ts", import.meta.url).href
+})()
+
+export interface FlowProcessStart {
+  readonly flowPath: string
+  readonly args: ReadonlyArray<string>
+  readonly environment: Readonly<Record<string, string | undefined>>
+  readonly cwd?: string
+  /**
+   * File paths are opened for append by the Node implementation. `ignore`
+   * discards both streams (used by the terminal launcher's tests).
+   */
+  readonly stdio: "inherit" | "ignore" | { readonly stdout: string; readonly stderr: string }
+  /**
+   * Runs the child in its own process group, so a Ctrl-C on the parent's
+   * terminal or a whole-group kill reaches only the parent, which then stops
+   * the child once. The terminal launcher leaves it off: there the
+   * terminal's SIGINT must keep reaching the child.
+   */
+  readonly detached?: boolean
+}
+
+export interface FlowProcessExit {
+  readonly code: number | undefined
+  readonly signal: string | undefined
+}
+
+export interface FlowProcessHandle {
+  readonly pid: number
+  readonly exited: Effect.Effect<FlowProcessExit>
+  readonly signal: (signal: "SIGINT" | "SIGTERM") => Effect.Effect<void>
+}
+
+export interface FlowProcessShape {
+  readonly start: (options: FlowProcessStart) => Effect.Effect<FlowProcessHandle, FlowLaunchError>
+  readonly isAlive: (pid: number) => boolean
+  /** Signals a process this shape did not start (a run left by an earlier server). */
+  readonly signal: (pid: number, signal: "SIGINT" | "SIGTERM") => Effect.Effect<void>
+}
+
+export const flowNodeArgs = (flowPath: string): ReadonlyArray<string> => [
+  "--experimental-strip-types",
+  ...(needsResolveFallback(flowPath) ? ["--import", resolveFallbackUrl] : [])
+]
+
+const openAppend = (path: string): number => {
+  mkdirSync(dirname(path), { recursive: true })
+  return openSync(path, "a")
+}
+
+export const nodeFlowProcess: FlowProcessShape = {
+  start: (options) =>
+    Effect.callback<FlowProcessHandle, FlowLaunchError>((resume) => {
+      const exited = Deferred.makeUnsafe<FlowProcessExit>()
+      const fds: Array<number> = []
+      const closeAll = (): void => {
+        for (const fd of fds.splice(0)) {
+          try {
+            closeSync(fd)
+          } catch {
+            // already closed
+          }
+        }
+      }
+      let stdio: "inherit" | "ignore" | Array<"ignore" | number>
+      try {
+        if (typeof options.stdio === "string") {
+          stdio = options.stdio
+        } else {
+          const out = openAppend(options.stdio.stdout)
+          fds.push(out)
+          const err = openAppend(options.stdio.stderr)
+          fds.push(err)
+          stdio = ["ignore", out, err]
+        }
+      } catch (error) {
+        closeAll()
+        resume(
+          Effect.fail(
+            new FlowLaunchError({ message: error instanceof Error ? error.message : String(error) })
+          )
+        )
+        return Effect.void
+      }
+      const child = spawn(
+        process.execPath,
+        [...flowNodeArgs(options.flowPath), options.flowPath, ...options.args],
+        {
+          stdio,
+          env: { ...options.environment },
+          ...(options.detached === true ? { detached: true } : {}),
+          ...(options.cwd === undefined ? {} : { cwd: options.cwd })
+        }
+      )
+      closeAll()
+      let started = false
+      child.on("error", (error) => {
+        if (!started) {
+          resume(Effect.fail(new FlowLaunchError({ message: error.message })))
+        }
+      })
+      child.on("spawn", () => {
+        started = true
+        resume(
+          Effect.succeed({
+            pid: child.pid ?? 0,
+            exited: Deferred.await(exited),
+            signal: (signal) =>
+              Effect.sync(() => {
+                child.kill(signal)
+              })
+          })
+        )
+      })
+      child.on("exit", (code, signal) => {
+        Deferred.doneUnsafe(
+          exited,
+          Effect.succeed({ code: code ?? undefined, signal: signal ?? undefined })
+        )
+      })
+      return Effect.void
+    }),
+  isAlive: (pid) => {
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  },
+  signal: (pid, signal) =>
+    Effect.sync(() => {
+      try {
+        process.kill(pid, signal)
+      } catch {
+        // already gone (ESRCH) or not ours to signal
+      }
+    })
+}
+
+export interface FakeFlowProcess {
+  readonly process: FlowProcessShape
+  readonly started: Effect.Effect<ReadonlyArray<FlowProcessStart>>
+  readonly exit: (pid: number, exit: FlowProcessExit) => Effect.Effect<void>
+  readonly signals: Effect.Effect<ReadonlyArray<{ pid: number; signal: string }>>
+  readonly setAlive: (pid: number, alive: boolean) => Effect.Effect<void>
+}
+
+export const makeFakeFlowProcess = (): Effect.Effect<FakeFlowProcess> =>
+  Effect.gen(function* () {
+    const starts = yield* Ref.make<ReadonlyArray<FlowProcessStart>>([])
+    const signals = yield* Ref.make<ReadonlyArray<{ pid: number; signal: string }>>([])
+    const alive = yield* Ref.make<ReadonlySet<number>>(new Set())
+    const exits = new Map<number, Deferred.Deferred<FlowProcessExit>>()
+    let nextPid = 1000
+    const setMember = (pid: number, member: boolean) =>
+      Ref.update(alive, (set) => {
+        const next = new Set(set)
+        if (member) {
+          next.add(pid)
+        } else {
+          next.delete(pid)
+        }
+        return next
+      })
+    const process: FlowProcessShape = {
+      start: (options) =>
+        Effect.gen(function* () {
+          const pid = nextPid++
+          const exited = yield* Deferred.make<FlowProcessExit>()
+          exits.set(pid, exited)
+          yield* Ref.update(starts, (all) => [...all, options])
+          yield* setMember(pid, true)
+          return {
+            pid,
+            exited: Deferred.await(exited),
+            signal: (signal) => Ref.update(signals, (all) => [...all, { pid, signal }])
+          }
+        }),
+      isAlive: (pid) => Ref.getUnsafe(alive).has(pid),
+      signal: (pid, signal) => Ref.update(signals, (all) => [...all, { pid, signal }])
+    }
+    return {
+      process,
+      started: Ref.get(starts),
+      signals: Ref.get(signals),
+      exit: (pid, exit) =>
+        Effect.gen(function* () {
+          yield* setMember(pid, false)
+          const deferred = exits.get(pid)
+          if (deferred !== undefined) {
+            yield* Deferred.succeed(deferred, exit)
+          }
+        }),
+      setAlive: (pid, value) => setMember(pid, value)
+    }
+  })