@llm4ts/runner 2.44.1 → 2.46.0

package/src/FlowRunner.ts

@@ -5,6 +5,7 @@ import * as Cause from "effect/Cause"
 import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
+import * as Fiber from "effect/Fiber"
 import * as Ref from "effect/Ref"
 import type * as Scope from "effect/Scope"
 import type { ConnectorConfig } from "@llm4ts/core/ConnectorConfig"
@@ -82,6 +83,7 @@ import { makeJudgmentLog, type JudgmentLogShape } from "@llm4ts/flow/JudgmentLog
 import { makeGitHubTool } from "@llm4ts/flow/GitHubTool"
 import { makeGitTool } from "@llm4ts/flow/GitTool"
 import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { ignoringRunState } from "@llm4ts/flow/RunState"
 import { makeTransientRetry } from "@llm4ts/flow/TransientRetry"
 import {
   Exclusion,
@@ -147,6 +149,16 @@ export interface NodeConnectorDependencies {
   readonly geminiCli: GeminiCliExecutorShape
 }
 
+/**
+ * The dependencies with the run-state rule on their file store: the first
+ * write under any `.llm4ts/` leaves a `.gitignore` there, so a trace, a
+ * plan or a transcript is never staged by a flow commit (`RunState`).
+ */
+const withRunStateIgnore = (dependencies: FlowRunnerDependencies): FlowRunnerDependencies => ({
+  ...dependencies,
+  files: ignoringRunState(dependencies.files)
+})
+
 export const nodeFlowRunnerDependencies = (): FlowRunnerDependencies => ({
   process: nodeProcessExecutor,
   files: nodePlainFileStore,
@@ -223,6 +235,14 @@ export interface FlowRunnerOptions {
    * roster files); `"none"` runs with one executor per seat.
    */
   readonly roster?: RosterDocument | "none"
+  /**
+   * Globs, relative to each seat's working directory, every CLI seat of
+   * the run is denied (`CliConnectorConfig.deniedPaths`). Default: the
+   * run's own state, `.llm4ts/**`. A flow whose coder writes there on
+   * purpose (port-guide's trial ports) passes `[]`; a seat that names its
+   * own list keeps it.
+   */
+  readonly deniedPaths?: ReadonlyArray<string>
 }
 
 export interface FlowRunnerBundle {
@@ -329,12 +349,34 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
       : config
 })
 
+const nonBlank = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim() === "" ? undefined : value
+
+/**
+ * The run id and trace path a parent process (the MCP operator server) hands
+ * to a child run. Explicit options win; blank variables count as unset.
+ */
+export const runIdentityFromEnvironment = (
+  options: Pick<FlowRunnerOptions, "runId" | "tracePath">,
+  environment: Readonly<Record<string, string | undefined>>
+): { readonly runId?: string; readonly tracePath?: string } => {
+  const runId = nonBlank(options.runId) ?? nonBlank(environment["LLM4TS_RUN_ID"])
+  const tracePath = nonBlank(options.tracePath) ?? nonBlank(environment["LLM4TS_TRACE_PATH"])
+  return {
+    ...(runId === undefined ? {} : { runId }),
+    ...(tracePath === undefined ? {} : { tracePath })
+  }
+}
+
 export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeContext")(function* (
   options: FlowRunnerOptions,
-  dependencies: FlowRunnerDependencies
+  given: FlowRunnerDependencies
 ): Effect.fn.Return<FlowRunnerBundle, FlowError, Scope.Scope> {
+  const dependencies = withRunStateIgnore(given)
   const events = yield* makeFlowEventHub()
-  const runId = options.runId ?? `run-${(yield* Clock.currentTimeMillis).toString()}`
+  const runId =
+    runIdentityFromEnvironment(options, options.environment ?? process.env).runId ??
+    `run-${(yield* Clock.currentTimeMillis).toString()}`
   // `llm4ts run --transcript`: what each seat is told and answers, per story,
   // in its own files — never in the trace.
   const transcriptOn =
@@ -391,6 +433,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
         readonly readOnlyEnforcement: string
         readonly effort: string
         readonly isolatedHeadless: string
+        readonly pathDeny: string
       }
     }
   ): Effect.Effect<void> => {
@@ -428,6 +471,24 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
             : "nothing reaches the harness")
       )
     }
