Skip to content

Commit 9ee0c40

Browse files
committed
🐛 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
1 parent e06e783 commit 9ee0c40

8 files changed

Lines changed: 373 additions & 75 deletions

File tree

‎architecture.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Existing documents and code get aligned to this section retroactively.
3636
| Prompt | a person's original request, in ordinary natural language. `xmd prompt` takes exactly one |
3737
| 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 |
3838
| 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 |
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. 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 remain empty |
4040
| expansion | one logical evaluation of an authored executable element within a document execution |
4141
| 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 |
4242
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
@@ -3545,7 +3545,7 @@ Status is measured against main.
35453545
| --- | --- | --- |
35463546
| `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 |
35473547
| 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 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 |
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 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, and refused rather than cleaned when it is 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 `<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 |
35493549
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35503550
| `<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 |
35513551
| `<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 |

‎packages/cli/src/documents/prompt-command.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,19 @@ Three attempts to fix it did not clear everything. These problems remain:
139139
<Break />
140140
</If>
141141

142+
Stopping says two different things depending on where you are. On the tenth
143+
draft, when it still has problems, `abort` is the only choice left and there was
144+
never a Plan to approve — so that ending says so. Everywhere else, including a
145+
tenth draft you could have approved, stopping is your decision and is reported
146+
as one.
147+
142148
<If condition={review.decision === "abort"}>
149+
<If condition={round === 10 && !check.valid}>
150+
<Fail message="xmd prompt: ten drafts were reviewed and none was approved, so nothing was saved and nothing ran. Try again with a more specific request." />
151+
<Else>
143152
<Fail message="xmd prompt: you ended the review, so nothing was saved and nothing ran." />
153+
</Else>
154+
</If>
144155
</If>
145156

146157
<Prompt as="draft">
@@ -157,8 +168,9 @@ explanation.
157168

158169
</Session>
159170

160-
If you approved a document, return its source unchanged. Otherwise, stop without
161-
saving or running anything.
171+
If you approved a document, return its source unchanged. Nothing should reach
172+
this point without approving or stopping first, so the other branch says what it
173+
would mean if anything did.
162174

163175
<If condition={approved !== null}>
164176
<Return value={approved} />

‎packages/cli/src/prompt-profile.ts‎

Lines changed: 77 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,18 @@
55
*
66
* `xmd prompt` owns two root document executions with a complete scope boundary
77
* between them. This module is the first one. It supplies that document's
8-
* inputs, a
9-
* constrained Agent provider, Elicitation, the fixed first-party components and
10-
* the host-declared candidate validator, and it exposes no custom root and no
11-
* repository component search: the program it runs is the one the CLI ships.
8+
* inputs, a constrained Agent provider, Elicitation, the fixed first-party
9+
* components and the host-declared draft validator, and it exposes no custom
10+
* root and no repository component search: the document it runs is the one the
11+
* CLI ships.
1212
*
1313
* The Agent ceiling is assembled here rather than read from the command line,
1414
* because it is not the caller's to choose. Writing a Plan is a conversation
15-
* about text; it never lets an agent touch anything. So the provider gets a fresh empty
16-
* directory of this host's own, no additional directories, no MCP servers, an
17-
* empty native-tool allowlist and a private strict denial of every native
15+
* about text; it never lets an agent touch anything. So the provider gets a
16+
* host-owned directory dedicated to this logical session — created empty, and
17+
* required to be empty before anything is built — no additional directories, no
18+
* MCP servers, an empty native-tool allowlist and a private strict denial of
19+
* every native
1820
* permission request — one that answers inside the provider and consults no
1921
* authored approval scope, so nothing composed around it can widen a ceiling
2022
* with nothing in it. `--approve-all`, `--approve-reads` and `--deny-all`
@@ -26,7 +28,8 @@
2628

2729
import { Err, Ok, scoped, until } from "effection";
2830
import type { Operation, Result } from "effection";
29-
import { mkdir } from "node:fs/promises";
31+
import { createHash } from "node:crypto";
32+
import { mkdir, readdir } from "node:fs/promises";
3033
import { homedir } from "node:os";
3134
import { join } from "node:path";
3235

@@ -122,8 +125,16 @@ export function* runPromptCommandDocument(profile: PromptProfile): Operation<Res
122125
);
123126
}
124127

