@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.
- package/README.md +38 -3
- package/dist/src/connection/connection.js +2 -1
- package/dist/src/connection/discovery.d.ts +14 -0
- package/dist/src/connection/discovery.js +39 -0
- package/dist/src/errors.d.ts +37 -0
- package/dist/src/errors.js +52 -0
- package/dist/src/facade/client.d.ts +76 -12
- package/dist/src/facade/client.js +150 -13
- package/dist/src/facade/run.d.ts +50 -0
- package/dist/src/facade/run.js +132 -0
- package/dist/src/facade/session.d.ts +83 -3
- package/dist/src/facade/session.js +290 -2
- package/dist/src/facade/turn-handle.d.ts +65 -6
- package/dist/src/facade/turn-handle.js +19 -3
- package/dist/src/facade/turn-submit.d.ts +27 -16
- package/dist/src/facade/turn-submit.js +68 -28
- package/dist/src/fingerprint.d.ts +4 -18
- package/dist/src/fingerprint.js +30 -20
- package/dist/src/fingerprint.stamped.d.ts +1 -0
- package/dist/src/fingerprint.stamped.js +6 -0
- package/dist/src/fold/session-fold.d.ts +19 -5
- package/dist/src/fold/session-fold.js +73 -1
- package/dist/src/index.d.ts +5 -4
- package/dist/src/index.js +1 -1
- package/dist/src/msp.d.ts +353 -28
- package/package.json +3 -1
|
@@ -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
|
|
7
|
-
*
|
|
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
|
|
7
|
-
*
|
|
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
|
|
3
|
-
* T030 obligations (a) and (d); tdd SS3.1.1,
|
|
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
|
-
*
|
|
11
|
-
* wire-blind by design (INV-001), so a replay — which must re-send
|
|
12
|
-
* logical command, byte for byte, to be the sanctioned retry rather
|
|
13
|
-
* double execution — needs the params to live on this side of that
|
|
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
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
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
|
-
|
|
68
|
+
steer(turnId: string, options: SteerTurnOptions<I>, anchorAfterItemId: string | null): Promise<TurnSteerResult>;
|
|
58
69
|
/**
|
|
59
|
-
* Re-send one remembered
|
|
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
|
|
3
|
-
* T030 obligations (a) and (d); tdd SS3.1.1,
|
|
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
|
-
*
|
|
11
|
-
* wire-blind by design (INV-001), so a replay — which must re-send
|
|
12
|
-
* logical command, byte for byte, to be the sanctioned retry rather
|
|
13
|
-
* double execution — needs the params to live on this side of that
|
|
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
|
-
*
|
|
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
|
|
82
|
-
const
|
|
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
|
|
91
|
-
...(
|
|
126
|
+
input,
|
|
127
|
+
...(displayText === undefined ? {} : { displayText }),
|
|
92
128
|
});
|
|
93
|
-
this.#memory.set(commandId,
|
|
129
|
+
this.#memory.set(commandId, remembered);
|
|
94
130
|
try {
|
|
95
|
-
const
|
|
96
|
-
this.#pending.acked(commandId, ack);
|
|
97
|
-
return
|
|
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
|
|
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
|
|
124
|
-
if (
|
|
159
|
+
const remembered = this.#memory.get(commandId);
|
|
160
|
+
if (remembered === undefined)
|
|
125
161
|
return undefined;
|
|
126
|
-
const connection = this.requireConnection(
|
|
162
|
+
const connection = this.requireConnection(`${remembered.method} replay`);
|
|
127
163
|
try {
|
|
128
|
-
return { ack: await this.#send(connection,
|
|
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,
|
|
152
|
-
const
|
|
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
|
-
|
|
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
|
-
*
|
|
23
|
-
* reading a red fingerprint as an SDK defect, so the message says it
|
|
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. */
|
package/dist/src/fingerprint.js
CHANGED
|
@@ -1,37 +1,47 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The schema-bundle staleness anchor (spec 14990 FR-006).
|
|
3
3
|
*
|
|
4
|
-
* `EXPECTED_SCHEMA_FINGERPRINT`
|
|
5
|
-
* this SDK was
|
|
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
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* the
|
|
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
|
|
13
|
-
* (tdd SS1.4.1) — additive-optional evolution means an older SDK
|
|
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
|
-
|
|
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
|
-
*
|
|
23
|
-
* reading a red fingerprint as an SDK defect, so the message says it
|
|
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:
|
|
28
|
-
`
|
|
29
|
-
` schema
|
|
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
|
|
33
|
-
"
|
|
34
|
-
"
|
|
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
|
|
52
|
-
`(SS1.5.4).
|
|
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`,
|
|
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
|
|
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
|