Skip to content

Commit 3948fe4

Browse files
authored
✨ Add xmd prompt: turn a request into an approved executable Plan (#260) (#657)
* ✨ Add xmd prompt, the authorship command (#260) `xmd prompt "<request>"` asks the configured ACP agent for a complete executable Markdown root, validates it without executing any of it, repairs its definite defects by asking again, shows a person the exact bytes, and runs the approved ones through the ordinary supplied-source path under the `<prompt>` identity. It adds authorship around one normal document; it adds no second execution model, props model or journal. Authorship sits outside durability. The catalog, the fresh generator session, every repair and the review create no journal and replay nothing, and the generator's scope closes before the optional exclusive `--save` and before execution. A defect the draft authored is repairable and earns one of three turns; a defect the command line authored terminates without spending a turn on something the agent cannot fix. `xmd run` and `xmd prompt` now share one execution field set, one resolved Agent configuration, and one props source resolution. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Settle one agent stack, refuse -e, and report a run's failure (#260) Three review findings on the xmd prompt command. An inline document reached the generator. `preparePropsPhase` skips the parse that carries the other commands' `-e` refusal, so a supplied document was dropped in silence and the command generated a different one. Refused in prompt's own branch, before the catalog, the provider, the review, the save, the journal or any execution. The agent configuration was resolved twice, once for generation and again for the document, so one command line had two chances to read DEFAULT_AGENT_NAME differently. A dispatch now settles it once and hands the resolved value to both consumers; DocumentMode carries the settled stack rather than the flags. The executed program still gets a fresh ordinary provider and inherits neither the generator session nor its system prompt. A document failing its own <Testing> boundary printed a bare message where a run prints a `tests failed:` heading. reportFailure moves to a module both commands share. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * ✨ Ship the plan program as a packaged Markdown document (#260) The first document-backed command needs its Markdown where the command is: a source checkout, a published npm package, and a compiled binary with no checkout. The document is the deployed program, so it ships as a file rather than as a generated string. src/documents/prompt-plan.md is that program. A package declares what it ships by putting it in that directory; test documents and scenario fixtures live under src/ too, and a build that swept those up would publish fixtures and grow every binary carrying them. The command locates it from its module's own URL, never from the working directory and never through the component search path, so it finds the same policy whatever directory a person stands in and no repository file can answer for it. Each build keeps the directory beside its module: both deno compile sites embed it, and the npm build copies it into the emitted tree, because dnt emits the module graph only and an asset nothing imports would otherwise reach Node and Bun missing while Deno stayed green. A regression holds the two compile sites to the documents that exist, since that list is the one thing no build discovers. The host still runs the TypeScript authorship loop; wiring the plan program into the plan profile follows. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Make plan approval and exhaustion mutually exclusive (#260) A <Return> selects the value a value body publishes; it does not end that body, and a later failure wins over a value already selected. The approve branch returned the candidate and broke out of the review loop, then execution left the Session and reached the unconditional exhaustion <Fail>. Every approval settled as the ten-draft failure and no approved candidate could reach the host. Approval now binds the exact candidate to a null-sentinel result, and one exhaustive branch after the Session either returns it or fails. Only the arm taken runs, so an approved candidate has no later sibling failure to overtake it. Bounds, prompt wording, diagnostics, presentation, Session structure and the authored abort remain as they were. The review schema also needed an explicit string type: Ajv strict mode refuses minLength on an untyped property, so every review was refused before a person saw anything. Diagnostics reach their code block through <Json> rather than a JSON.stringify call in an expression, so serializing them is a document construct like everything else this policy does. The regression runs the packaged document itself, resolved against first-party declarations with an empty include list, against a scripted agent turn, a scripted approval and a test validator. It fails with the exhaustion message before this change. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * ✨ Turn a request into a Plan with a packaged command document (#260) `xmd prompt` now executes two roots with a scope boundary between them. First `src/documents/prompt-command.md`, the checked-in first-party Markdown that implements the conversion and its review workflow; then the Plan it returned, through the ordinary supplied-source path. The TypeScript authorship loop — `author()`, `evaluate()` and `review()` — is gone: what the assistant is asked, how many drafts may be fixed, how many you are shown and what happens when you approve nothing are readable Markdown now, and arguable. A Plan is not a script with comments. The shipped generation, repair and revision instructions ask for every requested outcome as reader-facing prose with each component placed immediately after the sentences describing what it does, so the source can be audited and the execution followed by the same narrative. That authorship rule is the document's and human review's; it is never a hidden validation rule. The prompt profile is what that document runs inside. The assistant gets an empty directory of this host's own, no additional directories, no MCP servers, no native tools and a strict denial answered inside the provider — so nothing composed around it can widen a ceiling with nothing in it, and `--approve-all` configures the approved Plan rather than the conversation that wrote it. The document itself reaches no Files, command, service or network capability, runs against no repository component search, and cannot opt out of a failing turn ending it: a turn that streamed half a program and failed presents nothing. `<ValidateCandidate>` is declared to that execution rather than resolved from a repository, and it keeps the two kinds of failure apart. A defect a draft authored comes back as structured facts the document may repair; a defect the command line authored raises out of it, so no policy can catch a caller's mistake and call it feedback. The host takes the returned Plan back as untrusted text. Only after every Prompt task, provider and Elicitation resource has torn down does it validate those exact bytes again and resolve their props — a revision that changed a property's declared type changes what the run receives — and only then does `--save` create the file and the Plan run. `--session <name>` names the assistant session; without it each invocation places its own. The profile's working directory is one fixed host-owned path because a session's key includes the directory it lives in, and a location that changed every time would leave that option unable to name anything. Evidence runs the packaged document itself against a scripted agent and a scripted review: the shipped words reach the turn, ten presentations bound the review with no revision on the tenth, an interleaved Plan returns byte for byte, and what a person reads says each thing once however many rounds it took. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Give each prompt session its own directory and a reachable exhaustion (#260) Four corrections to the prompt profile and the command document it runs. One directory per logical session, at `~/.xmd/prompt/sessions/<sha256(logical-session-name)>`, replaces the single `~/.xmd/prompt` every invocation shared. A shared directory was one ambient location two conversations could both stand in; a fresh one each time would have left `--session` unable to name anything, since a session's key includes the directory it lives in. The digest gives both: a generated name reaches a location nothing else does, and the same explicit name reaches the same one, so the provider continues the session it established rather than placing a second. The leaf is the digest and never the name — a caller's string that becomes a path is a caller's string that can escape one. Emptiness is now proven rather than assumed. The directory is created empty and required to be empty before the provider is constructed or a session is materialized, and anything already in there is a terminal refusal naming the path. Nothing is deleted: what is in a directory this host did not authorize anything to write to is not this command's to clean up. Stopping on the tenth draft says two different things, and now the document says both. When that draft still has problems, `abort` is the only choice offered and there was never a Plan to approve, so it routes to the authored exhaustion message. Every other abort — including one on a tenth draft that could have been approved — stays the ordinary ending. The branch after the Session remains an exhaustive fallback. Final admission is now shown to be independently effective. A scripted draft uses a repository component that exists while the command document runs and is removed as its scope tears down; the unchanged approved bytes then fail the host's second validation, in that order, with no save, journal or execution. Both validations run the production path — leaving the component in place makes the case pass and execute, which is what makes it evidence. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Own the profile root in tests, and give a default session's directory back (#260) Two ownership corrections: one about which directories a test may touch, and one about which directories an invocation may keep. The suite no longer reads, creates or removes anything under a real `~/.xmd/prompt`. Snapshotting that root and deleting whatever appeared after the snapshot was unsafe on its face — absence from a snapshot says nothing about who created a directory, so an overlapping case or a real invocation could have its state removed by a test that never owned it. Where profile session directories live is now a host dependency: production keeps its default, and a harness names a tree it made itself, passed as a value with no flag, environment variable, document prop or replaceable context anywhere near it. `createPromptHarness` requires that root, so no case can fall back to the host's, and each root is a per-scope temporary directory removed whole — which is safe precisely because the scope created everything in it. The one case that needs two invocations to share a root says so explicitly. Only an explicitly named session needs its directory afterwards. Its identity is what a later `--session` derives the same ACPX session from, so it stays, is required empty on the way in every time, and is never cleaned. An invocation-unique default names nothing anybody can ask for again, so its directory belongs to the command: after the command document and every provider, Prompt task and Elicitation resource inside it has torn down, exactly one cleanup is attempted, and it settles before final admission, the save or the execution begins. Still empty, and the leaf is removed non-recursively. No longer empty, and the directory and its contents are preserved and the command fails terminally — this host authorized nothing to write there, and deleting a stranger's files to get on with the work is the opposite of what a ceiling is for. Being an `ensure` is what makes an abort, a failed turn and a cancellation settle the same way a success does. Which of the two applies is a trusted host value — whether the caller wrote `--session` — never inferred from the shape of the generated name, and never visible to the command document. Both outcomes are held by evidence that fails without them: disabling the cleanup leaves the leaf behind on success and before admission, and making the removal recursive turns the preserved-and-refused case into a silent success. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * ✨ Capture the problems with <Json as>, and claim the directory before making it (#260) Rebased onto `<Json as>` (#667), which supplies what the single-child `<Let>` wrapper was standing in for. Both wrappers in the packaged prompt command document are gone; `<Json value={check.diagnostics} as="problems" />` binds the serialized text directly, and the bytes reaching `<CodeBlock>` are the same bytes — the repair turn and the review presentation still carry the complete structured problems, now proven by parsing the fence back rather than by matching a substring of it. The default session's directory is now a scope-owned resource rather than a directory with an ensure attached afterwards. The release is registered before the `mkdir` that could create it, so there is no window in which a leaf exists that nothing is responsible for: a failure between making it and using it hands it back like every other ending. What the release knows is whether the directory was ever handed over, and that decides which question it is answering. Once established, the exit has exactly two outcomes and no third. Still the empty directory it was given, and the leaf is removed, non-recursively. Anything else — content that appeared, or a directory that vanished — is preserved as found and fails the command terminally. A leaf that disappears under a live conversation was silently accepted before, which was wrong twice over: nothing here is allowed to remove it, so its absence is interference, and treating interference as a clean exit would let admission, the save and the execution proceed on a conversation something else had already reached into. A directory establishment never handed over is a different question, already answered by what establishment reported. The release leaves that report and the directory's contents alone, while still handing back an empty leaf it did create. Explicitly named directories are untouched by any of this: they stay, because the next `--session` derives the same ACPX session identity from where they are. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * ✨ Make the approved Plan the result, and the workflow readable end to end (#260) The command document is now a workflow somebody can read straight through. It opens by saying what `xmd prompt` is for — a Prompt describes steps, the components carry them out, and the coding agent turns both into one document that explains and executes the sequence — and every stage after that is a heading: creating the first draft, checking and repairing it, reviewing it, continuing from the decision, returning the approved Plan. Every Plan now begins with one descriptive level-one title, and the generation, repair and revision turns each ask for it alongside the steps-beside-components structure, so a replacement cannot quietly drop either. The worked example is a titled Plan itself. This is an authorship and human-review requirement, not a rule hidden in the checker: `<CheckDraft>` reports structural facts and would accept a titleless Plan that a person would send back. `<ValidateCandidate>` is `<CheckDraft>` throughout. It checks a draft rather than validating a candidate, and nothing about what it does changed. The review choices are the words a person reads — Approve, Request changes, Stop — with no internal spelling behind them. A tenth draft that still has problems now offers something better than only stopping: Explain what went wrong makes one more ordinary turn in the same Session, carrying only the final diagnostics, because the conversation already holds the Prompt, the catalog and every draft. It asks for an explanation and explicitly not another Plan; its answer is inert text, reopens no draft limit, is reported as the coding agent's own words, and ends the command. So the host's instruction layer no longer demands that every answer be document source — it says only that an answer belongs to the message that asked for it, and each authored turn owns its own shape. The approved Plan is the command's result. By default it goes to stdout, byte for byte, with nothing this command added, so it can be piped, diffed or read before anybody commits to it. `--output` puts those bytes in a file instead, exclusively created. `--run` runs it. With both, the file is written first and only a successful write is followed by the run. `--save` is gone rather than aliased; nothing has been released to keep compatible with. That makes most execution flags conditional, so they are refused rather than ignored: a caller who asks for a journal, a permission mode or an exec deadline from a command that runs nothing has not been answered. `--include`, `--agent-provider`, `--default-agent`, `--session` and `--timeout` keep working always — they build the catalog, settle the agent, name the conversation, admit properties and bound the command. A journal exists only when `--run` begins. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 State the whole Plan requirement in every turn that asks for one (#260) A repair or a revision was told to "keep" the draft's title. That is the wrong instruction for a replacement: a draft whose title is missing, in the wrong place, or does not describe the Plan has nothing worth keeping, and an instruction to keep it asks the coding agent to carry the defect forward. Each Plan-producing turn — the first draft, each repair, each revision — now states the complete requirement on its own: optional frontmatter and then one descriptive level-one heading as the first body content, the Prompt's complete sequence as readable steps, every requested outcome, a meaningful order, and each component beside the prose describing what it does. Replacements are told to write the title the Plan needs rather than the one the last draft had. None of that reaches `<CheckDraft>`, `validateDocument()` or TypeScript. It is what the workflow asks for and what a person reviews, which is where a judgement about whether a title describes a Plan belongs. The prose under "Continue from your decision" claimed a final invalid draft left only one choice. It leaves two: ask the coding agent what went wrong, or stop. The governing documents still described the earlier command. They were swept deliberately rather than by replacing words: the opening example is a titled Plan, the flow shows the four destinations, and the failure table, timeout paragraph, acceptance rows, terminology rows, construct inventory, executable-MDX identity section, ACP lifecycle paragraph and root-props admission paragraph no longer say that an approved Plan always runs, that `--save` is the output option, that stopping is called abort, that admission is followed unconditionally by execution, or that every success writes a journal. The evidence follows the same rule. The approved introduction is pinned whole, punctuation included, rather than sampled; the requirement block is asserted against the actual initial, repair and revision turns and counted three times in the shipped source; and the run-only preflight table covers every spelling, including `-V` and `--secret-detection`. The test-local `validateCandidate` is `checkDraft`, so a terminology sweep finds no survivor of the old name. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Use the approved apostrophe, and refuse --save by name (#260) The introduction claimed to be the approved wording and was one byte away from it: `coding agent's plan` with an ASCII apostrophe where the contract has U+2019. The regression that was supposed to catch that had copied the same byte, so it pinned the file to itself rather than the file to the contract. Both now carry E2 80 99, and the fixture's comment says why it is the byte and not the sentence that is being held. Two contract passages still described the earlier command. The ACP lifecycle said the profile's scope closes before "the save and the execution"; it closes before final admission and before whichever result was asked for. The command spec said `xmd prompt` executes two root documents; it always executes the command document and executes a second only under `--run`. The terminology sweep reached the comments, messages and test names that the earlier passes left behind: "the save" in the deadline and teardown comments, the harness's `--save`, the profile's two directory failures now saying "nothing was output or run", and the review-decision comments and test names that still called stopping an abort. The unrelated abort in `runDocument` is left alone — it is about a document's own failure, not this command's. `--save` had no real proof it was gone. The case that passed it also passed two mutually exclusive permission flags, so the earlier failure decided the outcome and the assertion would have held whether or not the option still worked. That case no longer carries it, and a focused one does — on a command line that is otherwise entirely valid. Making that case honest exposed something worth fixing. `--save out.md` was refused, but as "unrecognized argument: out.md": the scanner passed the unknown option to a parser that stops at the first option it does not define and drops the rest, so what a caller heard about was the value rather than the flag. Fixed preflight now refuses an option this command does not define, by name, and names `--output` when the option was `--save`. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🤖 Say that the second root execution is optional (#260) The module contract opened by claiming `xmd prompt` owns two root document executions, and its flow diagram ended by running the second one unconditionally — one line after the line listing stdout, an `--output` file, a run, or both as the four ways the bytes are delivered. A reader following the diagram would conclude that a default invocation runs the Plan it just printed. Every invocation executes the packaged prompt command document. A second root is executed only under `--run`. The diagram now shows the four deliveries as the alternatives they are, and the paragraph after it puts the complete scope boundary where it belongs: before that optional second execution, so whatever result follows has already let go of the conversation that wrote it. The same claim opened the prompt profile's header and the Tier PR introduction, and three nearby comments still had execution as the thing that follows approval rather than one of the things that might. Corrected to the approved bytes, or to the run that may follow. Prose only: no runtime behaviour, no tests and no evidence changed. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Refuse a valued --run instead of reading it as the switch (#260) An option's name is read up to its first `=`, so `--run=false` arrived under the name of the switch and was taken for it. That set the flag saying execution had been requested, which is also what satisfies the gate refusing options that only configure a run — so `--run=false --journal trace.jsonl` was accepted. What followed is worth stating precisely, because it is not what the flag being set suggests. The ordinary parser reads `--run=false` as false and `--run=true` as the field's default, which is also false. So the command took the write path either way: `--run=false --journal <path>` completed successfully, created no journal, and never told the caller that the journal they asked for was not a thing this invocation would produce; and `--run=true` was silently answered by a command that wrote the Plan instead of running it. One half of the command believed a run had been requested and the other half did not, and neither told anybody. Every valued spelling — `--run=false`, `--run=true`, `--run=` — now fails fixed preflight, before it establishes that execution was requested and before it can answer for the gate. Nothing is loaded, built, contacted, opened, created or executed. The regressions fail without it: the scanner cases find no error, and the command-level case exits 0 where it now exits 1 — the old behaviour was a success, not an incidental failure, which is what makes the tripwires worth asserting. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Assert the session and output-file tripwires on the --run= refusal (#260) The refusal has to prove authorship never began, and the two tripwires that say so most directly were implied rather than asserted. A provider count of zero already rules out an established session, but the claim worth making is the narrow one: no session was established, and no directory was made for one to run in. The absence of an output file was likewise folded into an empty working directory rather than stated. Evidence only: no behaviour, no message and no other case changed. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 * 🐛 Pin the valued --run refusal at the parser boundary it crossed (#260) The defect was a disagreement between two layers: the scanner read `--run=false` as the switch while the parser read it as false. The command-level regression for it hand-built the scanned result and called `runPrompt` directly, so it never reached `preparePropsPhase`, the parser or dispatch — the boundary the bug lived on. It would have passed with the two layers still disagreeing. A real invocation now covers it, for `--run=false`, `--run=true` and `--run=`: the exact refusal, empty stdout so no approved Plan escaped, no unavailable-agent error because reaching a provider is what produces one, and an empty working directory holding neither the journal it named nor anything else. Both existing cases stay, because the three prove different things. The scanner table is the grammar. This one is the boundary. The direct one names the phases that stayed at zero, which a subprocess cannot see. Without the refusal this case fails at `Expected: 1 / Received: 0`, and its stderr carries the unavailable-agent error — the command line reached a provider, which is the authorship this refusal exists to prevent. Evidence only: no production change. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6 --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent e75859d commit 3948fe4

29 files changed

Lines changed: 6386 additions & 156 deletions

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ jobs:
9898
--exclude-unused-npm \
9999
--allow-all \
100100
--include packages/code-review-agent \
101+
--include packages/cli/src/documents/prompt-command.md \
101102
--target ${{ matrix.target }} \
102103
--output dist/${{ matrix.artifact }} \
103104
packages/cli/src/compiled.ts

‎architecture.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ Existing documents and code get aligned to this section retroactively.
3333
| Repository base | the optional Git revision from which one named Workspace Repository initializes its primary checkout |
3434
| pinned commit | the commit obtained by resolving a base once; it remains the workflow run's starting repository state even as the run creates descendant commits |
3535
| document target | an addressable static heading in a root document's own Markdown flow, named by the canonical path of heading labels that reaches it; selecting one executes the preamble, each ancestor's own content, and that heading's complete subtree |
36+
| Prompt | a person's original request, in ordinary natural language. `xmd prompt` takes exactly one |
37+
| Plan | the executable program produced from a Prompt: an Executable Markdown document combining readable prose that expresses the Prompt's intent with the components that carry it out, each placed beside the prose describing what it does. It begins with one descriptive level-one heading. A Plan is what `xmd prompt` approves and then delivers: printed to stdout by default, written to an `--output` file, and run only under `--run`. It is not a synonym for a workflow, a policy document or any executable Markdown file |
38+
| prompt command document | the one exact checked-in first-party Markdown value root `xmd prompt` executes to convert a Prompt into a Plan. It implements that conversion and its review workflow — the Prompt wording, the draft and repair loops, the `<CheckDraft>` branches, human review, revision, approval, stopping, exhaustion and the final explanation turn — and returns the exact approved Plan source. Every Plan-producing turn in it states the complete Plan requirements for itself, so a replacement may add or correct a title rather than only carry one forward. It is not itself a Plan. Internal: no command-line option selects another one, and no repository component search can answer for it |
39+
| prompt profile | the trusted-host assembly used only for the prompt command document: its fixed inputs, a constrained Agent provider, Elicitation, the fixed first-party components and the host-declared `<CheckDraft>`. It uses no repository component search and exposes no custom root, and the ceiling it establishes is not readable from the command line. Its working directory is one host-owned directory dedicated to the logical prompt session, keyed by the digest of that name, created empty and required to be empty on the way in. An explicitly named session's directory is durable, because continuation derives the same session identity from it; an invocation-unique default session's is scope-owned, claimed before it is created, and exactly one cleanup is attempted after profile teardown and before admission on every ending — the leaf removed non-recursively when it is still the empty directory that was handed over, and left as found with the command failing terminally when it has gained content or vanished. Where those directories live is a host dependency no caller or document selects |
3640
| expansion | one logical evaluation of an authored executable element within a document execution |
3741
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
3842
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
@@ -3541,6 +3545,7 @@ Status is measured against main.
35413545
| --- | --- | --- |
35423546
| `xmd syntax` | describes every structural construct and every selected component the production `run` profile would let a document write in the contextual working directory, as deterministic Markdown or as version-1 JSON, from one catalog. Inspection only: it registers the run profile's declarations in a bounded scope and reads the filesystem for which files exist and, for a selected Markdown component, that file's frontmatter. It runs no body, imports no repository TypeScript module, installs no provider, mints no authority and writes no journal. An include it cannot enumerate — a selection-relevant symbolic link to a directory beneath it included — fails the whole request rather than printing a healthy subset | built on the #632 stack |
35433547
| document validation | validates one supplied root projection and the recursive Markdown source closure normal component selection discovers, returning deterministic version-1 document diagnostics and `valid`, `invalid` or `not-statically-checkable` invocation outcomes without evaluating document code or installing operational host behavior | built on the #654 stack |
3548+
| `xmd prompt` | turns one Prompt into a Plan and delivers it, by executing one root document — and, only under `--run`, a second — with a complete scope boundary between them. First the packaged prompt command document, under the internal `<prompt-command>` identity, inside the prompt profile: one enclosing Session, a host ceiling of one host-owned directory dedicated to that logical session — keyed by the digest of the name, never the name, created empty and required to be empty before the provider exists or a session is materialized, refused rather than cleaned when it is not, durable when the caller named the session and handed back non-recursively after teardown when it did not — with no additional directories, no MCP servers, no native tools and a private strict denial no permission flag widens, no Files, command, service or network capability for that document, no repository component search, and one host-declared `<CheckDraft>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require every Plan to begin with one descriptive level-one title and to keep the Prompt's outcomes as readable steps with each component beside the step it performs, through repairs and revisions alike; that is an authorship and human-review requirement, and `<CheckDraft>` never enforces it. A tenth draft that still has problems may be stopped or explained: the explanation is one more ordinary turn in the same Session carrying only the final diagnostics, is inert text, reopens no draft limit, and ends the command. The host's instruction layer states only that an answer belongs to the message that asked for it, so which shape a turn wants stays in the document. Authorship sits outside durability: it runs on an invocation-owned in-memory stream that is never journaled, persisted, reused or replayed. Then, only after that execution and every provider, Prompt task and Elicitation resource inside it has torn down, the host validates the returned Plan again, resolves props for exactly those bytes, and then delivers the approved Plan where the caller asked: to stdout byte for byte by default, to an exclusively created `--output` path, and — only under `--run` — through the ordinary supplied-source path under the `<prompt>` identity, one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior. A journal exists only when `--run` begins, and the flags that configure only a run are refused in preflight without it | built on the #659 stack |
35443549
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35453550
| `<Fail message>` | stops authored work with the sentence its author wrote, raised where it is written. An ordinary overridable core default — never structural, never reserved, so a repository `Fail.md` is chosen ahead of it — with a closed schema of one required non-empty `message` and **self-closing only**: a paired spelling never enters its body, and `as` is refused by the body itself because there is nothing to bind. Every refusal reports the invocation and happens before the authored message, so a document that never reached its decision is never reported as having made one. A valid invocation is the ordinary failure of a function component: an `Error` carrying the exact authored message, positioned at the opening tag, rendering nothing and binding nothing. It carries no `printErrors()` declaration, which is what leaves recovery to an authored `<PrintErrors>` region under ordinary text-root modes; a value body's `throw` is not replaced there, so the authored failure settles the body ahead of missing-`<Return>` settlement. No authority, context, provider, resource, module state or durable operation of its own: replay of a completed root restores the recorded outcome without re-expanding the body | built on the #659 stack |
35463551
| `<Let as="name">` | binds one name in the current environment from exactly one source: the content it renders, or the exact value `value` names, bound by reference and never through the JSON boundary component props cross — the scanner resolves no JSON for that one prop, and expansion projects none. Which source it has is read from what the author wrote, before either one runs, so a construct naming both expands no child and evaluates no expression. It opens no scope, owns no resource, adds no middleware boundary and writes no journal record — replay reconstructs both sources through ordinary expansion | built on the #527 stack |

‎deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
"verify:clean": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/verify-clean.ts",
5858
"deps": "deno run --allow-all scripts/deps.ts",
5959
"deps:target": "deno run --allow-all scripts/deps-target.ts",
60-
"build": "deno task build:web && deno compile --node-modules-dir=none --cached-only --frozen --exclude-unused-npm --allow-all --include packages/code-review-agent --output dist/xmd packages/cli/src/compiled.ts",
60+
"build": "deno task build:web && deno compile --node-modules-dir=none --cached-only --frozen --exclude-unused-npm --allow-all --include packages/code-review-agent --include packages/cli/src/documents/prompt-command.md --output dist/xmd packages/cli/src/compiled.ts",
6161
"build:web": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/preflight.ts scripts/build-web-client.ts",
6262
"gen:publish-workflow": "deno run --allow-all packages/cli/src/deno.ts run scripts/gen-publish-workflow.md",
6363
"bump": "deno run -A scripts/bump-version.ts",

‎packages/cli/src/agent-stack.ts‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
/**
2+
* The one Agent configuration an invocation resolves, and the two things a
3+
* host does with it (specs/acp-client-spec.md §Command-line configuration).
4+
*
5+
* `xmd run` and `xmd prompt` take the same Agent, permission and provider
6+
* options, so they resolve them once, here, rather than each reading the flags
7+
* again. What they do with the result differs, and deliberately: a run installs
8+
* the registered provider into the Agent Api so a document may reach it, while
9+
* `xmd prompt` hands the same answer to two consumers — the prompt profile, which
10+
* takes the provider name and the default agent and nothing else, and the
11+
* approved document, which runs the ordinary run stack.
12+
*
13+
* `agent-config.ts` stays the pure flag-to-permission mapping. This module is
14+
* where the environment, the provider registry and the host's own machine
15+
* session assembly enter.
16+
*/
17+
18+
import {
19+
installAgentComponents,
20+
installPermissionMode,
21+
registerAgentProvider,
22+
} from "@executablemd/core";
23+
import type { AgentProviderFactory, PermissionMode } from "@executablemd/core";
24+
import { installForegroundLauncher, env as readEnv } from "@executablemd/runtime";
25+
import { createAcpxProvider, DEFAULT_AGENT_NAME } from "@executablemd/acp";
26+
import type { AcpxProviderDependencies } from "@executablemd/acp";
27+
import { Err, Ok } from "effection";
28+
import type { Operation, Result } from "effection";
29+
30+
import { resolveAgentConfig } from "./agent-config.ts";
31+
import type { AgentFlags } from "./agent-config.ts";
32+
import type { MachineSessionAssembly } from "./session-coordinator.ts";
33+
34+
/** Everything one invocation settled about agents, resolved exactly once. */
35+
export interface AgentStack {
36+
/** The provider name the caller selected, already known to be registered. */
37+
provider: string;
38+
/** The agent every consumer defaults to, environment fallback applied. */
39+
defaultAgent: string;
40+
permissionMode: PermissionMode;
41+
/** What this host states about machine-wide agent sessions, if anything. */
42+
sessions?: MachineSessionAssembly;
43+
}
44+
45+
/**
46+
* Read the command line, the environment and the host's assembly into one
47+
* configuration.
48+
*
49+
* A failure comes back as a `Result` rather than as a printed line and an exit,
50+
* so the same resolution serves a command that runs a document and one that
51+
* generates one first.
52+
*/
53+
export function* resolveAgentStack(
54+
flags: AgentFlags,
55+
sessions: MachineSessionAssembly | undefined,
56+
): Operation<Result<AgentStack>> {
57+
const config = resolveAgentConfig(flags);
58+
if ("error" in config) {
59+
return Err(new Error(config.error));
60+
}
61+
if (flags.agentProvider !== "acpx") {
62+
return Err(new Error(`Unknown agent provider "${flags.agentProvider}"`));
63+
}
64+
const defaultAgent =
65+
config.defaultAgent ?? (yield* readEnv("DEFAULT_AGENT_NAME")) ?? DEFAULT_AGENT_NAME;
66+
return Ok({
67+
provider: flags.agentProvider,
68+
defaultAgent,
69+
permissionMode: config.permissionMode,
70+
...(sessions === undefined ? {} : { sessions }),
71+
});
72+
}
73+
74+
/**
75+
* What this host built, if it built anything.
76+
*
77+
* Each piece reaches the provider directly rather than through a context: who
78+
* owns a session and which build it belongs to are security decisions, and ones
79+
* a document could replace are not ones. The two advertised sets are stated by
80+
* the host, not inherited.
81+
*/
82+
export function hostAcpDependencies(
83+
sessions: MachineSessionAssembly | undefined,
84+
): AcpxProviderDependencies {
85+
if (sessions === undefined) {
86+
return {};
87+
}
88+
return {
89+
...(sessions.coordinator ? { coordinator: sessions.coordinator } : {}),
90+
...(sessions.routeStore ? { routeStore: sessions.routeStore } : {}),
91+
...(sessions.executableObserver ? { executableObserver: sessions.executableObserver } : {}),
92+
advertiseNativeLaunch: sessions.advertiseNativeLaunch,
93+
advertiseClientNativeAttachment: sessions.advertiseClientNativeAttachment,
94+
};
95+
}
96+
97+
/**
98+
* Install the agent stack a document runs under: the registration, the
99+
* components with the resolved root provider, the permission mode, and the
100+
* terminal this command has to give away.
101+
*
102+
* Nothing starts an agent — the provider validates availability on first use.
103+
*/
104+
export function* installRunAgentStack(stack: AgentStack): Operation<void> {
105+
const acpx = createAcpxProvider(hostAcpDependencies(stack.sessions));
106+
yield* registerAgentProvider("acpx", acpx);
107+
108+
// The trusted host selects its own root provider by name. Document-level
109+
// selection goes through the installation protocol; this is the host saying
110+
// what it configured, which no document is composing around.
111+
const providers: Record<string, AgentProviderFactory> = { acpx };
112+
const factory = providers[stack.provider];
113+
const { defaultAgent, permissionMode } = stack;
114+
yield* installAgentComponents({
115+
defaultAgent,
116+
permissionMode,
117+
rootProvider: { factory, options: { defaultAgent, permissionMode } },
118+
});
119+
yield* installPermissionMode(permissionMode);
120+
// `xmd run` is the one command that has a terminal to give away. Help,
121+
// document inspection and `xmd test` install no launcher, so a document that
122+
// reaches <Session.Launch> under any of them refuses instead of spawning.
123+
yield* installForegroundLauncher();
124+
}

0 commit comments

Comments
 (0)