@muse-code/sdk 1.4.14 → 1.4.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,8 +3,10 @@
3
3
  * tasks.md T030).
4
4
  *
5
5
  * A handle owns two things: the SS3.1.4 turn-wait, and the async iterators
6
- * that ride the fold for this turn. It authors no wire traffic and holds no
7
- * durable state — `Session` feeds it folded events and it fans them out.
6
+ * that ride the fold for this turn. It holds no durable state — `Session`
7
+ * feeds it folded events and it fans them out. Its control verbs
8
+ * (`cancel`/`interrupt`/`steer`/`unqueue`, FR-79106-1) author wire traffic
9
+ * only through the `TurnControls` its `Session` hands it.
8
10
  *
9
11
  * INV-006 governs the wait: the SDK never locally times out, fails, or
10
12
  * completes a turn. Every settlement below traces to a server-authored fact,
@@ -13,7 +15,9 @@
13
15
  * client MUST ("stop waiting for a terminal") and which stays an annotation
14
16
  * rather than a synthesized event.
15
17
  */
16
- import type { Item, ItemDeltaParams, TurnCompletedParams, TurnUnqueuedParams } from "../msp.js";
18
+ import type { Item, ItemDeltaParams, TurnCancelResult, TurnCompletedParams, TurnInterruptParams, TurnInterruptResult, TurnSteerResult, TurnUnqueueResult, TurnUnqueuedParams } from "../msp.js";
19
+ import type { PendingRetirement } from "../pending/pending-command-set.js";
20
+ import type { SteerTurnOptions } from "./turn-submit.js";
17
21
  import type { DeepReadonly } from "../fold/session-fold.js";
18
22
  /**
19
23
  * What the iterators yield: the fold's stored item, sealed.
@@ -84,6 +88,34 @@ export type TurnOutcome = {
84
88
  export declare function isLaunchFailure(outcome: TurnOutcome): boolean;
85
89
  /** The turn's replayable backlog, supplied by `Session` from the fold. */
86
90
  export type ItemReplay = () => readonly FoldedItem[];
91
+ /** What `interrupt` forwards: the SS3.4 retract pairing. */
92
+ export type InterruptTurnOptions = Readonly<Pick<TurnInterruptParams, "retract">>;
93
+ /**
94
+ * What `unqueue` resolves to: the wire ack, and the SS4.13 retirement the
95
+ * accepted reclaim produced — the queued submit's input handed back to the
96
+ * composer. On a session `MuseClient` opened, `retirement` is set for this
97
+ * session's own accepted reclaim whatever order the ack and `turn/unqueued`
98
+ * arrive in. It is undefined when this session holds no queued entry for the
99
+ * turn (another client's submit, say). On a `Session` you feed through
100
+ * `apply` yourself, it is also undefined when `turn/unqueued` folded first:
101
+ * that `apply` returned the retirement, so restore the composer from
102
+ * whichever of the two returned it. Either way it is handed out once.
103
+ */
104
+ export interface TurnUnqueueOutcome<I> {
105
+ readonly ack: TurnUnqueueResult;
106
+ readonly retirement: PendingRetirement<I> | undefined;
107
+ }
108
+ /**
109
+ * The wire half of a handle's control verbs, supplied by its `Session`, which
110
+ * owns the connection, the discard latch and the SS4.13 pending set.
111
+ */
112
+ export interface TurnControls<I> {
113
+ cancel(turnId: string): Promise<TurnCancelResult>;
114
+ interrupt(turnId: string, options: InterruptTurnOptions): Promise<TurnInterruptResult>;
115
+ steer(turnId: string, options: SteerTurnOptions<I>): Promise<TurnSteerResult>;
116
+ /** `commandId` resends one reclaim under its first id; omitted, the connection mints one. */
117
+ unqueue(turnId: string, commandId?: string): Promise<TurnUnqueueOutcome<I>>;
118
+ }
87
119
  /**
88
120
  * A turn, as a CONSUMER sees it — the SS7.1 turn surface and nothing else.
89
121
  *
@@ -94,18 +126,41 @@ export type ItemReplay = () => readonly FoldedItem[];
94
126
  * is exactly what INV-006 forbids. They stay reachable only through
95
127
  * `Session.apply`, i.e. only from a server-authored event.
96
128
  */
