Skip to content

Commit 40be3e3

Browse files
committed
Require the current saved-message format for Sidekick records
Every saved Sidekick message carries an opaque ID and a UI or attachment origin. Both are required: a record missing either is unreadable rather than read as an earlier shape, and nothing projects a substitute origin for one. The chat item carries the ID and origin the record holds, so the live attachment's own saved message is found by that ID alone. There is one supported format for this data, so the stored records move to it in place: the two pinned chat fixtures gain those fields on their message records, and each receipt restates its own byte count and digest. The architecture and REPL specification say the fields are required. Formatting of the files this feature already touches is brought to oxfmt's output, which `deno task lint` checks.
1 parent c672a55 commit 40be3e3

17 files changed

Lines changed: 507 additions & 139 deletions

‎architecture.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8666,9 +8666,10 @@ it or release its reservation. Exact-handle Stop joins producer cleanup before
86668666
release, and an old handle cannot stop a successor. Entry work remains owned by
86678667
ReplSession.
86688668

8669-
Message records retain an optional opaque ID and UI/attachment origin beside the
8670-
legacy numeric `turn`. The reference is published only after the message append
8671-
is acknowledged. Legacy records are read without rewriting or inventing IDs.
8669+
Every message record carries an opaque ID and a UI/attachment origin beside the
8670+
conversation-scoped numeric `turn`, and a record missing either is unreadable
8671+
rather than assumed. The reference is published only after the message append
8672+
is acknowledged.
86728673
ACP-origin acknowledgement clears neither composer nor draft takeover. The live
86738674
root indexes established IDs for passive observation; that index supplies no
86748675
restart, resend or provider-acceptance authority. An earlier answer followed by
@@ -8842,7 +8843,7 @@ and categorization rather than clarify them, so both stay exactly as written.
88428843
| background automation | work designed to proceed without ongoing user or agent attention, with its persistence and recovery guarantees supplied by the workflow host |
88438844
| REPL | the foreground interactive environment for experimenting with and testing components; replay restores recorded execution state, while the user or agent handles differences between that state and the live environment |
88448845
| REPL history | the immutable ordered execution records the REPL reads from the durable journal and projects into `ReplModel`; the History surface presents this read model and is not itself a journal [Reference](#the-private-repl-composition-kernel). |
8845-
| legacy message ID | the number Sidekick retains to identify a saved person message within its conversation; fixed once saved, possibly noncontiguous, and independent of the turn numbers recorded by Core. The conversation and message ID together form its lookup key |
8846+
| message ID | the opaque identity Sidekick retains for a saved person message, written before its turn and never rewritten. The conversation and message ID together form its lookup key, and the conversation-scoped numeric `turn` beside it identifies no turn |
88468847
| turn | one request to an agent, together with the response or failure from that request |
88478848
| middleware | applied by the lexical structure, used by runtime execution [Reference](#two-layers). |
88488849
| workflow run | a workflow being carried out with its progress and outcome recorded durably; document executions perform its work, while ongoing effects remain scoped to the document execution in which they run [Reference](#workflow-runs). |

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3251,7 +3251,13 @@ function sidekickComposedRows(
32513251
}
32523252
for (const item of shownChat) {
32533253
if (item.kind === "person") {
3254-
items.push(text(`sidekick:${item.key}`, ` ${item.origin?.kind === "acp" ? "ACP (" + item.origin.attachment + ")" : "you"}: ${item.text}`, styleOf("source")));
3254+
items.push(
3255+
text(
3256+
`sidekick:${item.key}`,
3257+
` ${item.origin?.kind === "acp" ? "ACP (" + item.origin.attachment + ")" : "you"}: ${item.text}`,
3258+
styleOf("source"),
3259+
),
3260+
);
32553261
continue;
32563262
}
32573263
if (item.kind === "preview") {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2287,7 +2287,7 @@ export function sidekickChatRows(
22872287
conversation: item.conversation,
22882288
turn: item.turn,
22892289
kind: item.kind,
2290-
...(item.kind === "person" && item.origin.kind !== "legacy" ? { origin: item.origin } : {}),
2290+
...(item.kind === "person" ? { origin: item.origin } : {}),
22912291
text: item.text,
22922292
hasOutput: item.kind === "reply" ? item.hasOutput : false,
22932293
// The reply's own retained failure, carried through rather than

‎packages/cli/src/repl/sidekick/dispatch.ts‎

Lines changed: 117 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,28 @@
1-
import { createContext, createSignal, ensure, Err, Ok, scoped, spawn, useScope, withResolvers } from "effection";
1+
import {
2+
createContext,
3+
createSignal,
4+
ensure,
5+
Err,
6+
Ok,
7+
scoped,
8+
spawn,
9+
useScope,
10+
withResolvers,
11+
} from "effection";
212
import type { Operation, Result, Subscription, Task } from "effection";
313
import { API } from "@executablemd/runtime";
414
import type { Instruction } from "./gate.ts";
515
import type { MessageOrigin } from "./history.ts";
616
import { SidekickOwnerError } from "./owner.ts";
717
import type { SidekickOwner, SidekickTurn } from "./owner.ts";
818

9-
export const SidekickOrigin = createContext<MessageOrigin>("executablemd.repl.sidekick-origin", { kind: "ui" });
19+
export const SidekickOrigin = createContext<MessageOrigin>("executablemd.repl.sidekick-origin", {
20+
kind: "ui",
21+
});
1022

11-
export interface MessageReservation { readonly instruction?: Instruction }
23+
export interface MessageReservation {
24+
readonly instruction?: Instruction;
25+
}
1226
export interface ConfigurationReservation {
1327
readonly kind: "inspect" | "save" | "replace";
1428
readonly conversation: string | undefined;
@@ -22,33 +36,52 @@ export function createSidekickAdmission() {
2236
if (kind !== "save" && kind !== "replace" && message !== undefined) {
2337
return "the Sidekick is already working on a message.";
2438
}
25-
if (configuration === undefined) { return undefined; }
39+
if (configuration === undefined) {
40+
return undefined;
41+
}
2642
if (kind === "save" && configuration.kind === "save") {
2743
return "the Sidekick is already saving a setting.";
2844
}
2945
return "the Sidekick is already doing something you asked for.";
3046
}
3147
return {
32-
get message() { return message; },
33-
get configuration() { return configuration; },
48+
get message() {
49+
return message;
50+
},
51+
get configuration() {
52+
return configuration;
53+
},
3454
occupied,
3555
messageReservation(instruction?: Instruction): Result<MessageReservation> {
3656
const reason = occupied("message");
37-
if (reason !== undefined) { return Err(new Error(reason)); }
57+
if (reason !== undefined) {
58+
return Err(new Error(reason));
59+
}
3860
const held = Object.freeze({ ...(instruction === undefined ? {} : { instruction }) });
3961
message = held;
4062
return Ok(held);
4163
},
42-
releaseMessage(held: MessageReservation): void { if (message === held) { message = undefined; } },
43-
configure(kind: ConfigurationReservation["kind"], conversation: string | undefined): Result<ConfigurationReservation> {
64+
releaseMessage(held: MessageReservation): void {
65+
if (message === held) {
66+
message = undefined;
67+
}
68+
},
69+
configure(
70+
kind: ConfigurationReservation["kind"],
71+
conversation: string | undefined,
72+
): Result<ConfigurationReservation> {
4473
const reason = occupied(kind);
45-
if (reason !== undefined) { return Err(new Error(reason)); }
74+
if (reason !== undefined) {
75+
return Err(new Error(reason));
76+
}
4677
const held: ConfigurationReservation = { kind, conversation, task: undefined };
4778
configuration = held;
4879
return Ok(held);
4980
},
5081
releaseConfiguration(held: ConfigurationReservation): void {
51-
if (configuration === held) { configuration = undefined; }
82+
if (configuration === held) {
83+
configuration = undefined;
84+
}
5285
},
5386
};
5487
}
@@ -70,7 +103,10 @@ export interface SidekickDispatchSnapshot {
70103
export interface SidekickExchange {
71104
readonly snapshot: SidekickDispatchSnapshot;
72105
readonly completion: Operation<Result<SidekickTurn>>;
73-
observe(): Operation<{ readonly snapshot: SidekickDispatchSnapshot; readonly changes: Subscription<SidekickDispatchSnapshot, never> }>;
106+
observe(): Operation<{
107+
readonly snapshot: SidekickDispatchSnapshot;
108+
readonly changes: Subscription<SidekickDispatchSnapshot, never>;
109+
}>;
74110
cancel(): Operation<void>;
75111
}
76112
export interface SidekickDispatch {
@@ -91,28 +127,44 @@ export function* useSidekickDispatch(options: {
91127
let current: SidekickExchange | undefined;
92128
const messages = new Map<string, SidekickExchange>();
93129
let live = true;
94-
yield* ensure(function* () { live = false; messages.clear(); });
130+
yield* ensure(function* () {
131+
live = false;
132+
messages.clear();
133+
});
95134
return {
96-
get current() { return current; },
135+
get current() {
136+
return current;
137+
},
97138
follow(reference): Result<SidekickExchange> {
98-
if (!live) { return Err(new Error("The Sidekick dispatch owner has ended.")); }
139+
if (!live) {
140+
return Err(new Error("The Sidekick dispatch owner has ended."));
141+
}
99142
const exchange = messages.get(reference.id);
100143
const saved = exchange?.snapshot.message;
101-
return exchange !== undefined && saved?.execution === reference.execution && saved.conversation === reference.conversation
102-
? Ok(exchange) : Err(new Error("This live owner has no established association for that message."));
144+
return exchange !== undefined &&
145+
saved?.execution === reference.execution &&
146+
saved.conversation === reference.conversation
147+
? Ok(exchange)
148+
: Err(new Error("This live owner has no established association for that message."));
103149
},
104150
*send(text, instruction): Operation<Result<SidekickExchange>> {
105-
if (!live) { return Err(new Error("The Sidekick dispatch owner has ended.")); }
151+
if (!live) {
152+
return Err(new Error("The Sidekick dispatch owner has ended."));
153+
}
106154
const origin = Object.freeze({ ...(yield* SidekickOrigin.expect()) });
107-
if (text.trim().length === 0 || origin.kind === "acp" && origin.attachment.length === 0) {
155+
if (text.trim().length === 0 || (origin.kind === "acp" && origin.attachment.length === 0)) {
108156
return Err(new Error("A Sidekick dispatch requires text and an identified origin."));
109157
}
110158
const selected = owner.reading;
111-
if (!selected.ok) { return selected; }
159+
if (!selected.ok) {
160+
return selected;
161+
}
112162
const conversation = selected.value.active;
113163
const agent = owner.agent;
114164
const reserved = admission.messageReservation(instruction);
115-
if (!reserved.ok) { return reserved; }
165+
if (!reserved.ok) {
166+
return reserved;
167+
}
116168
const held = reserved.value;
117169
const answer = withResolvers<Result<SidekickTurn>>();
118170
const changed = createSignal<SidekickDispatchSnapshot, never>();
@@ -122,18 +174,35 @@ export function* useSidekickDispatch(options: {
122174
let stopped = false;
123175
let producer: Task<void>;
124176
function snapshot(): SidekickDispatchSnapshot {
125-
return completed ?? Object.freeze({ origin, message, reading: owner.reading, live: owner.live, preview: owner.previewing, terminal });
177+
return (
178+
completed ??
179+
Object.freeze({
180+
origin,
181+
message,
182+
reading: owner.reading,
183+
live: owner.live,
184+
preview: owner.previewing,
185+
terminal,
186+
})
187+
);
188+
}
189+
function publish(): void {
190+
changed.send(snapshot());
191+
options.changed();
126192
}
127-
function publish(): void { changed.send(snapshot()); options.changed(); }
128193
const exchange: SidekickExchange = {
129-
get snapshot() { return snapshot(); },
194+
get snapshot() {
195+
return snapshot();
196+
},
130197
completion: answer.operation,
131198
*observe() {
132199
const changes = yield* changed;
133200
return { snapshot: snapshot(), changes };
134201
},
135202
*cancel(): Operation<void> {
136-
if (terminal !== undefined) { return; }
203+
if (terminal !== undefined) {
204+
return;
205+
}
137206
if (!stopped && current === exchange) {
138207
stopped = true;
139208
yield* owner.stop();
@@ -143,17 +212,32 @@ export function* useSidekickDispatch(options: {
143212
};
144213
current = exchange;
145214
producer = root.run(function* (): Operation<void> {
146-
let result: Result<SidekickTurn> = Err(new SidekickOwnerError("The Sidekick exchange was cancelled."));
215+
let result: Result<SidekickTurn> = Err(
216+
new SidekickOwnerError("The Sidekick exchange was cancelled."),
217+
);
147218
try {
148-
yield* API.Env.around({ *cwd() { return options.workspace; } });
219+
yield* API.Env.around({
220+
*cwd() {
221+
return options.workspace;
222+
},
223+
});
149224
result = yield* scoped(function* (): Operation<Result<SidekickTurn>> {
150225
const changes = yield* owner.changes;
151226
yield* spawn(function* () {
152-
while (true) { yield* changes.next(); publish(); }
227+
while (true) {
228+
yield* changes.next();
229+
publish();
230+
}
153231
});
154-
if (stopped) { return Err(new SidekickOwnerError("The Sidekick exchange was cancelled before sending.")); }
232+
if (stopped) {
233+
return Err(
234+
new SidekickOwnerError("The Sidekick exchange was cancelled before sending."),
235+
);
236+
}
155237
const now = owner.reading;
156-
if (!now.ok) { return now; }
238+
if (!now.ok) {
239+
return now;
240+
}
157241
if (now.value.active !== conversation || owner.agent !== agent) {
158242
return Err(new Error("The selected Sidekick conversation changed before dispatch."));
159243
}
@@ -176,7 +260,9 @@ export function* useSidekickDispatch(options: {
176260
terminal = result;
177261
completed = snapshot();
178262
admission.releaseMessage(held);
179-
if (current === exchange) { current = undefined; }
263+
if (current === exchange) {
264+
current = undefined;
265+
}
180266
publish();
181267
answer.resolve(result);
182268
}

‎packages/cli/src/repl/sidekick/history.ts‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -214,16 +214,20 @@ export interface ReferenceRecord {
214214
readonly versions: Readonly<Record<string, string>>;
215215
}
216216

217-
export type MessageOrigin = { readonly kind: "ui" } | { readonly kind: "acp"; readonly attachment: string };
217+
export type MessageOrigin =
218+
| { readonly kind: "ui" }
219+
| { readonly kind: "acp"; readonly attachment: string };
218220

219221
/** Exactly what a person sent, and which chat revision it cleared. */
220222
export interface MessageRecord {
221-
readonly id?: string;
222-
readonly origin?: MessageOrigin;
223223
readonly kind: "message";
224+
/** This host's opaque identity for the saved message, written before its turn. */
225+
readonly id: string;
226+
/** Which surface sent it: this host's own UI, or a named live attachment. */
227+
readonly origin: MessageOrigin;
224228
readonly conversation: string;
225229
/**
226-
* This message's ID — it does not identify a turn.
230+
* This message's conversation-scoped number — it does not identify a turn.
227231
*
228232
* This host's own numbering, written before the turn and never rewritten
229233
* afterwards, scoped to the conversation and not promised to be contiguous.
@@ -605,20 +609,22 @@ function reference(value: Record<string, unknown>): ReferenceRecord | undefined
605609
}
606610

607611
function message(value: Record<string, unknown>): MessageRecord | undefined {
608-
if (!exactly(value, ["kind", "conversation", "turn", "revision", "text", ...(value.id === undefined ? [] : ["id"]), ...(value.origin === undefined ? [] : ["origin"])])) {
612+
if (!exactly(value, ["kind", "id", "origin", "conversation", "turn", "revision", "text"])) {
609613
return undefined;
610614
}
615+
const id = str(value.id);
616+
const origin = messageOrigin(value.origin);
611617
const held = str(value.conversation);
612618
const turn = whole(value.turn);
613619
const revision = whole(value.revision);
614620
const text = str(value.text);
621+
if (id === undefined || id.length === 0 || origin === undefined) {
622+
return undefined;
623+
}
615624
if (held === undefined || turn === undefined || revision === undefined || text === undefined) {
616625
return undefined;
617626
}
618-
const id = value.id === undefined ? undefined : str(value.id);
619-
const origin = value.origin === undefined ? undefined : messageOrigin(value.origin);
620-
if (value.id !== undefined && (id === undefined || id.length === 0) || value.origin !== undefined && origin === undefined) { return undefined; }
621-
return { kind: "message", conversation: held, turn, revision, text, ...(id === undefined ? {} : { id }), ...(origin === undefined ? {} : { origin }) };
627+
return { kind: "message", id, origin, conversation: held, turn, revision, text };
622628
}
623629

624630
function eventRecord(value: Record<string, unknown>): EventRecord | undefined {
@@ -1469,10 +1475,22 @@ export function* upgradeExecution(
14691475
}
14701476

14711477
function messageOrigin(value: unknown): MessageOrigin | undefined {
1472-
if (typeof value !== "object" || value === null || Array.isArray(value)) { return undefined; }
1473-
if (!("kind" in value)) { return undefined; }
1474-
if (value.kind === "ui" && Object.keys(value).length === 1) { return { kind: "ui" }; }
1475-
if (value.kind === "acp" && Object.keys(value).length === 2 && "attachment" in value && typeof value.attachment === "string" && value.attachment.length > 0) {
1478+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
1479+
return undefined;
1480+
}
1481+
if (!("kind" in value)) {
1482+
return undefined;
1483+
}
1484+
if (value.kind === "ui" && Object.keys(value).length === 1) {
1485+
return { kind: "ui" };
1486+
}
1487+
if (
1488+
value.kind === "acp" &&
1489+
Object.keys(value).length === 2 &&
1490+
"attachment" in value &&
1491+
typeof value.attachment === "string" &&
1492+
value.attachment.length > 0
1493+
) {
14761494
return { kind: "acp", attachment: value.attachment };
14771495
}
14781496
return undefined;

‎packages/cli/src/repl/sidekick/model.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -159,8 +159,10 @@ function lastVerified(
159159
export type SidekickChatItem =
160160
| {
161161
readonly kind: "person";
162-
readonly id?: string;
163-
readonly origin: import("./history.ts").MessageOrigin | { readonly kind: "legacy" };
162+
/** The saved message's own opaque ID, as the record holds it. */
163+
readonly id: string;
164+
/** Which surface sent it: this host's own UI, or a named live attachment. */
165+
readonly origin: import("./history.ts").MessageOrigin;
164166
readonly conversation: string;
165167
/**
166168
* The retained message ID, independent of saved turn numbering.
@@ -1026,8 +1028,8 @@ export function projectSidekick(records: readonly SidekickRecord[]): Result<Side
10261028
chatAt.push(index);
10271029
chat.push({
10281030
kind: "person",
1029-
...(record.id === undefined ? {} : { id: record.id }),
1030-
origin: record.origin ?? { kind: "legacy" },
1031+
id: record.id,
1032+
origin: record.origin,
10311033
conversation: record.conversation,
10321034
// Its own ID, and the saved turn its own request became — which
10331035
// is unknown when that request's records hold no saved turn.

0 commit comments

Comments
 (0)