Skip to content

Commit e06e783

Browse files
committed
✨ 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
1 parent a22c7b1 commit e06e783

22 files changed

Lines changed: 1685 additions & 1130 deletions

‎.github/workflows/release.yml‎

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

‎architecture.md‎

Lines changed: 5 additions & 1 deletion
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. A Plan is what `xmd prompt` approves, optionally saves and runs; 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 request wording, the draft and repair loops, the check branches, human review, revision, approval, abort and exhaustion — and returns the exact approved Plan source. 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 draft validator. It uses no repository component search and exposes no custom root, and the ceiling it establishes is not readable from the command line |
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,7 +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 |
3544-
| `xmd prompt` | asks the configured agent for a complete executable Markdown root, validates it without executing any of it, repairs its definite defects by asking again at most three times per draft, shows a person the exact bytes, and executes the approved ones through the ordinary supplied-source path under the `<prompt>` identity. Authorship sits outside durability: the catalog, the fresh generator session, every repair and the review create no journal, retain no durable identity and replay nothing, and the generator's scope closes before the optional exclusive save and before execution. What runs is one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior. A defect the draft authored is repairable; one the command line authored terminates without spending a turn on it | built on the #656 stack |
3548+
| `xmd prompt` | turns one Prompt into a Plan and runs it, by executing two root documents 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 an empty host-owned working directory 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 `<ValidateCandidate>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require the Plan to keep every requested outcome as reader-facing prose with each component beside the sentences describing it, through repairs and revisions alike, and prose quality stays that document's policy rather than a TypeScript rule. 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, optionally creates the save exclusively, and executes them 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 | built on the #659 stack |
35453549
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35463550
| `<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 |
35473551
| `<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 --include packages/cli/src/documents/prompt-plan.md --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: 5 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,24 @@
66
* options, so they resolve them once, here, rather than each reading the flags
77
* again. What they do with the result differs, and deliberately: a run installs
88
* the registered provider into the Agent Api so a document may reach it, while
9-
* prompt generation holds a provider handle of its own and installs no document
10-
* components, no root provider and no foreground launcher — it needs turns, not
11-
* authority.
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.
1212
*
1313
* `agent-config.ts` stays the pure flag-to-permission mapping. This module is
1414
* where the environment, the provider registry and the host's own machine
1515
* session assembly enter.
1616
*/
1717

1818
import {
19-
Agent,
2019
installAgentComponents,
2120
installPermissionMode,
2221
registerAgentProvider,
2322
} from "@executablemd/core";
2423
import type { AgentProviderFactory, PermissionMode } from "@executablemd/core";
2524
import { installForegroundLauncher, env as readEnv } from "@executablemd/runtime";
26-
import { createAcpxProvider, DEFAULT_AGENT_NAME, useAcpxProvider } from "@executablemd/acp";
27-
import type { AcpxProvider, AcpxProviderDependencies } from "@executablemd/acp";
25+
import { createAcpxProvider, DEFAULT_AGENT_NAME } from "@executablemd/acp";
26+
import type { AcpxProviderDependencies } from "@executablemd/acp";
2827
import { Err, Ok } from "effection";
2928
import type { Operation, Result } from "effection";
3029

@@ -123,52 +122,3 @@ export function* installRunAgentStack(stack: AgentStack): Operation<void> {
123122
// reaches <Session.Launch> under any of them refuses instead of spawning.
124123
yield* installForegroundLauncher();
125124
}
126-
127-
/**
128-
* A provider that can run turns, and nothing else.
129-
*
130-
* `xmd prompt` writes a document before one exists, so there is nothing to
131-
* install components into and no launch for anyone to authorize. It takes the
132-
* provider's operations directly and answers only the one Agent operation the
133-
* provider itself performs — resolving the agent a session and a turn belong
134-
* to. Everything else on the Agent Api stays at its base behavior, so a launch
135-
* or a document prompt reaching this scope is refused rather than served.
136-
*
137-
* The permission policy is installed first, so it encloses the provider state's
138-
* own scope and answers the native permission requests generation raises with
139-
* the same `--approve-all`, `--approve-reads` or `--deny-all` choice a run uses.
140-
*
141-
* `instructions` become the fresh session's system prompt. They reach ACPX
142-
* through `newSessionOptions`, which it applies when it creates a session and
143-
* ignores when it reuses a record.
144-
*/
145-
export function* useGeneratorAgent(
146-
stack: AgentStack,
147-
instructions: string,
148-
dependencies?: AcpxProviderDependencies,
149-
): Operation<AcpxProvider> {
150-
yield* installPermissionMode(stack.permissionMode);
151-
152-
let provider: AcpxProvider | undefined;
153-
yield* Agent.around(
154-
{
155-
*agent([name], _next) {
156-
if (provider === undefined) {
157-
throw new Error("the generator agent provider is not established yet");
158-
}
159-
return yield* provider.agent(name);
160-
},
161-
},
162-
{ at: "min" },
163-
);
164-
165-
provider = yield* useAcpxProvider(
166-
{ defaultAgent: stack.defaultAgent, permissionMode: stack.permissionMode },
167-
{
168-
...hostAcpDependencies(stack.sessions),
169-
...dependencies,
170-
newSessionOptions: { systemPrompt: instructions },
171-
},
172-
);
173-
return provider;
174-
}

‎packages/cli/src/cli.ts‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ import {
109109
resolvePropsFromSources,
110110
} from "./props.ts";
111111
import type { Binding, Extraction } from "./props.ts";
112-
import { namesPrompt, scanPromptArgs, SAVE_OPTION } from "./prompt-args.ts";
112+
import { namesPrompt, scanPromptArgs, SAVE_OPTION, SESSION_OPTION } from "./prompt-args.ts";
113113
import type { PromptScan } from "./prompt-args.ts";
114114
import { runPrompt } from "./prompt.ts";
115115
import type { PromptExecution } from "./prompt.ts";
@@ -256,6 +256,10 @@ const promptConfig = object({
256256
description: "write the approved document here before running it (path must not exist)",
257257
...field(z.string().optional()),
258258
},
259+
session: {
260+
description: "logical name for the assistant session (default: unique to this invocation)",
261+
...field(z.string().optional()),
262+
},
259263
...executionFields,
260264
});
261265

@@ -907,9 +911,9 @@ export interface PromptExecutionConfig {
907911
* How `xmd prompt` runs the document a person approved: exactly as `xmd run`
908912
* runs a supplied one.
909913
*
910-
* The generator's scope is already gone by the time this is called, so the
914+
* The prompt profile's scope is already gone by the time this is called, so the
911915
* executed program gets a fresh ordinary Agent provider and inherits neither
912-
* the generator session nor its system prompt. The browser form is composed
916+
* the assistant session nor its instruction layer. The browser form is composed
913917
* around the document for the same reason a run composes one: `xmd prompt` is a
914918
* command a person is sitting in front of.
915919
*/
@@ -938,7 +942,7 @@ export function promptExecutor(
938942
props: approved.props,
939943
...(sessions === undefined ? {} : { machineSessions: sessions }),
940944
// The same object generation was configured from. The provider it
941-
// installs is a fresh ordinary one — the generator's scope is already
945+
// installs is a fresh ordinary one — the profile's scope is already
942946
// gone — but which agent it defaults to and what it may do were
943947
// decided once, for the whole invocation.
944948
agent: stack,
@@ -1659,8 +1663,11 @@ const PROMPT_REQUEST_HELP = [
16591663
"path. Quote it so the shell passes it as a single argument:",
16601664
' xmd prompt "ask me for my age and write the result to a file"',
16611665
"",
1662-
"The agent writes a complete document, xmd validates it and repairs definite",
1663-
"defects, and you approve, revise or abort before anything runs.",
1666+
"A first-party command document turns your request into a Plan: an executable",
1667+
"Markdown document that states what you asked for in ordinary language and",
1668+
"places the components that do the work alongside those words. xmd checks each",
1669+
"draft and repairs definite defects; you approve, revise or abort before",
1670+
"anything runs.",
16641671
"",
16651672
"Document properties follow the request. The individual options a document",
16661673
"declares are the generated document's, so they are not listed here:",
@@ -1673,6 +1680,13 @@ const PROMPT_REQUEST_HELP = [
16731680
` ${SAVE_OPTION} <path>`,
16741681
" Write the approved document there before running it. The path must not",
16751682
" exist; an existing one is left alone and the run stops.",
1683+
"",
1684+
` ${SESSION_OPTION} <name>`,
1685+
" Use this logical assistant session instead of one unique to this run.",
1686+
"",
1687+
"Permission flags configure the approved document. Writing the Plan is a",
1688+
"conversation about text and gives the assistant nothing: an empty directory of",
1689+
"its own, no tools, no MCP servers, and every native permission request denied.",
16761690
].join("\n");
16771691

16781692
/**
@@ -1900,7 +1914,7 @@ function* dispatch(
19001914
yield* exit(1);
19011915
break;
19021916
}
1903-
// Once, here, and handed to both consumers below. Generation and the
1917+
// Once, here, and handed to both consumers below. Authorship and the
19041918
// execution that follows it are one invocation, so they answer to one
19051919
// `--default-agent`, one `DEFAULT_AGENT_NAME` and one permission mode.
19061920
const promptStack = yield* settleAgentStack(
@@ -1922,6 +1936,7 @@ function* dispatch(
19221936
scan,
19231937
include: config.include,
19241938
...(config.save === undefined ? {} : { save: config.save }),
1939+
...(config.session === undefined ? {} : { session: config.session }),
19251940
stack: promptStack,
19261941
},
19271942
{
@@ -2137,7 +2152,7 @@ export function* runXmd(
21372152
const provisional = xmd.parse({ args: helpRequest.args });
21382153
const selected = provisional.ok ? provisional.value.config : undefined;
21392154
// The two commands that end in a document execution. `xmd prompt`'s deadline
2140-
// encloses more than a run's — the catalog, the generator session, every
2155+
// encloses more than a run's — the catalog, the assistant session, every
21412156
// repair, the human review, provider teardown, the save and the execution —
21422157
// because all of it is what the caller asked to be bounded.
21432158
const executes =

0 commit comments

Comments
 (0)