Skip to content

Commit cbd3009

Browse files
authored
🐛 Let the workflow host answer its own <Elicit> through the CLI (#609)
* 🐛 Let the workflow host answer its own <Elicit> through the CLI (#607) Whether an execution activates the testing stack and whether this host owns elicitation are two decisions, and the CLI made them as one: every non-testing document got the Web provider. A workflow start is a non-testing document, so the provider landed in the nested document scope inside the host's attachment — nearer, at the same `{ at: "min" }`, and therefore first. A workflow reaching `<Elicit>` opened a loopback form and waited for a reader who is not coming instead of committing a `suspension_request` and settling `suspended`. `DocumentMode` now carries a required `webElicitation`, and each trusted profile states it: `xmd run` and the nested `host="run"` profile enable it, `xmd test` and `xmd workflow` do not. Required rather than defaulted, so a profile added later cannot inherit the browser form by omission. `installWebComponents()` stays unconditional — an authored `<WebForm>` under a workflow still asks through its own component. The regression launches the real Deno-source CLI, because no in-process caller builds the assembly that was broken: `runWorkflow()` and `executeInstalled()` both skip it. Before the fix the case is abandoned at its deadline with `http://127.0.0.1:<port>/f/…` on the captured channel. * ♻️ Compose the run profile's elicitation provider instead of flagging it (#607) Review of 8b380b9: a trusted host profile must install Web elicitation directly, through lexical composition, rather than by handing the shared assembly a property to interpret. `DocumentMode.webElicitation` is gone, and `installDocumentComponents()` no longer installs an elicitation provider for any command — it neither receives nor reads a profile. `installWebComponents()` stays unconditional, so `<WebForm>` remains registered everywhere. Instead, each profile composes what it owns. `xmd run` installs `installWebElicitation()` in the scope it assembles around its own document, and the nested `host="run"` profile installs it in the isolated scope the harness gives a child — restated there rather than inherited, because a child of `xmd test` is still the run profile and its command composes none. `xmd test` and `xmd workflow` compose no elicitation provider at all, so the workflow attachment's suspending provider stays the only one a workflow document can reach. The behavior is the one 8b380b9 established and the four-profile table is unchanged; what moves is where the decision lives. Absence is now how a profile says it does not own the question, so there is no flag to read and no default to inherit. The subprocess regression is unchanged, and still fails on the defect: with `installWebElicitation()` moved back into the shared assembly, the case is abandoned at its deadline with the loopback form URL in its captured output. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 2f06e79 commit cbd3009

3 files changed

Lines changed: 177 additions & 30 deletions

File tree

‎packages/cli/src/cli.ts‎

Lines changed: 43 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -628,15 +628,18 @@ export function* installDocumentComponents(mode: DocumentMode, verbose: boolean)
628628
// repository's own WebForm.md or WebForm.ts still wins.
629629
yield* installWebComponents();
630630

631-
// `<Elicit>` reaches a person through the same form — but only for `xmd run`.
632-
// Under `xmd test` a document that elicits without supplying an answer would
633-
// open a browser and wait for somebody who is not coming, which is a hang
634-
// rather than a test result. Leaving the provider out makes that document
635-
// fail immediately with "no elicitation provider configured", and an
636-
// `<Answers>` region stays the way a test says what the answer is.
637-
if (!mode.testing) {
638-
yield* installWebElicitation();
639-
}
631+
// No elicitation provider is assembled here, for any command. Who answers
632+
// `<Elicit>` is not a property of the components a document runs with: it is
633+
// whichever host attached this run, and a host says so by installing its own
634+
// provider in the scope it composes around this one. `xmd run` and the nested
635+
// run profile install the browser form there; `xmd test` and `xmd workflow`
636+
// install nothing there, and the workflow attachment's suspending provider is
637+
// the only one a workflow document can reach.
638+
//
639+
// Deciding it here instead would put the answer in the one assembly every
640+
// profile shares, where a provider is only ever a scope away from the wrong
641+
// run — and where the workflow's provider, installed further out, would lose
642+
// to it at the same `{ at: "min" }`.
640643

641644
// Agent flags are exclusive to `xmd run` — `xmd test` drives agents
642645
// through the deterministic TestAgent stack instead.
@@ -1692,25 +1695,34 @@ function* dispatch(
16921695
}
16931696
const root = propsPhase.root;
16941697
announceSecretDetection(config.secretDetection);
1695-
const result = yield* runScopedDocument(
1696-
{ ...config, root, retainProcessOutput: keepsProcessOutput(config.journal) },
1697-
{
1698-
testing: false,
1699-
props: props.value,
1700-
// Only `xmd run` receives it. Every other command assembles none of
1701-
// it, which is what keeps a machine session from being acted on by a
1702-
// command that never said it could own one.
1703-
...(sessions === undefined ? {} : { machineSessions: sessions }),
1704-
agent: {
1705-
agentProvider: config.agentProvider,
1706-
defaultAgent: config.defaultAgent,
1707-
approveAll: config.approveAll,
1708-
approveReads: config.approveReads,
1709-
denyAll: config.denyAll,
1698+
const result = yield* scoped(function* (): Operation<Result<void>> {
1699+
// `<Elicit>` reaches a person through the browser form, and `xmd run`
1700+
// is the command a person is sitting in front of. Composed here, in the
1701+
// scope this profile assembles around its own document, because that is
1702+
// what owning the question *is*: a host that answers installs a
1703+
// provider, and one that does not installs none. Nothing downstream
1704+
// reads a profile, so nothing downstream can read one wrong.
1705+
yield* installWebElicitation();
1706+
return yield* runScopedDocument(
1707+
{ ...config, root, retainProcessOutput: keepsProcessOutput(config.journal) },
1708+
{
1709+
testing: false,
1710+
props: props.value,
1711+
// Only `xmd run` receives it. Every other command assembles none of
1712+
// it, which is what keeps a machine session from being acted on by
1713+
// a command that never said it could own one.
1714+
...(sessions === undefined ? {} : { machineSessions: sessions }),
1715+
agent: {
1716+
agentProvider: config.agentProvider,
1717+
defaultAgent: config.defaultAgent,
1718+
approveAll: config.approveAll,
1719+
approveReads: config.approveReads,
1720+
denyAll: config.denyAll,
1721+
},
17101722
},
1711-
},
1712-
installService,
1713-
);
1723+
installService,
1724+
);
1725+
});
17141726
if (!result.ok) {
17151727
// The document is reread between preparation and execution, so the
17161728
// exact target this run decided on can be gone by the time it runs.
@@ -1832,6 +1844,10 @@ function* dispatch(
18321844
// already produced; the fork's own execution renders it again.
18331845
...(execution.discardOutput === true ? { discardOutput: true } : {}),
18341846
},
1847+
// No elicitation provider is composed around this document. The
1848+
// workflow host attached the execution and installed the suspending
1849+
// one already; a browser form here would sit nearer, answer first,
1850+
// and wait for a reader the run has no way to reach.
18351851
{ testing: false, props: execution.props, installations: execution.installations },
18361852
// The workflow authority boundary sits exactly where a host
18371853
// service adapter would: installed inside the execution scope,

‎packages/cli/src/testing-host.ts‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@
99
* of `xmd run` that nothing ships.
1010
*
1111
* So a child gets what `xmd run` gets, after the command line has been read:
12-
* the same components (`installDocumentComponents`), the same native service
13-
* adapter this entrypoint installs, the same root loader and target resolver,
14-
* and the same `executeInstalled()` call. What it does not get is process
12+
* the same components (`installDocumentComponents`), the same browser-form
13+
* elicitation provider, the same native service adapter this entrypoint
14+
* installs, the same root loader and target resolver, and the same
15+
* `executeInstalled()` call. What it does not get is process
1516
* presentation — no journal file, no `--verbose` echo, no terminal formatting,
1617
* no stdout of its own. Its rendered output goes back to the document that ran
1718
* it, which is the only reader it has.
@@ -25,6 +26,7 @@ import { InMemoryStream } from "@executablemd/durable-streams";
2526
import type { DurableEvent } from "@executablemd/durable-streams";
2627
import { forEach } from "@effectionx/stream-helpers";
2728
import { useHostFiles } from "@executablemd/runtime";
29+
import { installWebElicitation } from "@executablemd/web";
2830
import type { Operation } from "effection";
2931
import { fileSource, inlineSource } from "@executablemd/core";
3032
import type { RootDocumentSource } from "@executablemd/core";
@@ -94,6 +96,12 @@ function* runProfileChild(
9496
const stream = new InMemoryStream();
9597

9698
yield* installDocumentComponents({ testing: false }, false);
99+
// A child gets what `xmd run` gets, and the browser form is part of that.
100+
// Installed here rather than inherited: this scope is isolated from the
101+
// command that started it, so the run profile's provider reaches a child only
102+
// if the run profile composes it — and a child of `xmd test`, whose command
103+
// composes none, still gets one because *this* is the run profile.
104+
yield* installWebElicitation();
97105
// Document filesystem access resolves in the caller's own filesystem, as it
98106
// does for `xmd run`. The entrypoint installs its provider process-wide, but
99107
// the child runs in an isolated scope, so the child's assembly must restate

‎packages/cli/tests/workflow-suspension.test.ts‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,16 @@
2222
* this suite. Only the agent is a stand-in, in the slot the real agent profile
2323
* fills, because what is under test is that a turn is retained once rather than
2424
* what an agent says.
25+
*
26+
* One case below is a process after all, and says why: which provider answers
27+
* `<Elicit>` is decided by the assembly the entrypoint builds around the
28+
* document, and no in-process caller — this suite's included — builds that
29+
* assembly. It is the only observation here that a value cannot stand in for.
2530
*/
2631

2732
import { describe, it } from "@executablemd/test-support/bdd";
2833
import { expect } from "@executablemd/test-support/expect";
34+
import { runCli } from "@executablemd/test-support/launch";
2935
import { call, ensure, Err, Ok, resource, scoped } from "effection";
3036
import type { Operation, Result } from "effection";
3137
import { exists, rm, writeTextFile } from "@effectionx/fs";
@@ -1462,3 +1468,120 @@ the retained note
14621468
});
14631469
}
14641470
});
1471+
1472+
/**
1473+
* The one question a workflow asks, and the smallest document that asks it.
1474+
*
1475+
* No effect precedes the wait: what is under test is which provider answers
1476+
* `<Elicit>`, and an effect ahead of it would only add ways for the case to
1477+
* fail before reaching the boundary it exists to cross.
1478+
*/
1479+
const ELICITATION = `<Elicit schema={${CHECKPOINT_SCHEMA}} as="decision">
1480+
Proceed with the change?
1481+
</Elicit>
1482+
1483+
decision: {decision.proceed}
1484+
`;
1485+
1486+
/** A HOME of this case's own, so nothing reaches the developer's configuration. */
1487+
function useIsolatedHome(): Operation<string> {
1488+
return resource<string>(function* (provide) {
1489+
const home = yield* until(mkdtemp(join(tmpdir(), "xmd-wfs-home-")));
1490+
yield* ensure(function* () {
1491+
yield* rm(home, { recursive: true, force: true });
1492+
});
1493+
yield* provide(home);
1494+
});
1495+
}
1496+
1497+
/**
1498+
* How long one `xmd workflow` invocation may take before it is abandoned.
1499+
*
1500+
* Bounded rather than left to the default, because the failure this case
1501+
* guards against is a *wait*: with a Web provider assembled underneath the
1502+
* workflow's own, the start opens a loopback form and blocks for a reader who
1503+
* is not coming. `runCli` reports what each channel received before the
1504+
* deadline, so an abandoned run still names the form it opened.
1505+
*/
1506+
const INVOCATION_LIMIT = 40_000;
1507+
1508+
/** What one `xmd workflow` line published, or nothing when it published none. */
1509+
function published(stderr: string, label: string): string | undefined {
1510+
const prefix = `workflow ${label}: `;
1511+
const line = stderr.split("\n").find((entry) => entry.startsWith(prefix));
1512+
return line?.slice(prefix.length).trim();
1513+
}
1514+
1515+
describe("a workflow elicitation through the shipped CLI assembly", () => {
1516+
it("suspends, is answered and resumes without ever opening a browser form", function* () {
1517+
// Launched as a process, because the subject is the assembly the entrypoint
1518+
// builds around `runScopedDocument`. Calling `runWorkflow()` or
1519+
// `executeInstalled()` from here would install the components this suite
1520+
// chose and never reach the boundary under test.
1521+
const runs = yield* useRunStore();
1522+
const home = yield* useIsolatedHome();
1523+
const fixture = yield* useCheckpointFixture(ELICITATION);
1524+
1525+
const xmd = (args: string[]) =>
1526+
runCli(args, {
1527+
cwd: fixture.repository,
1528+
env: { HOME: home, XMD_WORKFLOW_RUNS: runs },
1529+
timeout: INVOCATION_LIMIT,
1530+
});
1531+
1532+
const started = yield* xmd(["workflow", "start", "workflow.md"]).join();
1533+
1534+
// Suspension is its own process outcome, and the pair a caller needs in
1535+
// order to answer the run reaches standard error beside it.
1536+
expect(started.code).toBe(2);
1537+
expect(published(started.stderr, "status")).toBe("suspended");
1538+
const runId = published(started.stderr, "run");
1539+
expect(runId).toBeDefined();
1540+
const suspensionId = published(started.stderr, "suspension");
1541+
expect(suspensionId).toBeDefined();
1542+
1543+
// Nobody was asked anything: no loopback form was announced and no browser
1544+
// launch was attempted, on either channel.
1545+
const captured = `${started.stdout}\n${started.stderr}`;
1546+
expect(captured).not.toContain("http://127.0.0.1:");
1547+
expect(captured).not.toContain("could not open a browser automatically");
1548+
1549+
const path = workflowRunPath(runs, String(runId));
1550+
const suspended = retained(path);
1551+
expect(suspended.status).toBe("suspended");
1552+
expect(suspended.requests).toHaveLength(1);
1553+
expect(suspended.rootCloses).toBe(0);
1554+
// The wait the caller was told to answer is the wait the run retained.
1555+
expect(suspensionId).toBe(suspended.requests[0]);
1556+
1557+
// The delivery retains a value and moves nothing else.
1558+
const delivered = yield* xmd([
1559+
"workflow",
1560+
"answer",
1561+
String(runId),
1562+
String(suspensionId),
1563+
'{"proceed":true}',
1564+
]).join();
1565+
expect(delivered.code).toBe(0);
1566+
expect(delivered.stdout.trim()).toBe(`workflow answer: ${runId} (${suspensionId})`);
1567+
expect(retained(path)).toEqual(suspended);
1568+
expect(answers(path)).toEqual([
1569+
{
1570+
suspensionId: String(suspensionId),
1571+
state: "pending",
1572+
answer: JSON.stringify({ proceed: true }),
1573+
},
1574+
]);
1575+
1576+
// An ordinary resume spends the answer once and reaches the authored value.
1577+
const resumed = yield* xmd(["workflow", "resume", String(runId)]).join();
1578+
expect(resumed.code).toBe(0);
1579+
expect(published(resumed.stderr, "status")).toBe("completed");
1580+
expect(resumed.stdout).toContain("decision: true");
1581+
1582+
const completed = retained(path);
1583+
expect(completed.status).toBe("completed");
1584+
expect(completed.requests).toEqual(suspended.requests);
1585+
expect(answers(path)[0]?.state).toBe("consumed");
1586+
});
1587+
});

0 commit comments

Comments
 (0)