Skip to content

Commit f2c73c6

Browse files
committed
✨ Slice C of #827: route, draft and a windowed Entries catalog
A draft is now execution-wide state for the next entry. It coexists with a selected entry, a nested scope, either surface, drawers, a Sessions filter and a frozen history position, and it stays editable while an entry runs and while a prefix is being inspected — an admitted entry is immutable, so there is never an entry those keystrokes could be editing. Run is available only at the live head. The reducer refuses it at a frozen position, because the only inheritance boundary there that is not a fork is the head; whether this is a moment to submit at all stays the session's answer. No refusal touches the draft: it clears only once it has become an entry, and the entry it became carries the key the session really assigned. The Entries surface is a catalog of every retained entry in admission order, each row carrying its own outcome — unfinished, ok, err or cancelled — and keyed by its stable entry key rather than by its place in the window. The catalog is windowed rather than mounted whole and clipped: rows outside the window are not described, mounted, drawn or targetable, every row becomes reachable by scrolling, and a scroll is applied from the clamped position the frame is drawing so the first press after a resize moves the screen. A location naming an entry its prefix never admitted refuses whole. When the history action selects a position earlier than the selected entry's admission, the loop clears that now-invalid entry and scope suffix and guesses no replacement, keeping the draft, the surface, the filter, the History drawer and the marker.
1 parent e732512 commit f2c73c6

10 files changed

Lines changed: 1371 additions & 102 deletions

File tree

‎packages/cli/src/repl/application.ts‎

Lines changed: 231 additions & 48 deletions
Large diffs are not rendered by default.