97
- export interface Turn {
129
+ export interface Turn<I = unknown> {
98
130
  readonly turnId: string;
99
131
  /** Did THIS session observe a `turn/started`? Not a launch-failure marker. */
100
132
  readonly observedStart: boolean;
101
133
  readonly completed: Promise<TurnOutcome>;
102
134
  items(): AsyncIterableIterator<FoldedItem>;
103
135
  deltas(): AsyncIterableIterator<ItemDeltaParams>;
136
+ /**
137
+ * Cancel this turn on the normal command lane (`turn/cancel`, tdd SS3.5).
138
+ * Admission only: the turn is over when its `turn/completed` folds.
139
+ */
140
+ cancel(): Promise<TurnCancelResult>;
141
+ /**
142
+ * Stop this turn on the priority lane (`turn/interrupt`, tdd SS3.4), the
143
+ * user's stop gesture; `retract: true` also asks to retract the prompt.
144
+ * Admission only, like `cancel`.
145
+ */
146
+ interrupt(options?: InterruptTurnOptions): Promise<TurnInterruptResult>;
147
+ /**
148
+ * Add input to this turn while it runs (`turn/steer`, tdd SS3.3). The steer
149
+ * is a pending command (SS4.13) until its `userMessage` folds.
150
+ */
151
+ steer(options: SteerTurnOptions<I>): Promise<TurnSteerResult>;
152
+ /**
153
+ * Take this queued turn back before it launches (`turn/unqueue`, tdd SS3.6).
154
+ * An accepted ack means the turn never launches, so this session's queued
155
+ * entry retires at once (SS4.13 Reclaimed) and comes back as `retirement`;
156
+ * the turn itself settles `unqueued` when the server's `turn/unqueued` folds.
157
+ */
158
+ unqueue(): Promise<TurnUnqueueOutcome<I>>;
104
159
  }
105
- export declare class TurnHandle implements Turn {
160
+ export declare class TurnHandle<I = unknown> implements Turn<I> {
106
161
  #private;
107
162
  readonly turnId: string;
108
- constructor(turnId: string, replayItems: ItemReplay);
163
+ constructor(turnId: string, replayItems: ItemReplay, controls: TurnControls<I>);
109
164
  /** Settles on `turn/completed`, `turn/unqueued`, or the ephemeral discard. */
110
165
  get completed(): Promise<TurnOutcome>;
111
166
  /**
@@ -139,6 +194,10 @@ export declare class TurnHandle implements Turn {
139
194
  * state that INV-002's determinism would then have to defend.
140
195
  */
141
196
  deltas(): AsyncIterableIterator<ItemDeltaParams>;
197
+ cancel(): Promise<TurnCancelResult>;
198
+ interrupt(options?: InterruptTurnOptions): Promise<TurnInterruptResult>;
199
+ steer(options: SteerTurnOptions<I>): Promise<TurnSteerResult>;
200
+ unqueue(): Promise<TurnUnqueueOutcome<I>>;
142
201
  markStarted(): void;
143
202
  pushItem(item: FoldedItem): void;
144
203
  pushDelta(params: ItemDeltaParams): void;
@@ -3,8 +3,10 @@
3
3
  * tasks.md T030).
4
4
  *
5
5
  * A handle owns two things: the SS3.1.4 turn-wait, and the async iterators
6
- * that ride the fold for this turn. It authors no wire traffic and holds no
7
- * durable state — `Session` feeds it folded events and it fans them out.
6
+ * that ride the fold for this turn. It holds no durable state — `Session`
7
+ * feeds it folded events and it fans them out. Its control verbs
8
+ * (`cancel`/`interrupt`/`steer`/`unqueue`, FR-79106-1) author wire traffic
9
+ * only through the `TurnControls` its `Session` hands it.
8
10
  *
9
11
  * INV-006 governs the wait: the SDK never locally times out, fails, or
10
12
  * completes a turn. Every settlement below traces to a server-authored fact,
@@ -120,6 +122,7 @@ class PushStream {
120
122
  export class TurnHandle {
121
123
  turnId;
122
124
  #replayItems;
125
+ #controls;
123
126
  #itemStreams = new Set();
124
127
  #deltaStreams = new Set();
125
128
  #completed;
@@ -134,9 +137,10 @@ export class TurnHandle {
134
137
  * rendered as finished, which is the invented completion INV-006 forbids.
135
138
  */
136
139
  #failure;
137
- constructor(turnId, replayItems) {
140
+ constructor(turnId, replayItems, controls) {
138
141
  this.turnId = turnId;
139
142
  this.#replayItems = replayItems;
143
+ this.#controls = controls;
140
144
  this.#completed = new Promise((resolve, reject) => {
141
145
  this.#settle = resolve;
142
146
  this.#fail = reject;
@@ -194,6 +198,18 @@ export class TurnHandle {
194
198
  this.#admit(stream, this.#deltaStreams);
195
199
  return stream;
196
200
  }
201
+ cancel() {
202
+ return this.#controls.cancel(this.turnId);
203
+ }
204
+ interrupt(options = {}) {
205
+ return this.#controls.interrupt(this.turnId, options);
206
+ }
207
+ steer(options) {
208
+ return this.#controls.steer(this.turnId, options);
209
+ }
210
+ unqueue() {
211
+ return this.#controls.unqueue(this.turnId);
212
+ }
197
213
  /**
198
214
  * Register a fresh stream, or finish it the way this turn already finished.
199
215
  * The failure branch comes FIRST: a turn that failed is not a turn that
@@ -1,21 +1,23 @@
1
1
  /**
2
- * `turn/start` submission and same-`commandId` replay (spec 14990 FR-018 /
3
- * T030 obligations (a) and (d); tdd SS3.1.1, SS3.2, SS4.13).
2
+ * `turn/start` and `turn/steer` submission and same-`commandId` replay (spec
3
+ * 14990 FR-018 / T030 obligations (a) and (d), FR-79106-1; tdd SS3.1.1,
4
+ * SS3.2, SS3.3, SS4.13).
4
5
  *
5
6
  * Split out of `session.ts` for the same reason `approval.ts` was: this is a
6
7
  * wire-shaping and idempotency concern, not a fold concern, and `Session` was
7
8
  * already the package's largest module.
8
9
  *
9
10
  * It holds the ONE piece of state `PendingCommandSet` deliberately cannot: the
10
- * `turn/start` params per `commandId`. The set stores the COMPOSER input and is
11
- * wire-blind by design (INV-001), so a replay — which must re-send the SAME
12
- * logical command, byte for byte, to be the sanctioned retry rather than a
13
- * double execution — needs the params to live on this side of that boundary.
11
+ * submitted method and params per `commandId`. The set stores the COMPOSER
12
+ * input and is wire-blind by design (INV-001), so a replay — which must re-send
13
+ * the SAME logical command, byte for byte, to be the sanctioned retry rather
14
+ * than a double execution — needs the params to live on this side of that
15
+ * boundary.
14
16
  */
15
17
  import type { Connection } from "../connection/connection.js";
16
18
  import type { PendingCommandSet } from "../pending/pending-command-set.js";
17
19
  import type { CommandErrorResponse, PendingCommandAck, PendingRetirement, ReplayAnswer } from "../pending/pending-command-set.js";
18
- import type { TurnStartParams } from "../msp.js";
20
+ import type { TurnStartParams, TurnSteerParams, TurnSteerResult } from "../msp.js";
19
21
  /**
20
22
  * What `Session.sendUserTurn` sends, COMPOSED from the generated params rather
21
23
  * than restated (INV-001).
@@ -32,6 +34,16 @@ export type SendUserTurnOptions<I> = Readonly<Omit<TurnStartParams, "commandId"
32
34
  */
33
35
  readonly composerInput?: I;
34
36
  };
37
+ /**
38
+ * What a turn handle's `steer` sends (`turn/steer`, tdd SS3.3), composed from
39
+ * the generated params. `expectedTurnId` is the handle's own turn, and
40
+ * `commandId`/`sessionId` are excluded for the same reasons as on
41
+ * {@link SendUserTurnOptions}.
42
+ */
43
+ export type SteerTurnOptions<I> = Readonly<Omit<TurnSteerParams, "commandId" | "sessionId" | "expectedTurnId">> & {
44
+ /** What to hand back to the composer if this steer is ever retired (SS4.13). */
45
+ readonly composerInput?: I;
46
+ };
35
47
  /**
36
48
  * An `MspError` as the pending set reads it (SS4.13's settlement test).
37
49
  *
@@ -45,18 +57,17 @@ export declare class TurnSubmitter<I> {
45
57
  constructor(sessionId: string, connection: Connection | undefined, pending: PendingCommandSet<I>);
46
58
  get wired(): boolean;
47
59
  requireConnection(verb: string): Connection;
60
+ /** Submit a `turn/start` through the SS4.13 path (`#submitRecorded`). */
61
+ submit(options: SendUserTurnOptions<I>, anchorAfterItemId: string | null): Promise<PendingCommandAck>;
48
62
  /**
49
- * Record the optimistic SS4.13 entry, then send `turn/start`.
50
- *
51
- * The ORDER is the point. An entry created only on the ack is invisible for
52
- * exactly the window it exists to cover — between the user pressing enter and
53
- * the host answering — and `anchorAfterItemId` is fixed here, at submission
54
- * time, because SS4.13's insertion point may never be relocated by events
55
- * that fold in afterwards.
63
+ * Steer `turnId` (`turn/steer`, tdd SS3.3) through the same SS4.13 path as
64
+ * `submit`: SS4.13's entry exists "from the moment it submits `turn/start`
65
+ * (or `turn/steer`)", and the steer's `userMessage` echoes its `commandId`,
66
+ * so materialization, rejection and reconnect replay all ride the set.
56
67
  */
57
- submit(options: SendUserTurnOptions<I>, anchorAfterItemId: string | null): Promise<PendingCommandAck>;
68
+ steer(turnId: string, options: SteerTurnOptions<I>, anchorAfterItemId: string | null): Promise<TurnSteerResult>;
58
69
  /**
59
- * Re-send one remembered `turn/start` under its ORIGINAL `commandId`
70
+ * Re-send one remembered submission under its ORIGINAL `commandId`
60
71
  * (SS3.1.1 — always safe, and the only re-send that is not a double
61
72
  * execution).
62
73
  *
@@ -1,16 +1,18 @@
1
1
  /**
2
- * `turn/start` submission and same-`commandId` replay (spec 14990 FR-018 /
3
- * T030 obligations (a) and (d); tdd SS3.1.1, SS3.2, SS4.13).
2
+ * `turn/start` and `turn/steer` submission and same-`commandId` replay (spec
3
+ * 14990 FR-018 / T030 obligations (a) and (d), FR-79106-1; tdd SS3.1.1,
4
+ * SS3.2, SS3.3, SS4.13).
4
5
  *
5
6
  * Split out of `session.ts` for the same reason `approval.ts` was: this is a
6
7
  * wire-shaping and idempotency concern, not a fold concern, and `Session` was
7
8
  * already the package's largest module.
8
9
  *
9
10
  * It holds the ONE piece of state `PendingCommandSet` deliberately cannot: the
10
- * `turn/start` params per `commandId`. The set stores the COMPOSER input and is
11
- * wire-blind by design (INV-001), so a replay — which must re-send the SAME
12
- * logical command, byte for byte, to be the sanctioned retry rather than a
13
- * double execution — needs the params to live on this side of that boundary.
11
+ * submitted method and params per `commandId`. The set stores the COMPOSER
12
+ * input and is wire-blind by design (INV-001), so a replay — which must re-send
13
+ * the SAME logical command, byte for byte, to be the sanctioned retry rather
14
+ * than a double execution — needs the params to live on this side of that
15
+ * boundary.
14
16
  */
15
17
  import { MspError } from "../connection/connection.js";
16
18
  /**
@@ -29,6 +31,14 @@ const TURN_START_FORWARDED = [
29
31
  // v1 stable member, forwarded like any other.
30
32
  "userShell",
31
33
  ];
34
+ /** Every `turn/steer` member forwarded; a regenerated member fails the build. */
35
+ const TURN_STEER_FORWARDED = ["input", "reasoningEffort"];
36
+ /**
37
+ * A steer's ack carries no disposition, but it IS the steered admission SS4.13
38
+ * names: the input is pending on the running turn's steer queue, so the entry
39
+ * holds like a `turn/start` acked `"steered"` (the acked-steer join arm).
40
+ */
41
+ const STEERED = "steered";
32
42
  /**
33
43
  * An `MspError` as the pending set reads it (SS4.13's settlement test).
34
44
  *
@@ -69,8 +79,38 @@ export class TurnSubmitter {
69
79
  }
70
80
  return connection;
71
81
  }
82
+ /** Submit a `turn/start` through the SS4.13 path (`#submitRecorded`). */
83
+ async submit(options, anchorAfterItemId) {
84
+ const connection = this.requireConnection("sendUserTurn");
85
+ // Delegated, not re-implemented: the connection owns the single mint, so
86
+ // INV-013's single-minter property survives this verb needing the id early.
87
+ const commandId = connection.mintCommandId();
88
+ const params = this.#params(commandId, options);
89
+ const sent = await this.#submitRecorded(connection, commandId, { method: "turn/start", params }, options.composerInput, anchorAfterItemId);
90
+ return sent.ack;
91
+ }
72
92
  /**
73
- * Record the optimistic SS4.13 entry, then send `turn/start`.
93
+ * Steer `turnId` (`turn/steer`, tdd SS3.3) through the same SS4.13 path as
94
+ * `submit`: SS4.13's entry exists "from the moment it submits `turn/start`
95
+ * (or `turn/steer`)", and the steer's `userMessage` echoes its `commandId`,
96
+ * so materialization, rejection and reconnect replay all ride the set.
97
+ */
98
+ async steer(turnId, options, anchorAfterItemId) {
99
+ const connection = this.requireConnection("steer");
100
+ const commandId = connection.mintCommandId();
101
+ const params = {
102
+ commandId,
103
+ expectedTurnId: turnId,
104
+ input: options.input,
105
+ sessionId: this.#sessionId,
106
+ };
107
+ if (options.reasoningEffort != null)
108
+ params.reasoningEffort = options.reasoningEffort;
109
+ const sent = await this.#submitRecorded(connection, commandId, { method: "turn/steer", params }, options.composerInput, anchorAfterItemId);
110
+ return sent.result;
111
+ }
112
+ /**
113
+ * Record the optimistic SS4.13 entry, then send.
74
114
  *
75
115
  * The ORDER is the point. An entry created only on the ack is invisible for
76
116
  * exactly the window it exists to cover — between the user pressing enter and
@@ -78,23 +118,19 @@ export class TurnSubmitter {
78
118
  * time, because SS4.13's insertion point may never be relocated by events
79
119
  * that fold in afterwards.
80
120
  */
81
- async submit(options, anchorAfterItemId) {
82
- const connection = this.requireConnection("sendUserTurn");
83
- // Delegated, not re-implemented: the connection owns the single mint, so
84
- // INV-013's single-minter property survives this verb needing the id early.
85
- const commandId = connection.mintCommandId();
86
- const params = this.#params(commandId, options);
121
+ async #submitRecorded(connection, commandId, remembered, input, anchorAfterItemId) {
122
+ const displayText = remembered.method === "turn/start" ? remembered.params.displayText : undefined;
87
123
  this.#pending.submitted({
88
124
  anchorAfterItemId,
89
125
  commandId,
90
- input: options.composerInput,
91
- ...(params.displayText === undefined ? {} : { displayText: params.displayText }),
126
+ input,
127
+ ...(displayText === undefined ? {} : { displayText }),
92
128
  });
93
- this.#memory.set(commandId, params);
129
+ this.#memory.set(commandId, remembered);
94
130
  try {
95
- const ack = await this.#send(connection, params, commandId);
96
- this.#pending.acked(commandId, ack);
97
- return ack;
131
+ const sent = await this.#send(connection, remembered, commandId);
132
+ this.#pending.acked(commandId, sent.ack);
133
+ return sent;
98
134
  }
99
135
  catch (error) {
100
136
  const response = commandErrorResponse(error);
@@ -111,7 +147,7 @@ export class TurnSubmitter {
111
147
  }
112
148
  }
113
149
  /**
114
- * Re-send one remembered `turn/start` under its ORIGINAL `commandId`
150
+ * Re-send one remembered submission under its ORIGINAL `commandId`
115
151
  * (SS3.1.1 — always safe, and the only re-send that is not a double
116
152
  * execution).
117
153
  *
@@ -120,12 +156,12 @@ export class TurnSubmitter {
120
156
  * transport/protocol one, which proves nothing about the intake.
121
157
  */
122
158
  async replay(commandId) {
123
- const params = this.#memory.get(commandId);
124
- if (params === undefined)
159
+ const remembered = this.#memory.get(commandId);
160
+ if (remembered === undefined)
125
161
  return undefined;
126
- const connection = this.requireConnection("turn/start replay");
162
+ const connection = this.requireConnection(`${remembered.method} replay`);
127
163
  try {
128
- return { ack: await this.#send(connection, params, commandId), kind: "ack" };
164
+ return { ack: (await this.#send(connection, remembered, commandId)).ack, kind: "ack" };
129
165
  }
130
166
  catch (error) {
131
167
  const response = commandErrorResponse(error);
@@ -148,12 +184,16 @@ export class TurnSubmitter {
148
184
  for (const retirement of retirements)
149
185
  this.#memory.delete(retirement.commandId);
150
186
  }
151
- async #send(connection, params, commandId) {
152
- const raw = await connection.command("turn/start", params, { commandId });
153
- const result = raw;
187
+ async #send(connection, remembered, commandId) {
188
+ const result = await connection.command(remembered.method, remembered.params, { commandId });
154
189
  // `turnId` comes from the ACK and never from the `commandId`: SS3.2 makes
155
190
  // the ack authoritative, and a queued submit's turn may already exist.
156
- return { disposition: result.disposition, turnId: result.turnId };
191
+ if (remembered.method === "turn/steer") {
192
+ const steered = result;
193
+ return { ack: { disposition: STEERED, turnId: steered.turnId }, result };
194
+ }
195
+ const started = result;
196
+ return { ack: { disposition: started.disposition, turnId: started.turnId }, result };
157
197
  }
158
198
  /**
159
199
  * OPTIONAL MEANS OMITTED, NEVER `null` (tdd SS1.2), and the guards are LOOSE
@@ -1,26 +1,12 @@
1
- /**
2
- * The schema-bundle staleness anchor (spec 14990 FR-006).
3
- *
4
- * `EXPECTED_SCHEMA_FINGERPRINT` pins the stable protocol-schema fingerprint
5
- * this SDK was written against. Two consumers:
6
- *
7
- * - Build time: a test asserts this equals `schema/msp/stable/manifest.json`,
8
- * so a schema advance that forgets the SDK reds the SDK lane instead of
9
- * shipping a silently-stale facade. This is the same manifest-pin pattern
10
- * the #210 transcripts use.
11
- * - Runtime: the connection machine compares `InitializeResult.schema
12
- * .fingerprint` against this pin. A mismatch is a WARNING, never an error
13
- * (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
14
- * working against a newer host.
15
- */
16
- export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:c94c3d1f2f51e6424074b9ec43eac3eedcf532d3dcd77351ec1383a87d3049c6";
1
+ export declare const EXPECTED_SCHEMA_FINGERPRINT: string;
17
2
  /**
18
3
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
4
  *
20
5
  * A mismatch is the normal, expected consequence of the protocol schema
21
6
  * advancing — it is NOT evidence that the SDK is broken. The remedy is to
22
- * re-pin and adapt whatever actually changed. Several lanes have burned time
23
- * reading a red fingerprint as an SDK defect, so the message says it plainly.
7
+ * rebuild and adapt whatever actually changed. Several lanes have burned
8
+ * time reading a red fingerprint as an SDK defect, so the message says it
9
+ * plainly.
24
10
  */
25
11
  export declare function fingerprintMismatchMessage(pinned: string, actual: string): string;
26
12
  /** The runtime arm (tdd SS1.4.1): advisory only, never a connection failure. */
@@ -1,37 +1,47 @@
1
1
  /**
2
2
  * The schema-bundle staleness anchor (spec 14990 FR-006).
3
3
  *
4
- * `EXPECTED_SCHEMA_FINGERPRINT` pins the stable protocol-schema fingerprint
5
- * this SDK was written against. Two consumers:
4
+ * `EXPECTED_SCHEMA_FINGERPRINT` is the stable protocol-schema fingerprint
5
+ * this SDK was built against. It derives at build: the `prebuild` step
6
+ * (`node scripts/msp-fingerprint.mjs --stamp`) computes it from the
7
+ * committed schema bytes and stamps the generated module this file imports
8
+ * (ADR 77546 D4). No literal is committed here — a schema advance moves
9
+ * the value at the next build, and two PRs that change different schema
10
+ * regions never conflict on this file.
6
11
  *
7
- * - Build time: a test asserts this equals `schema/msp/stable/manifest.json`,
8
- * so a schema advance that forgets the SDK reds the SDK lane instead of
9
- * shipping a silently-stale facade. This is the same manifest-pin pattern
10
- * the #210 transcripts use.
12
+ * Two consumers:
13
+ *
14
+ * - Build time: the receipt-pins gate proves this file carries the
15
+ * derivation hook and no committed copy, and the sdk-ts suite proves
16
+ * the stamped value equals the port's derivation over the live schema
17
+ * bytes — so a schema advance that the build somehow misses reds
18
+ * instead of shipping a silently-stale facade.
11
19
  * - Runtime: the connection machine compares `InitializeResult.schema
12
- * .fingerprint` against this pin. A mismatch is a WARNING, never an error
13
- * (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
14
- * working against a newer host.
20
+ * .fingerprint` against this value. A mismatch is a WARNING, never an
21
+ * error (tdd SS1.4.1) — additive-optional evolution means an older SDK
22
+ * keeps working against a newer host.
15
23
  */
16
- export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:c94c3d1f2f51e6424074b9ec43eac3eedcf532d3dcd77351ec1383a87d3049c6";
24
+ import { STAMPED_SCHEMA_FINGERPRINT } from "./fingerprint.stamped.js";
25
+ export const EXPECTED_SCHEMA_FINGERPRINT = STAMPED_SCHEMA_FINGERPRINT;
17
26
  /**
18
27
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
28
  *
20
29
  * A mismatch is the normal, expected consequence of the protocol schema
21
30
  * advancing — it is NOT evidence that the SDK is broken. The remedy is to
22
- * re-pin and adapt whatever actually changed. Several lanes have burned time
23
- * reading a red fingerprint as an SDK defect, so the message says it plainly.
31
+ * rebuild and adapt whatever actually changed. Several lanes have burned
32
+ * time reading a red fingerprint as an SDK defect, so the message says it
33
+ * plainly.
24
34
  */
25
35
  export function fingerprintMismatchMessage(pinned, actual) {
26
36
  return [
27
- "MSP schema fingerprint moved: re-pin after a schema advance.",
28
- ` pinned by @muse-code/sdk: ${pinned}`,
29
- ` schema/msp/stable/manifest.json: ${actual}`,
37
+ "MSP schema fingerprint moved: rebuild after a schema advance.",
38
+ ` built by @muse-code/sdk: ${pinned}`,
39
+ ` derived stable schema fingerprint: ${actual}`,
30
40
  "",
31
41
  "This does NOT mean the SDK is broken. The stable schema bundle advanced",
32
- "(a #206 enrollment or renderer change). Fix it by running",
33
- "scripts/regen-msp-pins.sh, which re-pins EXPECTED_SCHEMA_FINGERPRINT and",
34
- "every other derived copy from the committed stable manifest, then adapt",
42
+ "(a #206 enrollment or renderer change). Fix it by rebuilding",
43
+ "(`npm run build` re-stamps EXPECTED_SCHEMA_FINGERPRINT from the",
44
+ "committed schema bytes), then adapt",
35
45
  "the facade to whatever the advance actually changed. Never hand-edit",
36
46
  "schema/msp/** to match the SDK.",
37
47
  ].join("\n");
@@ -48,7 +58,7 @@ export function checkServedFingerprint(served, pinned = EXPECTED_SCHEMA_FINGERPR
48
58
  pinned,
49
59
  served,
50
60
  message: `host schema fingerprint ${served} differs from the fingerprint this ` +
51
- `SDK pins (${pinned}); proceeding under additive-optional evolution ` +
52
- `(SS1.5.4). Re-pin after a schema advance.`,
61
+ `SDK was built against (${pinned}); proceeding under additive-optional ` +
62
+ `evolution (SS1.5.4). Rebuild after a schema advance.`,
53
63
  };
54
64
  }
@@ -0,0 +1 @@
1
+ export declare const STAMPED_SCHEMA_FINGERPRINT = "sha256:ef311d2dbf051ed9114556e14ad3980eb515104baa3409306a6817082a61d8cd";
@@ -0,0 +1,6 @@
1
+ // GENERATED by `node scripts/msp-fingerprint.mjs --stamp` (runs on every
2
+ // `npm run build` / `npm run check`). Do not edit: the value derives from
3
+ // schema/msp/stable/msp.schema.json through the port in
4
+ // scripts/msp-fingerprint.mjs. A schema advance moves this value at the
5
+ // next build; the file itself is gitignored and never committed.
6
+ export const STAMPED_SCHEMA_FINGERPRINT = "sha256:ef311d2dbf051ed9114556e14ad3980eb515104baa3409306a6817082a61d8cd";
@@ -14,7 +14,8 @@
14
14
  *
15
15
  * - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
16
16
  * `turn/unqueued`, and the non-terminal `turn/retryScheduled`,
17
- * `turn/modelRetryScheduled`, and `turn/foregroundCompleted`;
17
+ * `turn/modelRetryScheduled`, `turn/modelAttemptStarted`, and
18
+ * `turn/foregroundCompleted`;
18
19
  * - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
19
20
  * sets and their first durable terminal. The decision flow (choosing and
20
21
  * sending a resolution) is the facade's, not the fold's;
@@ -27,7 +28,7 @@
27
28
  * unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
28
29
  * displaces the first durable one.
29
30
  */
30
- import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MonitorInboxItemAdmittedParams, MonitorInboxItemDrainedParams, MonitorInboxItemVoidedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
31
+ import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MonitorInboxItemAdmittedParams, MonitorInboxItemDrainedParams, MonitorInboxItemVoidedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnModelAttemptStartedParams, TurnModelRetryScheduledParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
31
32
  import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
32
33
  import type { StateApplyOutcome, StateValue } from "./state-store.js";
33
34
  /** The session-state families, each keyed in the store by its method name. */
@@ -63,6 +64,9 @@ export type ViewEvent = {
63
64
  } | {
64
65
  readonly method: "turn/modelRetryScheduled";
65
66
  readonly params: TurnModelRetryScheduledParams;
67
+ } | {
68
+ readonly method: "turn/modelAttemptStarted";
69
+ readonly params: TurnModelAttemptStartedParams;
66
70
  } | {
67
71
  readonly method: "turn/unqueued";
68
72
  readonly params: TurnUnqueuedParams;
@@ -195,7 +199,7 @@ export type ViewEvent = {
195
199
  type AssertNever<T extends never> = T;
196
200
  type LiveHostStateProjection = "skill/changed" | "usage/changed" | "session/statusChanged" | "session/listChanged" | "plugin/changed" | "plugin/marketplaceChanged" | "computerUseSetup/changed";
197
201
  type SessionLifecycleBroadcast = "session/started" | "session/closed";
198
- type NonFoldNotification = "initialized" | "userInput/engaged" | "session/viewHealthChanged" | "session/leaveCompleted" | "recap/completed" | SessionLifecycleBroadcast | LiveHostStateProjection;
202
+ type NonFoldNotification = "initialized" | "userInput/engaged" | "session/viewHealthChanged" | "session/leaveCompleted" | "recap/completed" | "model/completed" | SessionLifecycleBroadcast | LiveHostStateProjection;
199
203
  type UnfoldedViewNotification = Exclude<MspNotification, NonFoldNotification | ViewEvent["method"]>;
200
204
  export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
201
205
  /**
@@ -241,7 +245,7 @@ export type SessionStateMethod = ViewEvent["method"] & `session/${string}`;
241
245
  * and could never match exhaustively. A future arm that starts dropping
242
246
  * widens this deliberately (PR #23087 review round).
243
247
  */
244
- export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/retracted" | "turn/foregroundCompleted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested" | "view/gap";
248
+ export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/retracted" | "turn/foregroundCompleted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/modelAttemptStarted" | "approval/requested" | "approval/updated" | "userInput/requested" | "view/gap";
245
249
  /**
246
250
  * The `NoStaleViewArm` sibling for the union above: these are hand-typed
247
251
  * literals, so without this pin a typo'd or later-retired member compiles
@@ -271,6 +275,13 @@ export interface TurnEntry {
271
275
  * its delay. Clears on the turn's terminal.
272
276
  */
273
277
  readonly modelRetryScheduled?: TurnModelRetryScheduledParams;
278
+ /**
279
+ * The latest model attempt start (tdd SS4.5.1, ADR 68644 D1), recorded
280
+ * before the provider dials; non-terminal. It stays set through tool runs
281
+ * and retry backoffs until the turn's terminal, so it is not a live
282
+ * "model is working" flag.
283
+ */
284
+ readonly modelAttemptStarted?: TurnModelAttemptStartedParams;
274
285
  /**
275
286
  * The latest foreground-completed notice; non-terminal (tdd SS4.5.12).
276
287
  * Tells a renderer the answer is done while `blockingAgents` hold the
@@ -401,13 +412,16 @@ export type FoldOutcome = {
401
412
  /**
402
413
  * A recognized frame the fold deliberately dropped, leaving state
403
414
  * unchanged: a `turn/started`, `turn/retryScheduled`,
404
- * `turn/modelRetryScheduled` or `turn/foregroundCompleted` for a turn
415
+ * `turn/modelRetryScheduled`, `turn/modelAttemptStarted` or
416
+ * `turn/foregroundCompleted` for a turn
405
417
  * that already left `running`; a `turn/completed` for a `retracted` or
406
418
  * `unqueued` turn; a declined `turn/retracted` for a turn the fold has
407
419
  * not seen; an `approval/updated` for an approval it never saw
408
420
  * requested (or whose entry a resolution already deleted); or a
409
421
  * redelivered `approval/requested` / `userInput/requested` for an
410
422
  * approval/prompt that already has its durable terminal; or a
423
+ * `userInput/requested` for a turn already known to have left
424
+ * `running`; or a
411
425
  * `view/gap` whose `next` an earlier frame already named while the
412
426
  * hole is open (`id` is that `next`, #62032). Truthful by
413
427
  * contract: a "pending" kind here would make a renderer show an entry