Skip to content

Commit f49c528

Browse files
committed
🐛 Match REPL syntax to the ordinary entry profile
1 parent 40a3635 commit f49c528

7 files changed

Lines changed: 386 additions & 50 deletions

File tree

‎packages/cli/src/documents/sidekick/entries.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,13 @@ Sidekick responses that write an entry, and the REPL entry program they write.
1212
- Your response and the entry you prepare are two different XMD documents. A
1313
component admitted in an entry is not thereby admitted in your response. List
1414
the entry vocabulary with `<REPL.Syntax />` and read a named component with
15-
`<REPL.Syntax names={["Elicit"]} />`.
15+
`<REPL.Syntax names={["Elicit"]} />`. Availability means the component resolves
16+
in an ordinary entry; each effect still requires permission and can fail.
17+
Fresh asks read current session components and this command's selected Plugins.
18+
- Built-in assertions absent from the ordinary entry profile are Markdown-test
19+
components. Named lookup explains their test context and `REPL.Test` invocation.
20+
Save the test document and request it with `REPL.Test`; submitting assertions as
21+
an ordinary entry does not activate testing.
1622
- Quoted props are strings: `as="code"`. Braced props supply data:
1723
`limit={16384}`, `entry={-2}`, `names={["Elicit"]}`.
1824
- In a response, braced props accept JSON literals, arrays, objects, object

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

Lines changed: 107 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import { agentIdentityComponents } from "@executablemd/core";
1414
import type { PermissionMode } from "@executablemd/core";
1515
import type { GeneratedSelection } from "@executablemd/core/api";
1616
import type { ExecutionInstallation } from "@executablemd/core/host";
17-
import { useScope } from "effection";
17+
import { scoped, useScope } from "effection";
1818
import { cwd } from "@executablemd/runtime";
1919
import { resolve, join } from "node:path";
2020
import type { Operation } from "effection";
@@ -33,7 +33,10 @@ import { runReplProgram } from "./repl/program.ts";
3333
import type { ReplInputPass } from "./repl/program.ts";
3434
import { ReplEntryHost } from "./repl-entry-installation.ts";
3535
import type { ReplEntryInstallation } from "./repl-entry-installation.ts";
36-
import { renderSyntaxDocumentation, renderSyntaxMarkdown, syntaxSymbols } from "./syntax.ts";
36+
import { inspectSyntax, renderSyntaxMarkdown } from "@executablemd/core";
37+
import { Component, Syntax } from "@executablemd/core/api";
38+
import { useSyntax } from "@executablemd/core/host";
39+
import { useTestingComponents } from "@executablemd/testing";
3740

3841
const REPL_INCLUDES: readonly string[] = Object.freeze(["components", "."]);
3942

@@ -288,25 +291,26 @@ export function* assembleReplProfile(
288291
installElicitation: noElicitationOfItsOwn,
289292
});
290293

294+
const entryInstallations = Object.freeze([
295+
...installations,
296+
children.installation,
297+
Object.freeze({
298+
components: agentIdentityComponents(),
299+
declarations: Object.freeze([plan]),
300+
}),
301+
]);
291302
const profile = Object.freeze({
292303
children,
293304
mounts,
294305
includes,
295306
projectCwd,
296-
vocabulary: entryVocabulary(includes, plugins, children.installation.components),
307+
vocabulary: entryVocabulary(includes, entryInstallations),
297308
// Read off the admitted assembly here, once, while it is in hand. Copied
298309
// rather than referenced so nothing downstream can reach a Plugin value
299310
// through the profile, and frozen because a profile is read and never
300311
// changed.
301312
plugins: names,
302-
installations: Object.freeze([
303-
...installations,
304-
children.installation,
305-
Object.freeze({
306-
components: agentIdentityComponents(),
307-
declarations: Object.freeze([plan]),
308-
}),
309-
]),
313+
installations: entryInstallations,
310314
generated: ordinaryGeneratedSelection(),
311315
permissionMode,
312316
...(entryInstallation === undefined ? {} : { entryInstallation }),
@@ -329,33 +333,108 @@ export function* assembleReplProfile(
329333
});
330334
}
331335

