@llm4ts/shell 2.15.0 → 2.17.0

package/flows/lib/epic-stories.js

@@ -10,7 +10,9 @@ 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 { parseEpicBrief, renderEpicBrief, unanswered } from "@llm4ts/flow/EpicBrief";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { EpicBriefInvalid, EpicBriefNotApproved } from "@llm4ts/flow/FlowError";
 import { Info } from "@llm4ts/flow/FlowEvents";
 import { EpicLanded, EpicLandedVersion, landedPath } from "@llm4ts/flow/Landing";
 import { loadVersioned } from "@llm4ts/flow/Persistence";
@@ -167,6 +169,53 @@ export const renderEpicList = (epics) => epics.length === 0
             `  "${epic.epic.length > 110 ? `${epic.epic.slice(0, 109)}…` : epic.epic}"`
         ])
     ].join("\n");
+/** The names of the epic folders of a repository. */
+export const epicDirs = (workDir) => Effect.tryPromise(() => readdir(epicsDir(workDir), { withFileTypes: true })).pipe(Effect.map((entries) => entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()), Effect.catch(() => Effect.succeed([])));
+/** The briefs among `dirs`; a folder without one, or with one that does not parse, is skipped. */
+export const listBriefs = (files, workDir, dirs) => Effect.gen(function* () {
+    const briefs = [];
+    for (const dir of dirs) {
+        const text = yield* files.read(join(epicsDir(workDir), dir, "brief.md"));
+        if (text === undefined)
+            continue;
+        const brief = yield* parseEpicBrief(text).pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (brief !== undefined)
+            briefs.push({ dir, request: brief.request, status: brief.status });
+    }
+    return briefs;
+});
+/**
+ * What the story planner reads in place of the one-line epic: the approved
+ * brief in the epic's folder. Undefined when the plan is already written (the
+ * brief has done its job) or there is no brief. A draft, or an approved brief
+ * with an unanswered open point, stops the run: planning from the bare
+ * sentence beside an unfinished brief would silently ignore it.
+ */
+export const plannerInput = (files, stateDir, planPath) => Effect.gen(function* () {
+    if ((yield* files.read(planPath)) !== undefined)
+        return undefined;
+    const path = join(stateDir, "brief.md");
+    const text = yield* files.read(path);
+    if (text === undefined)
+        return undefined;
+    const brief = yield* parseEpicBrief(text, path);
+    if (brief.status !== "approved") {
+        return yield* EpicBriefNotApproved.make({ path });
+    }
+    const pending = unanswered(brief);
+    if (pending.length > 0) {
+        return yield* EpicBriefInvalid.make({
+            path,
+            violations: [
+                `the brief is approved with unanswered open points: ${pending.map((point) => point.number).join(", ")}`
+            ]
+        });
+    }
+    return renderEpicBrief(brief);
+});
 /**
  * The epic text given wins (a new epic, or the existing one with that exact
  * text); `--epic` picks an existing one; with neither, the one epic not yet
@@ -176,6 +225,10 @@ export const renderEpicList = (epics) => epics.length === 0
 export const chooseEpic = (args) => {
     if (args.epic !== undefined) {
         const found = args.epics.find((epic) => epic.dir === args.epic || epic.epicId === args.epic);
+        const brief = (args.briefs ?? []).find((candidate) => candidate.dir === args.epic);
+        if (found === undefined && brief !== undefined) {
+            return Effect.succeed({ _tag: "Brief", dir: brief.dir, request: brief.request });
+        }
         return found === undefined
             ? Effect.fail(ScriptUsage.make({
                 message: `no epic '${args.epic}' in this repository\n${renderEpicList(args.epics)}`
@@ -186,6 +239,23 @@ export const chooseEpic = (args) => {
         return Effect.succeed({ _tag: "Text", prompt: args.text });
     }
     const open = args.epics.filter((epic) => epic.landed === undefined);
+    // A folder `epic-design` wrote a brief into and nobody planned yet is an open
+    // epic too: alone it is the one to run, beside others it is never guessed.
+    const planned = new Set(args.epics.map((epic) => epic.dir));
+    const briefOnly = (args.briefs ?? []).filter((brief) => !planned.has(brief.dir));
+    const [onlyBrief] = briefOnly;
+    if (briefOnly.length === 1 && open.length === 0 && onlyBrief !== undefined) {
+        return Effect.succeed({ _tag: "Brief", dir: onlyBrief.dir, request: onlyBrief.request });
+    }
+    if (briefOnly.length > 0) {
+        return Effect.fail(ScriptUsage.make({
+            message: [
+                "several epics are open here; pick one with --epic <id>, or give an epic's text",
+                ...(open.length === 0 ? [] : [renderEpicList(open)]),
+                ...briefOnly.map((brief) => `${brief.dir}  brief ${brief.status}  ${brief.request}`)
+            ].join("\n")
+        }));
+    }
     if (open.length === 1 && open[0] !== undefined) {
         return Effect.succeed({ _tag: "Existing", epic: open[0] });
     }
@@ -470,7 +540,9 @@ export const storyPlanInstructions = (epicId, guidance) => [
     "Target repository guidance (house rules and layout — the vocabulary to use):",
     guidance
 ].join("\n");
-export const generateStoryPlan = (reasoning, events, epic, epicId, guidance) => structuredAndPublish(reasoning, events, `${storyPlanInstructions(epicId, guidance)}\n\nEpic:\n${epic}`, StoryPlan, storyPlanJsonSchema).pipe(
+export const generateStoryPlan = (reasoning, events, epic, epicId, guidance, 
+/** An approved epic brief (`epic-design`): what the planner reads in place of the sentence. */
+brief) => structuredAndPublish(reasoning, events, `${storyPlanInstructions(epicId, guidance)}\n\nEpic:\n${brief ?? epic}`, StoryPlan, storyPlanJsonSchema).pipe(
 // The id and the epic text are ours, whatever the model echoed back.
 Effect.map((plan) => StoryPlan.make({ ...plan, epicId, epic })));
 // ---- Usage ---------------------------------------------------------------------