+    // The run state (ADR 0027 amendment): a harness with no per-path deny
+    // rule keeps the model out of `.llm4ts/` by the contract text alone.
+    if (
+      configuration instanceof CliConnectorConfig &&
+      configuration.deniedPaths !== undefined &&
+      configuration.deniedPaths.length > 0 &&
+      connector.capabilities.pathDeny !== "enforced"
+    ) {
+      const paths = configuration.deniedPaths.join(", ")
+      notes.push(
+        `'${name}' is asked to keep out of ${paths} (the run's own state: traces, plans, ` +
+          "transcripts), but its harness " +
+          (connector.capabilities.pathDeny === "partial"
+            ? "denies it by rule, not at the filesystem — a shell command that spells the path " +
+              "another way can still reach it"
+            : "has no per-path deny rule — only the contract text in its prompt keeps it out")
+      )
+    }
     return Effect.forEach(
       notes,
       (detail) => events.publish(FlowEventsValues.CapabilityUnenforceable(detail)),
@@ -545,12 +606,16 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
     Scope.Scope
   > {
     const environment = options.environment ?? process.env
-    const coder = yield* resolveSeat(prepareConnector(bridged(options.coder), workDir, environment))
+    const coder = yield* resolveSeat(
+      prepareConnector(bridged(options.coder), workDir, environment, options.deniedPaths)
+    )
     const reasoningService = yield* resolveSeat(
-      prepareConnector(bridged(reasoning), workDir, environment)
+      prepareConnector(bridged(reasoning), workDir, environment, options.deniedPaths)
     )
     const reviewers = yield* Effect.forEach(options.reviewers ?? [], (configuration) =>
-      resolveSeat(prepareConnector(bridged(configuration), workDir, environment))
+      resolveSeat(
+        prepareConnector(bridged(configuration), workDir, environment, options.deniedPaths)
+      )
     )
     // The judgment seat is the reasoner with its tools taken away: a judge
     // reads, it does not act. Over an API reasoner (no tools to take) it is
@@ -561,7 +626,9 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
     const judgmentSeat =
       judgmentConfig === undefined
         ? reasoningService
-        : yield* resolveSeat(prepareConnector(bridged(judgmentConfig), workDir, environment))
+        : yield* resolveSeat(
+            prepareConnector(bridged(judgmentConfig), workDir, environment, options.deniedPaths)
+          )
     const judgment = yield* judgmentFor(judgmentSeat, judgmentConfig ?? reasoning, environment)
     return { coder, reasoning: reasoningService, reviewers, judge: judgmentSeat, judgment }
   })
@@ -720,7 +787,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
             })
           }
           const seat: RosterSeat = yield* resolveSeat(
-            prepareConnector(bridged(configuration), workDir, runEnvironment)
+            prepareConnector(bridged(configuration), workDir, runEnvironment, options.deniedPaths)
           ).pipe(ScopeModule.provide(runScope))
           seatCache.set(key, seat)
           return seat
@@ -918,8 +985,9 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   bundle: FlowRunnerBundle,
   options: FlowRunnerOptions,
   body: (context: FlowContextShape) => Effect.Effect<A, E, R>,