332-
/**
333-
* Describe one profile's entry vocabulary, through the machinery `xmd syntax` uses.
334-
*
335-
* One construction for both questions, and the same one the command line
336-
* answers from: an operator printing the vocabulary and a reply asking about it
337-
* are asking about one language, and two renderings that agreed only by hand
338-
* would be one release away from disagreeing.
339-
*
340-
* Exported because a profile assembled for a proof describes the same vocabulary
341-
* as a profile assembled for a command — the includes and the Plugins differ,
342-
* and nothing else does.
343-
*/
336+
/** Describe the finalized entry installations without acquiring their resources. */
344337
export function entryVocabulary(
345338
includes: readonly string[],
346-
plugins: CommandPlugins,
347-
components: import("@executablemd/core/host").ExecutionInstallation["components"] = [],
339+
installations: readonly ExecutionInstallation[] = [],
348340
): EntryVocabulary {
341+
function* ordinary() {
342+
return {
343+
includes: [...includes],
344+
registry: new Map(yield* Component.operations.registry),
345+
components: installations.flatMap((one) =>
346+
(one.components ?? []).map((item) => ({ ...item })),
347+
),
348+
declarations: installations.flatMap((one) =>
349+
(one.declarations ?? []).map((item) => ({ ...item })),
350+
),
351+
};
352+
}
349353
return Object.freeze({
350-
*symbols(): Operation<string> {
351-
return renderSyntaxMarkdown(yield* syntaxSymbols(includes, plugins, components));
354+
symbols(): Operation<string> {
355+
return scoped(function* () {
356+
const inputs = yield* ordinary();
357+
yield* useSyntax(() => inspectSyntax(inputs));
358+
return (
359+
renderSyntaxMarkdown(yield* Syntax.operations.symbols) +
360+
"\nMarkdown test components are documented by name with REPL.Syntax and run through REPL.Test.\n" +
361+
ENTRY_AVAILABILITY
362+
);
363+
});
352364
},
353365
documentation(names: readonly string[]): Operation<string> {
354-
return renderSyntaxDocumentation(includes, names, plugins, components);
366+
return scoped(function* () {
367+
const inputs = yield* ordinary();
368+
const runnable = yield* inspectSyntax(inputs);
369+
const ordinaryNames = new Set(
370+
runnable.categories.flatMap((category) => category.entries.map((entry) => entry.name)),
371+
);
372+
// Inspect testing separately so reference registrations cannot replace
373+
// an ordinary selection or read its moving session files a second time.
374+
yield* useTestingComponents();
375+
const testing = yield* inspectSyntax({ includes: [] });
376+
const readable = {
377+
...runnable,
378+
categories: [
379+
runnable.categories[0],
380+
{
381+
...runnable.categories[1],
382+
entries: [
383+
...runnable.categories[1].entries,
384+
...testing.categories[1].entries.filter((entry) => !ordinaryNames.has(entry.name)),
385+
].sort((left, right) => {
386+
if (left.name < right.name) {
387+
return -1;
388+
}
389+
return left.name > right.name ? 1 : 0;
390+
}),
391+
},
392+
runnable.categories[2],
393+
],
394+
} satisfies import("@executablemd/core").SyntaxSymbols;
395+
yield* useSyntax(function* () {
396+
return readable;
397+
});
398+
yield* Syntax.around({
399+
symbols: function* () {
400+
return runnable;
401+
},
402+
});
403+
const documentation = yield* Syntax.operations.documentation(names);
404+
return (
405+
documentation +
406+
ENTRY_AVAILABILITY +
407+
(names.some((name) => !ordinaryNames.has(name)) ? TEST_CONTEXT : "")
408+
);
409+
});
355410
},
356411
});
357412
}
358413

414+
const ENTRY_AVAILABILITY =
415+
"\nAvailability describes resolution in an ordinary entry, not permission to perform every effect or a guarantee of success.\n";
416+
417+
const TEST_CONTEXT = `
418+
Components marked unavailable cannot run in an ordinary entry. Use them in a Markdown test
419+
requested through REPL.Test. Save this complete test as the session-relative
420+
\`components/assertions.test.md\`:
421+
422+
\`\`\`xmd
423+
<Test name="assertions">
424+
<Assert expr={true} />
425+
<AssertEquals actual="yes" expected="yes" />
426+
</Test>
427+
\`\`\`
428+
429+
Then write this in a Sidekick response:
430+
431+
\`\`\`xmd
432+
<REPL.Test path="components/assertions.test.md" />
433+
\`\`\`
434+
435+
The file runs as a test document; do not submit it as an ordinary entry.
436+
`;
437+
359438
/**
360439
* The Plan Component's elicitation installer, which installs nothing.
361440
*

‎packages/cli/tests/fixtures/repl/issue-883/sidekick-harness.ts‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ import { installReplHost } from "../../../../src/repl-assembly.ts";
3232
import { resolveAgentStack } from "../../../../src/agent-stack.ts";
3333
import { assembleReplProfile } from "../../../../src/repl-profile.ts";
3434
import type { ReplExecutionProfile } from "../../../../src/repl-profile.ts";
35-
import { NO_PLUGINS } from "../../../../src/plugin-host.ts";
35+
import { installPlugins } from "../../../../src/plugin-host.ts";
36+
import type { Plugin } from "@executablemd/core/api";
3637
import { openReplSession } from "../../../../src/repl/session.ts";
3738
import type { ReplSession } from "../../../../src/repl/session.ts";
3839
import { admitted, filled, initialState } from "../../../../src/repl/application.ts";
@@ -113,6 +114,7 @@ export function* useHarness(
113114
* being admitted, and that interval is inside the entry's execution.
114115
*/
115116
readonly entryInstallation?: ExecutionInstallation;
117+
readonly plugins?: readonly Plugin[];
116118
readonly state?: (initial: ReplState) => ReplState;
117119
readonly acknowledge?: () => Operation<void>;
118120
/**
@@ -160,19 +162,23 @@ export function* useHarness(
160162
throw stack.error;
161163
}
162164
const workspace = pairedLocation(join(dataRoot, "repl"), execution.id).directory;
163-
const profile = yield* (yield* assembleReplProfile(stack.value, NO_PLUGINS, {
164-
acp: {
165-
createRuntime: fake.create,
166-
sessionStore: makeStore(),
167-
agentRegistry: makeRegistry({ [AGENT]: `${AGENT}-cmd` }),
165+
const profile = yield* (yield* assembleReplProfile(
166+
stack.value,
167+
yield* installPlugins(extra.plugins ?? [], { command: "repl", args: [] }),
168+
{
169+
acp: {
170+
createRuntime: fake.create,
171+
sessionStore: makeStore(),
172+
agentRegistry: makeRegistry({ [AGENT]: `${AGENT}-cmd` }),
173+
},
174+
// The scripted agent, named to the profile rather than left to the
175+
// environment: the Sidekick assembly is built with it, and a conversation
176+
// opened under an agent this registry does not know would fail as an
177+
// availability refusal rather than reaching the fake.
178+
sidekickAgent: AGENT,
179+
planWriterRoot: yield* useTemporary("xmd-sidekick-plan-"),
168180
},
169-
// The scripted agent, named to the profile rather than left to the
170-
// environment: the Sidekick assembly is built with it, and a conversation
171-
// opened under an agent this registry does not know would fail as an
172-
// availability refusal rather than reaching the fake.
173-
sidekickAgent: AGENT,
174-
planWriterRoot: yield* useTemporary("xmd-sidekick-plan-"),
175-
})).finalize(workspace);
181+
)).finalize(workspace);
176182

177183
const opened = yield* openReplSession({
178184
execution,

‎packages/cli/tests/repl-agent-interface.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -466,7 +466,7 @@ const PROFILE: ReplExecutionProfile = {
466466
// opens a Sidekick conversation.
467467
sidekickAssembly: sidekickAssembly(DEFAULT_AGENT_NAME, {}),
468468
plugins: NO_PLUGINS.plugins.map((plugin) => plugin.name),
469-
vocabulary: entryVocabulary([], NO_PLUGINS),
469+
vocabulary: entryVocabulary([]),
470470
};
471471

472472
function installations(): readonly ExecutionInstallation[] {

‎packages/cli/tests/repl-sidekick-controls.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1486,7 +1486,7 @@ describe("Tier R3 — a reply reads the history, not the screen", () => {
14861486
includes: ["components", "."],
14871487
permissionMode: "deny-all",
14881488
plugins: NO_PLUGINS.plugins.map((plugin) => plugin.name),
1489-
vocabulary: entryVocabulary(["components", "."], NO_PLUGINS),
1489+
vocabulary: entryVocabulary(["components", "."]),
14901490
} as const;
14911491

14921492
/**
@@ -2256,7 +2256,7 @@ describe("Tier R3 — four bounded reads of one entry's saved evidence", () => {
22562256
includes: ["components", "."],
22572257
permissionMode: "deny-all",
22582258
plugins: NO_PLUGINS.plugins.map((plugin) => plugin.name),
2259-
vocabulary: entryVocabulary(["components", "."], NO_PLUGINS),
2259+
vocabulary: entryVocabulary(["components", "."]),
22602260
} as const;
22612261

22622262
/** The saved events, read with the reader the command reads them with. */

0 commit comments

Comments
 (0)