Skip to content

Commit de53362

Browse files
committed
✨ 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
1 parent e75859d commit de53362

17 files changed

Lines changed: 3308 additions & 124 deletions

‎architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3541,6 +3541,7 @@ Status is measured against main.
35413541
| --- | --- | --- |
35423542
| `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 |
35433543
| 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 |
35443545
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35453546
| `<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 |
35463547
| `<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/agent-stack.ts‎

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

0 commit comments

Comments
 (0)