128+
// Before the provider exists, and therefore before a session could be placed
129+
// or a turn started: this session's directory is established and proven empty,
130+
// or the command stops here.
131+
const established = yield* useProfileDirectory(profile.session);
132+
if (!established.ok) {
133+
return established;
134+
}
135+
const workdir = established.value;
136+
125137
return yield* scoped(function* (): Operation<Result<string>> {
126-
const workdir = yield* useProfileDirectory();
127138
yield* refuseDocumentCapabilities();
128139
yield* profile.installElicitation();
129140

@@ -215,8 +226,9 @@ function validator(profile: PromptProfile): IdentityComponent {
215226
/**
216227
* The Agent ceiling, stated as the dependencies the provider is built from.
217228
*
218-
* Each entry is the whole of one clause: the working directory the agent runs
219-
* in, the MCP servers it configures, the native tools a fresh session may use,
229+
* Each entry is the whole of one clause: the directory the agent runs in — this
230+
* session's own, proven empty above — the MCP servers it configures, the native
231+
* tools a fresh session may use,
220232
* and who answers a native permission request. `mcpServers: []` and
221233
* `allowedTools: []` are statements rather than omissions — leaving either off
222234
* is the backend's default, which is not this host's.
@@ -258,24 +270,64 @@ export const PROMPT_INSTRUCTIONS = [
258270
].join("\n");
259271

260272
/**
261-
* Where the assistant runs while it writes a Plan: this host's own directory,
262-
* and an empty one.
273+
* Where every profile directory lives.
263274
*
264-
* The caller's working directory is deliberately not offered — an agent writing
265-
* a document has no reason to read the tree it will run in, and a ceiling that
266-
* starts at the caller's checkout is not a ceiling. Nothing this profile grants
267-
* can write here either, so what is created empty stays empty.
275+
* Under this host's own state directory rather than the caller's tree: an agent
276+
* writing a document has no reason to read the checkout it will run in, and a
277+
* ceiling that starts there is not a ceiling.
278+
*/
279+
export const PROMPT_PROFILE_SESSIONS: string = join(homedir(), ".xmd", "prompt", "sessions");
280+
281+
/**
282+
* The directory one logical session's conversation runs in.
268283
*
269-
* One fixed path rather than a new directory each time, because a session's
270-
* identity includes the directory it lives in: a location that changed every
271-
* invocation would mean `--session` could never name a conversation that
272-
* already exists, which is the whole of what that option is for.
284+
* Dedicated to that session rather than shared by every invocation, so two
285+
* conversations never see one ambient directory. The leaf is the digest of the
286+
* name and never the name itself: a logical session name is a caller's string,
287+
* and a caller's string that becomes a path is a caller's string that can escape
288+
* one.
289+
*
290+
* A digest also gives the identity `--session` needs. The generated
291+
* invocation-unique name digests to a location nothing else reaches, while the
292+
* same explicit name digests to the same one — which is what lets ACPX find the
293+
* session record it established last time, since a session's key includes the
294+
* directory it lives in.
273295
*/
274-
export const PROMPT_PROFILE_DIRECTORY: string = join(homedir(), ".xmd", "prompt");
296+
export function profileDirectoryFor(session: string): string {
297+
return join(PROMPT_PROFILE_SESSIONS, createHash("sha256").update(session).digest("hex"));
298+
}
275299

276-
function* useProfileDirectory(): Operation<string> {
277-
yield* until(mkdir(PROMPT_PROFILE_DIRECTORY, { recursive: true }));
278-
return PROMPT_PROFILE_DIRECTORY;
300+
/**
301+
* Establish that directory, or refuse.
302+
*
303+
* Created empty, and required to be empty every time — not cleaned. Whatever is
304+
* in there was put there by something this host did not authorize, and deleting
305+
* a stranger's files to get on with the work is the opposite of what a ceiling
306+
* is for. So the command says what it found and where, and stops.
307+
*/
308+
function* useProfileDirectory(session: string): Operation<Result<string>> {
309+
const directory = profileDirectoryFor(session);
310+
try {
311+
yield* until(mkdir(directory, { recursive: true }));
312+
const entries = yield* until(readdir(directory));
313+
if (entries.length > 0) {
314+
return Err(
315+
new Error(
316+
`${directory} is not empty, and xmd prompt writes a Plan in a directory of its own ` +
317+
"with nothing in it. Move or remove what is in there, or name a different " +
318+
"--session; nothing was written or run",
319+
),
320+
);
321+
}
322+
return Ok(directory);
323+
} catch (error) {
324+
return Err(
325+
new Error(
326+
`could not establish ${directory}: ` +
327+
(error instanceof Error ? error.message : String(error)),
328+
),
329+
);
330+
}
279331
}
280332

281333
/**

0 commit comments

Comments
 (0)