‎packages/cli/src/repl/components/actions.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ export type ReplAction =
2626
| { readonly kind: "type"; readonly text: string; readonly field?: string }
2727
/** Remove the last Unicode scalar value from one named field, or the draft. */
2828
| { readonly kind: "erase"; readonly field?: string }
29-
/** Admit the draft as this execution's one entry. */
29+
/** Admit the draft as this execution's next entry. */
3030
| { readonly kind: "submit" }
3131
| { readonly kind: "select-surface"; readonly surface: ReplSurface }
3232
/** Select a structural scope by its key path, outermost first. */
@@ -63,6 +63,14 @@ export type ReplAction =
6363
* whichever the reducer guessed.
6464
*/
6565
| { readonly kind: "scroll-sessions"; readonly delta: number }
66+
/**
67+
* Move the Entries catalog by whole rows.
68+
*
69+
* Its own member for the same reason `scroll-sessions` is: a wide frame has
70+
* both readings open at once, and one action meaning either would move
71+
* whichever the reducer guessed rather than the list the control belongs to.
72+
*/
73+
| { readonly kind: "scroll-entries"; readonly delta: number }
6674
/**
6775
* Show only the conversation this provider session key names.
6876
*

‎packages/cli/src/repl/components/rows.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,10 @@ function activation(input: ReplViewData): ReplAction | undefined {
164164
const delta = named["delta"];
165165
return typeof delta === "number" ? { kind: "scroll-sessions", delta } : undefined;
166166
}
167+
if (select === "scroll-entries") {
168+
const delta = named["delta"];
169+
return typeof delta === "number" ? { kind: "scroll-entries", delta } : undefined;
170+
}
167171
if (select === "session") {
168172
const session = named["session"];
169173
return typeof session === "string" && session.length > 0

‎packages/cli/src/repl/program.ts‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ import {
5454
replSurface,
5555
stateFor,
5656
viewFor,
57+
withoutAbsentEntry,
5758
} from "./application.ts";
5859
import type { Json, NormalizedIssue } from "@executablemd/core";
5960
import type {
@@ -553,9 +554,24 @@ function* drive(
553554
let view: ReplView;
554555
const attempted = yield* reproject(state, model, execution);
555556
const drawnAt = yield* screen.size();
556-
const built = viewFor(attempted.state, attempted.model, liveOf(current), drawnAt, focused);
557+
let adopting = attempted.state;
558+
let built = viewFor(adopting, attempted.model, liveOf(current), drawnAt, focused);
559+
if (!built.ok) {
560+
// A position earlier than the selected entry's admission has no such
561+
// entry in it. The position is what was asked for, so the invalid entry
562+
// and scope suffix goes and nothing guesses a replacement — the draft,
563+
// the surface, the conversation filter and the marker all stand.
564+
const cleared = withoutAbsentEntry(adopting, attempted.model);
565+
if (cleared !== undefined) {
566+
const without = viewFor(cleared, attempted.model, liveOf(current), drawnAt, focused);
567+
if (without.ok) {
568+
adopting = cleared;
569+
built = without;
570+
}
571+
}
572+
}
557573
if (built.ok) {
558-
state = attempted.state;
574+
state = adopting;
559575
model = attempted.model;
560576
view = built.value;
561577
} else {

‎packages/cli/src/repl/route.ts‎

Lines changed: 28 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@
2121
* split is what keeps a typo in a location from being answered with a guess
2222
* about the history.
2323
*
24+
* `draft` is the next entry's text, and it is execution-wide. An admitted entry
25+
* is immutable, so what is being typed is always the one *after* whatever a
26+
* reader is looking at — which is why it accompanies a selected entry, a nested
27+
* scope, a drawer stack, a conversation filter and a frozen history position
28+
* rather than being a state the execution can only be in before its first entry.
29+
*
2430
* `session` selects one Agent conversation to filter the Sessions list by. It
2531
* is the provider's own session key, which is the one name for a conversation
2632
* that a second process reading the same Journal would arrive at too. The live
@@ -32,7 +38,6 @@
3238
import { Err, Ok } from "effection";
3339
import type { Result } from "effection";
3440

35-
import { ENTRY_SCOPE } from "./model.ts";
3641
import type {
3742
ReplAgentSession,
3843
ReplBinding,
@@ -74,7 +79,15 @@ export interface ReplRoute {
7479
readonly at: string | undefined;
7580
/** Whether that frozen position is read-only. Requires `at`. */
7681
readonly inspect: boolean;
77-
/** Text typed but not yet admitted. Exists only before an entry does. */
82+
/**
83+
* Text typed for the next entry and not yet admitted.
84+
*
85+
* Execution-wide rather than a state one entry can be in: an entry is
86+
* immutable once admitted, so what is being typed is always the *next* one and
87+
* is a different thing from whichever entry a reader happens to be looking at.
88+
* It therefore accompanies a selected entry, a nested scope, either surface, a
89+
* drawer stack, a conversation filter and a frozen history position.
90+
*/
7891
readonly draft: string | undefined;
7992
/**
8093
* The one conversation the Sessions list is filtered to, by provider session
@@ -122,6 +135,7 @@ export type ReplDrawer =
122135
export interface ReplSelection {
123136
readonly route: ReplRoute;
124137
readonly surface: ReplSurface;
138+
/** The root scope of the entry this location selected, when it selected one. */
125139
readonly entry: ReplScope | undefined;
126140
/** The entry and each selected nested scope, outermost first. */
127141
readonly ancestry: readonly ReplScope[];
@@ -213,12 +227,6 @@ export function decodeLocation(location: string): Result<ReplRoute> {
213227
if (query.inspect && query.at === undefined) {
214228
return refuse("inspecting a history position needs the position");
215229
}
216-
if (query.draft !== undefined && (query.at !== undefined || scopes.length > 0)) {
217-
return refuse(
218-
"a draft is text no entry has admitted yet, so it cannot accompany an admitted " +
219-
"structure or a history position",
220-
);
221-
}
222230

223231
return Ok({
224232
execution,
@@ -273,9 +281,6 @@ export function encodeLocation(route: ReplRoute): string {
273281
if (route.inspect && route.at === undefined) {
274282
throw new TypeError("inspecting a history position needs the position");
275283
}
276-
if (route.draft !== undefined && (route.at !== undefined || route.scopes.length > 0)) {
277-
throw new TypeError("a draft cannot accompany an admitted structure or a history position");
278-
}
279284
if (route.session !== undefined && route.session.length === 0) {
280285
throw new TypeError("a session filter names one conversation");
281286
}
@@ -356,34 +361,27 @@ export function resolveLocation(
356361
drawers: opened.value,
357362
});
358363
}
359-
// The first entry's scope, which is the only entry this slice's route grammar
360-
// selects. Entry selection across the collection is the route work this
361-
// Story's later slice owns; what changed here is where the one entry is read
362-
// from, not which entries a location may name.
363-
const admitted = model.entries[0]?.scope;
364-
if (route.draft !== undefined && admitted !== undefined) {
365-
return Err(
366-
new ReplRouteError(
367-
"this route carries a draft, and this execution has already admitted its entry. An " +
368-
"admitted entry is immutable.",
369-
),
370-
);
371-
}
372-
364+
// The first structural member is the entry, by its own admission-order key,
365+
// and every nested scope is resolved beneath that one entry. An entry this
366+
// prefix did not admit refuses here rather than falling back to another: a
367+
// location naming something the history does not hold is a location to
368+
// answer, not to guess at.
373369
const ancestry: ReplScope[] = [];
370+
let entry: ReplScope | undefined;
374371
let scope: ReplScope | undefined;
375372
for (const key of route.scopes) {
376373
if (scope === undefined) {
377-
if (key !== ENTRY_SCOPE) {
378-
return Err(new ReplRouteError(`this execution has no ${key}.`));
379-
}
374+
const admitted = model.entries.find((candidate) => candidate.key === key)?.scope;
380375
if (admitted === undefined) {
381376
return Err(
382377
new ReplRouteError(
383-
"this route selects an entry, and this execution has not admitted one yet.",
378+
model.entries.length === 0
379+
? "this route selects an entry, and this execution has not admitted one yet."
380+
: `this execution has no ${key}.`,
384381
),
385382
);
386383
}
384+
entry = admitted;
387385
scope = admitted;
388386
ancestry.push(scope);
389387
continue;
@@ -404,7 +402,7 @@ export function resolveLocation(
404402
return Ok({
405403
route,
406404
surface: "repl",
407-
entry: admitted,
405+
entry,
408406
ancestry: Object.freeze(ancestry),
409407
scope,
410408
session: filtered.value,

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3119,3 +3119,121 @@ describe("U9 — two entries whose Prompts share one durable name", () => {
31193119
expect(session.model.sessions[0]?.turns).toHaveLength(2);
31203120
});
31213121
});
3122+
3123+
/** The catalog rows one view describes, in the order it describes them. */
3124+
function catalogRows(view: ReplView): Array<{ key: string; label: string }> {
3125+
return rowsOf(describeApplication(view)).filter((one) => one.key.startsWith("entry:"));
3126+
}
3127+
3128+
/** The label of the catalog row for one entry key. */
3129+
function catalogLabel(view: ReplView, entry: string): string {
3130+
const found = catalogRows(view).find((one) => one.key === `entry:${entry}`);
3131+
if (found === undefined) {
3132+
throw new Error(`this catalog has no row for ${entry}`);
3133+
}
3134+
return found.label;
3135+
}
3136+
3137+
describe("EU1 — selecting an entry moves the transcript locus and nothing else", () => {
3138+
beforeAll(() => useTempFileCompiler());
3139+
3140+
/** Two entries, each with one recorded turn in one provider conversation. */
3141+
function* twoRecordedEntries(): Operation<{ session: ReplSession; stub: Stub }> {
3142+
const stub = createStub({ two: { unrecorded: true } });
3143+
yield* useStub(stub);
3144+
const holder = execution();
3145+
const session = granted(
3146+
yield* submitReplEntry({
3147+
execution: holder,
3148+
installations: installations(),
3149+
permissionMode: "deny-all",
3150+
source: onePromptAt("one"),
3151+
}),
3152+
);
3153+
yield* until(session, "the first entry's turn being recorded", () => recorded(session) === 1);
3154+
yield* session.join();
3155+
expect((yield* session.submit(onePromptAt("two"))).ok).toBe(true);
3156+
yield* until(session, "the second entry's turn reaching its terminal event", () =>
3157+
session.agent.turns.some((turn) => turn.state === "terminal"),
3158+
);
3159+
return { session, stub };
3160+
}
3161+
3162+
it("EU1: selecting an entry changes the locus, and leaves Sessions global", function* () {
3163+
const { session, stub } = yield* twoRecordedEntries();
3164+
stub.record("root");
3165+
yield* until(session, "the second entry's turn being recorded", () => recorded(session) === 2);
3166+
yield* session.join();
3167+
3168+
// Standing with a draft, a conversation filter, and the first entry
3169+
// selected: everything selecting another entry must leave alone.
3170+
let standing = withDraft(initialState("agents"), "the next one");
3171+
standing = acted(standing, { kind: "select-scope", scopes: ["entry-1"] }, session);
3172+
standing = acted(standing, { kind: "select-session", session: "stub:planner" }, session);
3173+
const before = reading(standing, session);
3174+
expect(before.selection.entry?.key).toBe("entry-1");
3175+
const turnsBefore = turnRows(before);
3176+
const conversationsBefore = conversationRows(before);
3177+
const appendsBefore = session.model.turns.length;
3178+
3179+
const selected = acted(standing, { kind: "select-scope", scopes: ["entry-2"] }, session);
3180+
const after = reading(selected, session);
3181+
3182+
// The locus moved, and that is the whole of what moved.
3183+
expect(after.selection.entry?.key).toBe("entry-2");
3184+
expect(after.selection.scope?.key).toBe("entry-2");
3185+
expect(before.selection.entry?.key).toBe("entry-1");
3186+
3187+
// The draft, the marker, the surface and the conversation filter all stand.
3188+
expect(selected.draft).toBe("the next one");
3189+
expect(selected.route.draft).toBe("the next one");
3190+
expect(selected.route.at).toBe(undefined);
3191+
expect(selected.route.surface).toBe("repl");
3192+
expect(selected.route.session).toBe("stub:planner");
3193+
3194+
// Sessions is one execution-wide chronology and selecting an entry never
3195+
// narrows it: both entries' turns are still in it, in the same order, under
3196+
// the one conversation the provider named.
3197+
expect(turnRows(after)).toEqual(turnsBefore);
3198+
expect(conversationRows(after)).toEqual(conversationsBefore);
3199+
expect(conversationRows(after)).toEqual(["sessions:conversation:stub:planner"]);
3200+
expect(session.model.sessions.map((one) => one.sessionKey)).toEqual(["stub:planner"]);
3201+
expect(session.model.sessions[0]?.turns).toHaveLength(2);
3202+
expect(labelOf(after, "one")).toBe(labelOf(before, "one"));
3203+
expect(labelOf(after, "two")).toBe(labelOf(before, "two"));
3204+
3205+
// And no live execution, Agent work or history was touched by a selection.
3206+
expect(session.model.turns).toHaveLength(appendsBefore);
3207+
expect(session.live).toBe(false);
3208+
expect(session.agent.requests).toEqual([]);
3209+
});
3210+
3211+
it("EU1: entry keys and mounted nodes survive publication and an outcome change", function* () {
3212+
const { session, stub } = yield* twoRecordedEntries();
3213+
const tree = yield* useReplTree<ReplAction>();
3214+
3215+
// The second entry's root cannot close until its Prompt publishes, so the
3216+
// catalog honestly says it has not settled.
3217+
const before = reading(initialState("agents"), session);
3218+
expect(catalogRows(before).map((one) => one.key)).toEqual(["entry:entry-1", "entry:entry-2"]);
3219+
expect(catalogLabel(before, "entry-1")).toContain("ok");
3220+
expect(catalogLabel(before, "entry-2")).toContain("unfinished");
3221+
yield* applied(tree, before);
3222+
const nodes = ["entry-1", "entry-2"].map((key) => nodeOf(tree, `entry:${key}`));
3223+
expect(nodes.every((node) => node !== undefined)).toBe(true);
3224+
3225+
stub.record("root");
3226+
yield* until(session, "the second entry's turn being recorded", () => recorded(session) === 2);
3227+
yield* session.join();
3228+
3229+
// The outcome changed under it, which is the point: a row whose identity
3230+
// came from its place in the window would have moved, and a row keyed by
3231+
// its entry does not.
3232+
const after = reading(initialState("agents"), session);
3233+
expect(catalogRows(after).map((one) => one.key)).toEqual(["entry:entry-1", "entry:entry-2"]);
3234+
expect(catalogLabel(after, "entry-2")).toContain("ok");
3235+
expect(catalogLabel(after, "entry-2")).not.toContain("unfinished");
3236+
yield* applied(tree, after);
3237+
expect(["entry-1", "entry-2"].map((key) => nodeOf(tree, `entry:${key}`))).toEqual(nodes);
3238+
});
3239+
});

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1660,6 +1660,14 @@ function maybeLocation(terminal: Terminal): string | undefined {
16601660
break;
16611661
}
16621662
parts.push(part.trimEnd());
1663+
// Every row of a location is padded to the full surface width, so a row
1664+
// with space left on its end is the last of them. Without this the row
1665+
// drawn underneath joins on, and the round-trip below cannot always tell:
1666+
// a location ending in `/entry-2` followed by a transcript row beginning
1667+
// `entry ...` re-encodes as `/entry-2entry` exactly as written.
1668+
if (part.trimEnd().length < part.length) {
1669+
break;
1670+
}
16631671
}
16641672

16651673
const joined = parts.join("");
@@ -1852,7 +1860,15 @@ function* typed(terminal: Terminal, text: string): Operation<void> {
18521860
terminal.feed("\r");
18531861
yield* sleep(200);
18541862
yield* settled(20);
1855-
yield* showing(terminal, "(one entry admitted)");
1863+
// The draft leaving the location is what says the entry exists. It used to be
1864+
// the footer notice that replaced the draft once one did; a draft is now
1865+
// execution-wide and survives admission as the *next* entry's text (#827
1866+
// Slice C), so what clears is the one this helper just typed — and it clears
1867+
// only when it has become an entry.
1868+
yield* until(
1869+
() => !(maybeLocation(terminal) ?? "draft=").includes("draft="),
1870+
"the draft never became an entry",
1871+
);
18561872
}
18571873

18581874
/** Type a value into the field this label names. */

0 commit comments

Comments
 (0)