@llm4ts/shell 2.7.0 → 2.8.0

package/flows/epic-stories.js

@@ -9,31 +9,40 @@
 // their models (pi: "provider/model"). The story plan is persisted under
 // .llm4ts/epics/<epic-id>/plan.md BEFORE any coder runs, and an existing
 // file wins over regeneration — editing it is the approval and the re-plan
-// path. Stories run in .llm4ts/worktrees/<story-id> under --concurrency
-// (default 3); a failed story skips its dependents (--fail-fast stops
-// instead). The epic branch is left in place; the board and the report
-// under .llm4ts/epics/<epic-id>/ carry ESTIMATED usage figures (ADR 0013).
+// path. Stories run in worktrees BESIDE the repository (<repo>.worktrees/
+// <epic-id>/<story-id>, LLM4TS_WORKTREE_ROOT to move them) under
+// --concurrency (default 3); a failed story puts its dependents on hold
+// (--fail-fast stops instead). The epic branch is left in place; the board
+// and the report under .llm4ts/epics/<epic-id>/ carry ESTIMATED usage
+// figures (ADR 0013).
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig";
 import { budget, cap } from "@llm4ts/flow/Context";
 import { makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
 import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
 import { FlowAborted, Info, asReadOnly, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runFlowMain, runNode, stage, withModel } from "@llm4ts/runner";
 import { implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
-import { combineTotals, epicIdFor, gateCommands, gatesIn, generateStoryPlan, judgeStory, parseEpicArgs, reasonerFromEnvironment, setupIn, storyCoderFromEnvironment, worktreeSetupCommand } from "./lib/epic-stories.js";
+import { awaitServer, combineTotals, epicIdFor, flagsFromEnvironment, gateCommands, gatesIn, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
 /** `LLM4TS_CODER_MODEL` / `LLM4TS_REASONING_MODEL`: pi takes `provider/model` (e.g. `openai-codex/gpt-5.5`). */
 const withOptionalModel = (config, model) => {
     const trimmed = model?.trim();
     return trimmed === undefined || trimmed.length === 0 ? config : withModel(config, trimmed);
 };
+/** Extra CLI flags on top of a preset's own (`LLM4TS_CODER_FLAGS`). */
+const withExtraFlags = (config, flags) => Object.keys(flags).length === 0
+    ? config
+    : CliConnectorConfig.make({ ...config, flags: { ...config.flags, ...flags } });
 const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
     "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
 const program = Effect.gen(function* () {
     const flags = yield* parseEpicArgs(process.argv.slice(2));
     const input = yield* resolveFlowInput(defaultEpic, flags.rest);
-    const reasoning = withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL);
-    const coder = withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL);
+    const coderFlags = flagsFromEnvironment(process.env.LLM4TS_CODER_FLAGS);
+    const reasoning = withExtraFlags(withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL), flagsFromEnvironment(process.env.LLM4TS_REASONING_FLAGS));
+    const coder = withExtraFlags(withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL), coderFlags);
+    const localServer = localCoderServer(process.env.LLM4TS_CODER_MODEL, coderFlags, process.env);
     const files = nodePlainFileStore;
     const epicId = epicIdFor(input.prompt);
     const stateDir = join(input.workDir, ".llm4ts", "epics", epicId);
@@ -62,6 +71,15 @@ const program = Effect.gen(function* () {
         if (flags.planOnly) {
             return;
         }
+        const concurrency = flags.concurrency ?? 3;
+        if (localServer !== undefined && concurrency > 1) {
+            yield* events.publish(Info.make({
+                message: `⚠ the coder is served by a local single-model server (${localServer}): it generates one ` +
+                    `reply at a time, so ${concurrency} parallel coders queue behind each other and a queued ` +
+                    'request is cut off after a few minutes ("terminated"). Prefer --concurrency 1, or give ' +
+                    "the server parallel slots."
+            }));
+        }
         const contextFor = context.contextFor;
         if (contextFor === undefined) {
             return yield* FlowAborted.make({
@@ -70,11 +88,12 @@ const program = Effect.gen(function* () {
         }
         const gates = gatesIn(nodeProcessExecutor, events, gateCommands(process.env));
         const setupCommand = worktreeSetupCommand(process.env);
+        const healthUrl = serverHealthUrl(localServer, process.env);
         const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
             plan,
             files,
             stateDir,
-            worktreeRoot: join(input.workDir, ".llm4ts", "worktrees"),
+            worktreeRoot: worktreeRootFor(input.workDir, plan.epicId, process.env),
             board: makeLocalBoardSync(files, stateDir, `Epic: ${plan.epicId}`),
             contextFor: (workDir) => Effect.gen(function* () {
                 const rebound = yield* contextFor(workDir);
@@ -95,6 +114,8 @@ const program = Effect.gen(function* () {
                 : { setup: setupIn(nodeProcessExecutor, events, setupCommand) }),
             gates,
             judge: (story, diff) => judgeStory(reasoningMeter.service, story, diff, contextBudget),
+            verifyBlocked: verifyBlockedOn(reasoningMeter.service, events, files, plan),
+            awaitRecovery: awaitServer(healthUrl === undefined ? undefined : httpProbe(healthUrl), events),
             system: (story) => Effect.succeed([
                 "House rules of the target repository (CONTRIBUTING.md):",
                 guidance,

package/flows/lib/epic-stories.js

@@ -1,15 +1,19 @@
 // Shared core of the epic-stories flow (ADR 0013): the operator flags, the
 // story-plan generator prompt and schema, the story judge, the gate runner,
 // and seat selection. The executor itself is `@llm4ts/flow/Stories`.
+import { join } from "node:path";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { TokenUsage } from "@llm4ts/core/Models";
 import { cap } from "@llm4ts/flow/Context";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { BlockedVerdict } from "@llm4ts/flow/Stories";
 import { stableHash } from "@llm4ts/flow/Plan";
 import { ReviewIssue } from "@llm4ts/flow/Review";
-import { StoryPlan } from "@llm4ts/flow/StoryPlan";
+import { StoryPlan, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
 import { claude, coderIds, pi } from "@llm4ts/runner/Connectors";
 import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand, mergeReviewResults } from "@llm4ts/runner";
 export const epicUsage = [
@@ -19,8 +23,11 @@ export const epicUsage = [
     "  --fail-fast         stop the epic at the first failed story",
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
     "       LLM4TS_CODER (default pi) implements; LLM4TS_REASONING_MODEL / LLM4TS_CODER_MODEL",
-    "       pick their models (pi: provider/model). LLM4TS_GATES overrides the gate commands;",
-    "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree."
+    "       pick their models (pi: provider/model); LLM4TS_CODER_FLAGS / LLM4TS_REASONING_FLAGS",
+    "       add CLI flags (key=value;key=value). LLM4TS_GATES overrides the gate commands;",
+    "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree;",
+    "       LLM4TS_WORKTREE_ROOT (default: <repo>.worktrees beside the repository) holds them;",
+    "       LLM4TS_CODER_HEALTH_URL is polled after the coder's serving engine goes down."
 ].join("\n");
 /** The flow's own flags, taken out before the shared `--repo`/prompt parsing sees the rest. */
 export const parseEpicArgs = (argv) => Effect.gen(function* () {
@@ -84,6 +91,180 @@ export const storyCoderFromEnvironment = (environment) => {
         })
         : Effect.succeed(preset);
 };
+// ---- Seat flags and local servers --------------------------------------------------
+/**
+ * `LLM4TS_CODER_FLAGS` / `LLM4TS_REASONING_FLAGS`: extra CLI flags for a seat as
+ * `key=value;key=value` (a bare `key` is a boolean flag). The first `=` splits, so
+ * a value may itself carry `=`: `config=model_provider=lmstudio` is codex's
+ * `--config model_provider=lmstudio`.
+ */
+export const flagsFromEnvironment = (raw) => {
+    const flags = {};
+    for (const part of (raw ?? "").split(";")) {
+        const entry = part.trim();
+        if (entry.length === 0) {
+            continue;
+        }
+        const at = entry.indexOf("=");
+        if (at < 0) {
+            flags[entry] = "";
+        }
+        else {
+            flags[entry.slice(0, at).trim()] = entry.slice(at + 1).trim();
+        }
+    }
+    return flags;
+};
+/**
+ * The local single-model server a coder seat points at, if any: pi's
+ * `lmstudio/…` and `ollama/…` model specs, codex's `--config model_provider=lmstudio`,
+ * a claude seat with `ANTHROPIC_BASE_URL` on a loopback host. Such a server serves
+ * one generation at a time, so parallel coders queue and a queued request is cut
+ * off after a few minutes — the flow warns when concurrency is above one.
+ */
+export const localCoderServer = (model, flags, environment) => {
+    const spec = (model ?? "").trim().toLowerCase();
+    for (const provider of ["lmstudio", "lm-studio", "ollama", "mlx"]) {
+        if (spec.startsWith(`${provider}/`)) {
+            return provider;
+        }
+    }
+    const configured = Object.entries(flags).find(([key, value]) => key === "config" && /^model_provider=(lmstudio|ollama)/.test(value));
+    if (configured !== undefined) {
+        return configured[1].slice("model_provider=".length);
+    }
+    const base = environment.ANTHROPIC_BASE_URL ?? environment.OPENAI_BASE_URL ?? "";
+    return /^(https?:\/\/)?(127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\])(:|\/|$)/.test(base)
+        ? "local"
+        : undefined;
+};
+// ---- Worktrees and the serving engine -------------------------------------------
+/**
+ * Where an epic's story worktrees live: `LLM4TS_WORKTREE_ROOT/<epicId>`, by
+ * default `<repo>.worktrees/<epicId>` BESIDE the repository. Nested inside
+ * it, a coder's parent directory is the epic checkout, and coders cd there.
+ */
+export const worktreeRootFor = (workDir, epicId, environment) => {
+    const configured = environment.LLM4TS_WORKTREE_ROOT?.trim();
+    const root = configured === undefined || configured.length === 0
+        ? `${workDir.replace(/[\\/]+$/, "")}.worktrees`
+        : configured;
+    return join(root, epicId);
+};
+/**
+ * The URL that answers when a local serving engine is up:
+ * `LLM4TS_CODER_HEALTH_URL`, else the server's model list at its default
+ * address. Undefined for a hosted provider — there is nothing to poll.
+ */
+export const serverHealthUrl = (server, environment) => {
+    const configured = environment.LLM4TS_CODER_HEALTH_URL?.trim();
+    if (configured !== undefined && configured.length > 0) {
+        return configured;
+    }
+    switch (server) {
+        case "lmstudio":
+        case "lm-studio":
+            return "http://127.0.0.1:1234/v1/models";
+        case "ollama":
+            return "http://127.0.0.1:11434/api/tags";
+        case "local": {
+            const base = (environment.ANTHROPIC_BASE_URL ?? environment.OPENAI_BASE_URL ?? "")
+                .trim()
+                .replace(/\/+$/, "")
+                .replace(/\/v1$/, "");
+            return base.length === 0 ? undefined : `${base}/v1/models`;
+        }
+        default:
+            return undefined;
+    }
+};
+/** Whether `url` answers 2xx within five seconds. */
+export const httpProbe = (url) => Effect.tryPromise(() => fetch(url, { signal: AbortSignal.timeout(5_000) })).pipe(Effect.map((response) => response.ok), Effect.catch(() => Effect.succeed(false)));
+export const defaultRecoveryTiming = {
+    interval: "15 seconds",
+    attempts: 60,
+    grace: "30 seconds"
+};
+/**
+ * The executor's `awaitRecovery`: polls `probe` until the engine answers
+ * (then waits the grace period), or fails after `attempts`. Without a probe
+ * (a hosted provider) it waits one interval-times-eight and lets the retry
+ * find out.
+ */
+export const awaitServer = (probe, events, timing = defaultRecoveryTiming) => (reason) => Effect.gen(function* () {
+    yield* events.publish(Info.make({ message: `⏸ waiting for the coder's serving engine to recover: ${reason}` }));
+    if (probe === undefined) {
+        yield* Effect.sleep(Duration.times(Duration.fromInputUnsafe(timing.interval), 8));
+        return;
+    }
+    for (let attempt = 0; attempt < timing.attempts; attempt += 1) {
+        if (yield* probe) {
+            yield* Effect.sleep(timing.grace);
+            yield* events.publish(Info.make({ message: "▶ the coder's serving engine answers again" }));
+            return;
+        }
+        yield* Effect.sleep(timing.interval);
+    }
+    return yield* FlowAborted.make({
+        message: `the coder's serving engine did not answer after ${timing.attempts} probes`
+    });
+});
+// ---- BLOCKED_ON second opinion ----------------------------------------------------
+export const blockedVerdictJsonSchema = {
+    type: "object",
+    properties: {
+        real: { type: "boolean" },
+        reason: { type: "string" }
+    },
+    required: ["real", "reason"]
+};
+const excerptLimit = 6_000;
+/**
+ * The executor's `verifyBlocked`: the reasoning seat reads the claim, the
+ * plan, and the named files as they are in the story's worktree, and decides
+ * whether the plan really has a gap. Only claims the plan alone cannot
+ * settle reach it.
+ */
+export const verifyBlockedOn = (reasoning, events, files, plan) => (story, need, workDir) => Effect.gen(function* () {
+    const excerpts = [];
+    for (const path of pathsNamedIn(plan, need).slice(0, 4)) {
+        const text = yield* files
+            .read(join(workDir, path))
+            .pipe(Effect.catch(() => Effect.succeed("(a directory, or unreadable)")));
+        excerpts.push(`### ${path}`, text === undefined ? "(does not exist in the working tree)" : cap(text, excerptLimit).text);
+    }
+    const others = plan.stories
+        .filter((other) => other.id !== story.id)
+        .map((other) => `- ${other.id} (depends on: ${other.dependsOn.join(", ") || "nothing"}) owns ${other.owned.join(", ")}; provides ${other.provides.join("; ")}`);
+    const prompt = [
+        "A coding agent implementing ONE story of a parallel epic stopped and claimed it is blocked",
+        "on work another story owns. Decide whether the claim is REAL.",
+        "",
+        "It is real only when the needed work is absent from the agent's working tree, is not",
+        "within its own owned paths, and no story it depends on provides it: the plan has a gap.",
+        "It is NOT real when the thing exists (perhaps in another file or under another name), when",
+        "the agent can build it inside its owned paths, when a later story owns it, or when the",
+        "problem is tooling or a type error the agent can fix itself.",
+        "",
+        `Story ${story.id}: ${story.title}`,
+        story.description,
+        `Depends on: ${story.dependsOn.join(", ") || "nothing"}`,
+        `Owns: ${story.owned.join(", ")}`,
+        `Reads: ${story.sharedReadOnly.join(", ") || "nothing"}`,
+        "",
+        "The other stories:",
+        ...others,
+        "",
+        `The claim: BLOCKED_ON: ${need}`,
+        "",
+        "The paths the claim names, as they are in the agent's working tree:",
+        ...(excerpts.length === 0 ? ["(the claim names no repository path)"] : excerpts),
+        "",
+        'Respond only with JSON: {"real": true|false, "reason": "..."}. The reason is shown to the',
+        "agent when the claim is rejected: say concretely where to look or what to do."
+    ].join("\n");
+    return yield* structuredAndPublish(reasoning, events, prompt, BlockedVerdict, blockedVerdictJsonSchema);
+});
 // ---- Story plan generation -----------------------------------------------------
 /** A readable, stable epic id: the first words of the epic plus a content hash. */
 export const epicIdFor = (epic) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/core": "2.7.0",
-    "@llm4ts/flow": "2.7.0",
-    "@llm4ts/runner": "2.7.0"
+    "@llm4ts/core": "2.8.0",
+    "@llm4ts/flow": "2.8.0",
+    "@llm4ts/runner": "2.8.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"