Skip to content

Commit 8b380b9

Browse files
committed
🐛 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.
1 parent 170a021 commit 8b380b9

3 files changed

Lines changed: 167 additions & 9 deletions

File tree

‎packages/cli/src/cli.ts‎

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -572,6 +572,18 @@ interface DocumentConfig {
572572

573573
export interface DocumentMode {
574574
testing: boolean;
575+
/**
576+
* Whether this host profile answers `<Elicit>` with the browser form.
577+
*
578+
* Required, and stated by each trusted profile rather than derived from
579+
* `testing`: whether an execution activates the testing stack and whether
580+
* this host owns elicitation are two independent decisions, and a host that
581+
* already installed a provider of its own — a workflow attachment installs
582+
* the suspending one — must not have a second, nearer provider assembled
583+
* underneath it. Making it required is what keeps a profile added later from
584+
* inheriting the browser form by omission.
585+
*/
586+
webElicitation: boolean;
575587
agent?: AgentFlags;
576588
/**
577589
* What this host states about machine-wide agent sessions: who owns one,
@@ -628,13 +640,19 @@ export function* installDocumentComponents(mode: DocumentMode, verbose: boolean)
628640
// repository's own WebForm.md or WebForm.ts still wins.
629641
yield* installWebComponents();
630642

631-
// `<Elicit>` reaches a person through the same form — but only for `xmd run`.
643+
// `<Elicit>` reaches a person through the same form — but only where the
644+
// profile said this host owns the question.
645+
//
632646
// Under `xmd test` a document that elicits without supplying an answer would
633647
// 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) {
648+
// rather than a test result. Under `xmd workflow` the workflow attachment
649+
// already installed the suspending provider around this scope, and both are
650+
// installed `{ at: "min" }`, so a provider assembled here would be the nearer
651+
// one and would answer with a form the run has no reader for. Leaving it out
652+
// makes an unowned elicitation fail immediately with "no elicitation provider
653+
// configured", and an `<Answers>` region stays the way a document says what
654+
// the answer is.
655+
if (mode.webElicitation) {
638656
yield* installWebElicitation();
639657
}
640658

@@ -930,7 +948,9 @@ function* test(
930948
announceSecretDetection(config.secretDetection);
931949
const result = yield* runScopedDocument(
932950
{ ...config, root: { path } },
933-
{ testing: true },
951+
// `xmd test` owns no elicitation: a document that asks without an
952+
// `<Answers>` region fails rather than opening a form nobody is at.
953+
{ testing: true, webElicitation: false },
934954
installService,
935955
);
936956
if (!result.ok) {
@@ -970,7 +990,7 @@ function* test(
970990
root: { path: document.path },
971991
componentDir: componentSearchPath(document, target.root, config.componentDir),
972992
},
973-
{ testing: true },
993+
{ testing: true, webElicitation: false },
974994
installService,
975995
);
976996
if (!result.ok) {
@@ -1696,6 +1716,9 @@ function* dispatch(
16961716
{ ...config, root, retainProcessOutput: keepsProcessOutput(config.journal) },
16971717
{
16981718
testing: false,
1719+
// `xmd run` is the command a person is sitting in front of, so it is
1720+
// the one that may ask them through the browser form.
1721+
webElicitation: true,
16991722
props: props.value,
17001723
// Only `xmd run` receives it. Every other command assembles none of
17011724
// it, which is what keeps a machine session from being acted on by a
@@ -1832,7 +1855,17 @@ function* dispatch(
18321855
// already produced; the fork's own execution renders it again.
18331856
...(execution.discardOutput === true ? { discardOutput: true } : {}),
18341857
},
1835-
{ testing: false, props: execution.props, installations: execution.installations },
1858+
{
1859+
testing: false,
1860+
// The workflow host attached this execution and installed the
1861+
// suspending provider around it. A browser form assembled here
1862+
// would sit nearer and answer first, and a workflow's question is
1863+
// answered by `xmd workflow answer`, not by a reader who would
1864+
// have to still be at the terminal when the run reaches it.
1865+
webElicitation: false,
1866+
props: execution.props,
1867+
installations: execution.installations,
1868+
},
18361869
// The workflow authority boundary sits exactly where a host
18371870
// service adapter would: installed inside the execution scope,
18381871
// before the root document is imported.

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,9 @@ function* runProfileChild(
9393
const diagnostic = request.journal === "diagnostic";
9494
const stream = new InMemoryStream();
9595

96-
yield* installDocumentComponents({ testing: false }, false);
96+
// A child gets what `xmd run` gets, and the browser form is part of that:
97+
// this profile *is* the run profile, so it states the run profile's answer.
98+
yield* installDocumentComponents({ testing: false, webElicitation: true }, false);
9799
// Document filesystem access resolves in the caller's own filesystem, as it
98100
// does for `xmd run`. The entrypoint installs its provider process-wide, but
99101
// 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)