@@ -719,11 +791,16 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         text: given.prompt,
         epic: flags.epic,
         epics,
+        briefs: yield* listBriefs(files, given.workDir, yield* epicDirs(given.workDir)),
         defaultEpic
     });
     const input = {
         ...given,
-        prompt: choice._tag === "Existing" ? choice.epic.epic : choice.prompt
+        prompt: choice._tag === "Existing"
+            ? choice.epic.epic
+            : choice._tag === "Brief"
+                ? choice.request
+                : choice.prompt
     };
     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));
@@ -731,7 +808,11 @@ export const runEpicStories = (options) => Effect.gen(function* () {
     const localServer = localCoderServer(process.env.LLM4TS_CODER_MODEL, coderFlags, process.env);
     // A new epic's id (and state folder) is derived from its text; an existing
     // one keeps its folder, whatever text is on the command line.
-    const epicId = choice._tag === "Existing" ? choice.epic.dir : epicIdFor(input.prompt);
+    const epicId = choice._tag === "Existing"
+        ? choice.epic.dir
+        : choice._tag === "Brief"
+            ? choice.dir
+            : epicIdFor(input.prompt);
     const stateDir = join(epicsDir(input.workDir), epicId);
     const planPath = join(stateDir, "plan.md");
     const estimateOptions = estimatedUsageOptionsFromEnv(process.env);
@@ -750,9 +831,16 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         const events = context.events;
         const reasoningMeter = yield* makeEstimatedUsageMeter(context.reasoning, estimateOptions);
         const guidance = yield* Effect.map(files.read(join(input.workDir, "CONTRIBUTING.md")), (text) => cap(text ?? "(no CONTRIBUTING.md in the target repository)", 24_000).text);
+        // An approved epic brief in the epic's folder is what the planner reads.
+        const brief = yield* plannerInput(files, stateDir, planPath);
+        if (brief !== undefined) {
+            yield* events.publish(Info.make({
+                message: `planning from the approved brief at ${join(stateDir, "brief.md")}`
+            }));
+        }
         const store = makeStoryPlanStore(files);
         const plan = yield* stage(events, "story plan", store
-            .recoverOrCreate(planPath, generateStoryPlan(reasoningMeter.service, events, input.prompt, epicId, guidance))
+            .recoverOrCreate(planPath, generateStoryPlan(reasoningMeter.service, events, input.prompt, epicId, guidance, brief))
             .pipe(Effect.flatMap(validateStoryPlan)));
         yield* events.publish(Info.make({
             message: `story plan: ${plan.stories.length} stories at ${planPath} (edit and rerun to re-plan)`

package/kits/soap-ace/README.md

@@ -14,15 +14,56 @@ source) and shares nothing with this kit.
 
 ## Status
 
-| Piece                                              | State    |
-| -------------------------------------------------- | -------- |
-| Strict XML reader (`flows/lib/soap/Xml.ts`)        | done     |
-| WSDL 1.1/2.0 + XSD catalog (`Wsdl.ts`, `Xsd.ts`)   | done     |
-| `demo-bank-soap` fixture                           | WSDL/XSD |
-| `soap-discover` flow and operation classification  | pending  |
-| Masking, auth profile, transport, sample authoring | pending  |
-| Analysis, REST design, OpenAPI projection          | pending  |
-| `ace12-rest` pack, scaffold, `soap-epic`           | pending  |
+| Piece                                                                    | State |
+| ------------------------------------------------------------------------ | ----- |
+| Strict XML reader, WSDL 1.1/2.0 + XSD catalog                            | done  |
+| `soap-discover` flow and operation classification                        | done  |
+| Masking, auth profile, transport, sample authoring                       | done  |
+| Analysis, REST design, OpenAPI projection                                | done  |
+| `ace12-rest` pack, scaffold, `soap-epic`                                 | done  |
+| `soap-explore`: the discovery half in one command                        | done  |
+| `demo-bank-soap` fixture ([runbook](fixtures/demo-bank-soap/RUNBOOK.md)) | done  |
+
+## Quick start: soap-explore
+
+One command from a WSDL to a design draft, the way SoapUI turns a WSDL into
+a project. It stops only where a person decides, and a rerun continues where
+it stopped:
+
+```bash
+llm4ts run soap-explore --repo ~/work/conti-analysis ./wsdl/ContiService.wsdl   # or an https URL
+# write .llm4ts/soap/<service>/auth.json: at least {"environment": "test"}
+# review operations.md, set Status: confirmed
+llm4ts run soap-explore --repo ~/work/conti-analysis                             # continue
+```
+
+| Step     | What happens                                                                                                                                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| discover | `catalog.json`/`.md`, `operations.md` with proposed classes (as `soap-discover`)                                                                                                                                                |
+| requests | `samples/<op>/happy-path.request.yaml` for **every** operation, example values from the XSD                                                                                                                                     |
+| probe    | calls the **read** operations once, producers first: the IBAN `cercaConti` returns is what `dettaglioConto` is called with. Live values stay in memory; the request file on disk carries the masked one. Mutating: never called |
+| evidence | `analysis/<op>.md`, `design/mapping.json`/`.md`                                                                                                                                                                                 |
+| design   | the reasoning seat drafts `design/api-design.md`, `check`, one `revise` round when errors remain; an existing design is only checked; `--no-design` skips                                                                       |
+| report   | `explore.md`: per operation the probe decision and result, the chained values, the design state, and the next command for every gap                                                                                             |
+
+**Who may be called.** Without `auth.json` nothing is called (explore never
+writes it: the environment label is yours to declare). With `operations.md`
+confirmed, its `read` operations are called. Before confirmation, an
+operation is called only in dev or test, and only when the file still lists
+it as `read`, the name heuristic says `read`, and the judgment seat
+(`LLM4TS_JUDGMENT_PROVIDER`) answers `read` with an `act` decision; without
+a judgment seat, confirm first. uat always needs confirmation.
+
+**Files it owns.** A request explore writes starts with a `# soap-explore:
+generated` line and is regenerated when probed again. Delete that line to
+own the file: explore then sends it as written and never touches it.
+`--refresh` calls the probed operations again; everything else is kept.
+
+Approvals stay human: `Status: confirmed` in `operations.md`,
+`Status: approved` in `api-design.md`. Then `soap-design "openapi"` and
+`soap-epic` as below. The individual flows remain for everything past the
+first pass: more scenarios per operation (`soap-sample "propose <op>"`),
+mutating calls, SoapUI import, design revisions.
 
 ## soap-discover
 

package/kits/soap-ace/fixtures/demo-bank-soap/RUNBOOK.md

@@ -16,6 +16,22 @@ cd ~/work/conti-analysis
 The analysis repository holds `.llm4ts/soap/<service>/`: catalog, samples,
 analysis, design. The ACE repository receives the contracts and the code.
 
+## Fast path: soap-explore
+
+Steps 1 to 4 in one command, rerun after each decision:
+
+```bash
+llm4ts run soap-explore --repo . ./wsdl/ContiService.wsdl   # discover, requests, report
+# write auth.json (step 2), review and confirm operations.md
+llm4ts run soap-explore --repo .                            # probe reads, analyse, draft the design
+```
+
+Read `.llm4ts/soap/<service>/explore.md` after each run: it lists what was
+called, what was not and why, and the next command. On the fixture:
+`LLM4TS_SOAP_STUB=<kit>/fixtures/demo-bank-soap/responses`. The steps below
+are the same work one command at a time, and what to use past the first
+pass.
+
 ## 1. Discover
 
 ```bash

package/kits/soap-ace/flows/lib/soap/Call.js

@@ -69,7 +69,7 @@ export const callOperation = (options) => Effect.gen(function* () {
             detail: `no auth profile; write ${`.llm4ts/soap/${service}/auth.json`} with at least {"environment": "dev"}`
         });
     }
-    const request = yield* readRequestFile(workspace, catalog, service, operation.name, name);
+    const request = options.request ?? (yield* readRequestFile(workspace, catalog, service, operation.name, name));
     const issues = [
         ...request.readIssues,
         ...validateInstance(catalog, input, request.body)
@@ -130,6 +130,7 @@ export const callOperation = (options) => Effect.gen(function* () {
     // which quote values) is read from the masked, security-stripped tree:
     // nothing unmasked reaches the exchange.
     let fault;
+    let payload;
     if (parsedResponse._tag === "None") {
         responseIssues.push({
             path: "(response)",
@@ -148,11 +149,14 @@ export const callOperation = (options) => Effect.gen(function* () {
         }
         else if (operation.output !== undefined) {
             const output = elementByName(catalog, operation.output);
-            const payload = read.value.payload;
-            if (output !== undefined && payload !== undefined) {
-                responseIssues.push(...instanceFromXml(catalog, output, payload).issues);
+            const masked = read.value.payload;
+            if (output !== undefined && masked !== undefined) {
+                responseIssues.push(...instanceFromXml(catalog, output, masked).issues);
+                const live = yield* readEnvelope(stripSecurity(parsedResponse.value)).pipe(Effect.option);
+                if (live._tag === "Some" && live.value.payload !== undefined)
+                    payload = { live: live.value.payload, masked };
             }
-            else if (payload === undefined) {
+            else if (masked === undefined) {
                 responseIssues.push({ path: "(response)", detail: "empty Body" });
             }
         }
@@ -182,5 +186,5 @@ export const callOperation = (options) => Effect.gen(function* () {
         masking: mergeReports([maskedRequest.report, maskedResponse.report])
     });
     const path = yield* writeExchange(workspace, service, exchange);
-    return { exchange, path, permission };
+    return { exchange, path, permission, ...(payload === undefined ? {} : { payload }) };
 });