-  dependencies: FlowRunnerDependencies = nodeFlowRunnerDependencies()
+  given: FlowRunnerDependencies = nodeFlowRunnerDependencies()
 ): Effect.fn.Return<A, E | FlowError, R | Scope.Scope> {
+  const dependencies = withRunStateIgnore(given)
   const startedAt = yield* Clock.currentTimeMillis
   const environment = options.environment ?? process.env
   const verbosity = options.verbosity ?? "Normal"
@@ -928,7 +996,7 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   // per run, flushed when the run's scope closes.
   const otel = otelConfig(environment)
   const tracePath =
-    options.tracePath ??
+    runIdentityFromEnvironment(options, environment).tracePath ??
     (persistRun ? join(options.workDir, ".llm4ts", `trace-${startedAt}.jsonl`) : undefined)
   const costLedgerPath =
     options.costLedgerPath ??
@@ -977,11 +1045,7 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
         : `executors ${bundle.roster.executors.map(describeExecutor).join(", ")} (roster in force: the flow's own seat choices are not used)`
     yield* surface.log(palette.info(`${seats} · ${options.workDir}`))
     if (tracePath !== undefined) {
-      yield* surface.log(
-        palette.info(
-          `trace ${tracePath}${options.runId === undefined ? "" : ` · run ${options.runId}`}`
-        )
-      )
+      yield* surface.log(palette.info(`trace ${tracePath} · run ${bundle.runId}`))
     }
     const where = otelSummary(otel)
     if (where !== undefined) {
@@ -1012,7 +1076,7 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
           const at = new Date(yield* Clock.currentTimeMillis).toISOString()
           yield* checkCostBudget(
             makeCostRecord({
-              runId: options.runId ?? "run",
+              runId: bundle.runId,
               at,
               repo: options.workDir,
               prompt: options.userPrompt,
@@ -1110,6 +1174,22 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
         ),
         Effect.andThen(tree === undefined ? Effect.void : tree.close),
         Effect.andThen(appendLedger),
+        // A trace that lost lines says so here, once; the ledger line above
+        // is complete, and `llm4ts costs` reads it for this run's remainder.
+        Effect.andThen(
+          recorder === undefined
+            ? Effect.void
+            : Effect.flatMap(recorder.shortfall, (shortfall) =>
+                shortfall === undefined
+                  ? Effect.void
+                  : surface.log(
+                      palette.fail(
+                        `trace short: ${shortfall.lines} line${shortfall.lines === 1 ? "" : "s"} not recorded after "${shortfall.reason}" — ` +
+                          "the cost ledger line is complete, and llm4ts costs reads it for this run"
+                      )
+                    )
+              )
+        ),
         Effect.andThen(surface.setStatus(undefined)),
         Effect.andThen(tracker.summary),
         Effect.flatMap((summary) => surface.log(`\n${summary}`))
@@ -1189,8 +1269,83 @@ export const runNode = <A, E, R>(
 const mainErrorMessage = (error: unknown): string =>
   error instanceof Error && error.message.length > 0 ? error.message : String(error)
 
+export type InterruptSignal = "SIGINT" | "SIGTERM"
+
+export interface SignalSource {
+  readonly once: (signal: InterruptSignal, handler: () => void) => void
+  readonly off: (signal: InterruptSignal, handler: () => void) => void
+  readonly exit: (code: number) => void
+}
+
+const signalExitCode: Record<InterruptSignal, number> = { SIGINT: 130, SIGTERM: 143 }
+
+/**
+ * The first of the given signals (SIGINT by default) interrupts the fiber
+ * (finalizers run, the trace ends `interrupted`); any later one exits at
+ * once, 130 for SIGINT and 143 for SIGTERM. The handlers re-arm themselves
+ * after the first signal. Returns a disposer that removes whichever handlers
+ * are armed.
+ */
+export const interruptOnSignal = <A, E>(
+  fiber: Fiber.Fiber<A, E>,
+  signals: SignalSource,
+  signal: InterruptSignal | ReadonlyArray<InterruptSignal> = "SIGINT"
+): (() => void) => {
+  const watched: ReadonlyArray<InterruptSignal> = typeof signal === "string" ? [signal] : signal
+  const seconds = new Map<InterruptSignal, () => void>(
+    watched.map((name) => [name, () => signals.exit(signalExitCode[name])])
+  )
+  const firsts = new Map<InterruptSignal, () => void>(
+    watched.map((name) => [
+      name,
+      () => {
+        for (const other of watched) {
+          const otherFirst = firsts.get(other)
+          if (otherFirst !== undefined) signals.off(other, otherFirst)
+          const second = seconds.get(other)
+          if (second !== undefined) signals.once(other, second)
+        }
+        Effect.runFork(Fiber.interrupt(fiber))
+      }
+    ])
+  )
+  const dispose = (): void => {
+    for (const name of watched) {
+      const first = firsts.get(name)
+      if (first !== undefined) signals.off(name, first)
+      const second = seconds.get(name)
+      if (second !== undefined) signals.off(name, second)
+    }
+  }
+  for (const [name, first] of firsts) signals.once(name, first)
+  // After an interrupt the handlers stay: a second signal must still kill a
+  // run whose finalizers hang. Otherwise they are removed when the fiber ends.
+  fiber.addObserver((exit) => {
+    if (!(Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause))) {
+      dispose()
+    }
+  })
+  return dispose
+}
+
+/**
+ * The signals `runFlowMain` stops on. SIGTERM counts like SIGINT, so a
+ * supervisor's or init system's stop ends the trace `interrupted` too.
+ */
+export const flowMainSignals: ReadonlyArray<InterruptSignal> = ["SIGINT", "SIGTERM"]
+
+const processSignals: SignalSource = {
+  once: (signal, handler) => {
+    process.once(signal, handler)
+  },
+  off: (signal, handler) => {
+    process.off(signal, handler)
+  },
+  exit: (code) => process.exit(code)
+}
+
 export const runFlowMain = <E>(program: Effect.Effect<void, E>): void => {
-  Effect.runFork(
+  const fiber = Effect.runFork(
     program.pipe(
       Effect.match({
         onFailure: (error) =>
@@ -1203,4 +1358,10 @@ export const runFlowMain = <E>(program: Effect.Effect<void, E>): void => {
       Effect.flatten
     )
   )
+  fiber.addObserver((exit) => {
+    if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) {
+      process.exitCode = 130
+    }
+  })
+  interruptOnSignal(fiber, processSignals, flowMainSignals)
 }

package/src/NodeGeminiCliExecutor.ts

@@ -8,7 +8,7 @@ import {
   GeminiCliExecutor,
   buildGeminiArgs,
   extractGeminiCliResponse,
-  geminiHarnessPolicyToml,
+  geminiHarnessPolicyFor,
   geminiProcessEnv,
   geminiSupportsAdminPolicy,
   geminiTurnLimitSettingsJson,
@@ -39,7 +39,7 @@ export const makeNodeGeminiCliExecutor = (
           ),
           (path) => geminiProcessEnv(context, path)
         )
-  // The harness policy (`geminiHarnessPolicyToml`) goes in with
+  // The harness policy (`geminiHarnessPolicyFor`) goes in with
   // `--admin-policy` on a CLI that lists the flag: `gemini --help` is asked
   // once, and an older CLI simply runs without it — an unknown flag would
   // fail every turn.
@@ -68,7 +68,7 @@ export const makeNodeGeminiCliExecutor = (
     Effect.flatMap(supportsAdminPolicy, (supported) =>
       supported
         ? Effect.map(
-            temporaryFiles.write("gemini-policy-", ".toml", geminiHarnessPolicyToml),
+            temporaryFiles.write("gemini-policy-", ".toml", geminiHarnessPolicyFor(context)),
             (path) => buildGeminiArgs(config, context, outputFormat, path)
           )
         : Effect.succeed(buildGeminiArgs(config, context, outputFormat))