@muse-code/sdk 0.1.0 → 1.3.0
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 +56 -238
- package/dist/src/connection/connection.d.ts +1 -1
- package/dist/src/connection/spawn.d.ts +1 -1
- package/dist/src/facade/approval.d.ts +21 -1
- package/dist/src/facade/approval.js +97 -1
- package/dist/src/facade/client.d.ts +4 -5
- package/dist/src/facade/client.js +7 -3
- package/dist/src/facade/host-death.d.ts +1 -1
- package/dist/src/facade/session.d.ts +1 -1
- package/dist/src/facade/session.js +26 -12
- package/dist/src/facade/turn-handle.d.ts +1 -1
- package/dist/src/facade/turn-submit.d.ts +1 -1
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/fold/session-fold.d.ts +74 -12
- package/dist/src/fold/session-fold.js +6 -2
- package/dist/src/index.d.ts +8 -1
- package/dist/src/msp.d.ts +2363 -0
- package/dist/src/pending/pending-command-set.d.ts +1 -1
- package/package.json +10 -2
|
@@ -253,6 +253,18 @@ export class Session {
|
|
|
253
253
|
if (outcome.kind === "approvalPending")
|
|
254
254
|
this.#approvalRequested(known.params, tasks);
|
|
255
255
|
break;
|
|
256
|
+
case "approval/updated":
|
|
257
|
+
// FR-019's outbound half too (#36949): a stage advance is delivered by
|
|
258
|
+
// this frame alone on the notification plane, so it must drive the
|
|
259
|
+
// handler — the why and the request merge live on
|
|
260
|
+
// `ApprovalRouter.updated`. The same fold verdict gates it: an update
|
|
261
|
+
// the fold IGNORED (unknown or already-resolved approval) authors
|
|
262
|
+
// nothing, and the verdict itself carries the retained request the
|
|
263
|
+
// merge needs.
|
|
264
|
+
if (outcome.kind === "approvalPending") {
|
|
265
|
+
this.#approvalUpdated(outcome.requested, known.params, tasks);
|
|
266
|
+
}
|
|
267
|
+
break;
|
|
256
268
|
// Folded, deliberately NOT routed to a turn handle. Listed rather than
|
|
257
269
|
// defaulted so this switch is exhaustive over `ViewEvent`: the fold's
|
|
258
270
|
// `AssertNever` forces each new #206 view notification into that union,
|
|
@@ -265,23 +277,19 @@ export class Session {
|
|
|
265
277
|
case "view/gap":
|
|
266
278
|
case "turn/retracted": // the turn still reaches its own terminal
|
|
267
279
|
case "turn/retryScheduled": // non-terminal by contract (SS4.5.1)
|
|
268
|
-
// An UPDATE refreshes a pending approval; it never opens one, and it
|
|
269
|
-
// carries none of the request-shape members (`itemId`, `turnId`,
|
|
270
|
-
// `toolName`) an `ApprovalHandler` is typed on. SS5.6.3: a re-issued
|
|
271
|
-
// REQUEST embodies the refresh, and that is the frame that drives the
|
|
272
|
-
// handler — so calling it from here would either lie about the request
|
|
273
|
-
// or need a second, thinner handler type for one wire event.
|
|
274
|
-
case "approval/updated":
|
|
275
280
|
case "approval/resolved":
|
|
276
281
|
case "userInput/requested":
|
|
277
282
|
case "userInput/settled":
|
|
278
283
|
case "session/modelChanged":
|
|
284
|
+
case "session/reasoningEffortChanged":
|
|
279
285
|
case "session/goalChanged":
|
|
280
286
|
case "session/todoListChanged":
|
|
281
287
|
case "session/branchChanged":
|
|
282
288
|
case "session/tokenUsage":
|
|
283
289
|
case "session/contextUsage":
|
|
284
290
|
case "session/approvalModeChanged":
|
|
291
|
+
case "session/modelRouteUnserved":
|
|
292
|
+
case "session/nameChanged":
|
|
285
293
|
break;
|
|
286
294
|
default: {
|
|
287
295
|
// Compile-time exhaustiveness. Runtime tolerance of a newer host's
|
|
@@ -592,6 +600,13 @@ export class Session {
|
|
|
592
600
|
if (decided !== undefined)
|
|
593
601
|
tasks.push(decided.then(() => []));
|
|
594
602
|
}
|
|
603
|
+
/** The #36949 stage-advance re-route; the merge lives on `ApprovalRouter.updated`. */
|
|
604
|
+
#approvalUpdated(requested, params, tasks) {
|
|
605
|
+
const decided = this.#approvals.updated(requested, params);
|
|
606
|
+
// Awaitable through `io`, same as `#approvalRequested` above.
|
|
607
|
+
if (decided !== undefined)
|
|
608
|
+
tasks.push(decided.then(() => []));
|
|
609
|
+
}
|
|
595
610
|
#itemsOfTurn(turnId) {
|
|
596
611
|
return this.#fold.items.list().filter((item) => item.turnId === turnId);
|
|
597
612
|
}
|
|
@@ -606,11 +621,10 @@ export class Session {
|
|
|
606
621
|
retirements.push(materialized);
|
|
607
622
|
}
|
|
608
623
|
// `!= null`, not `!== undefined`: `userShell` items carry `turnId: null`
|
|
609
|
-
// on the wire (spec Edge Cases; tdd SS4.5.6 example)
|
|
610
|
-
//
|
|
611
|
-
//
|
|
612
|
-
|
|
613
|
-
const turnId = item.turnId ?? undefined;
|
|
624
|
+
// on the wire (spec Edge Cases; tdd SS4.5.6 example). A `!== undefined`
|
|
625
|
+
// guard let null through and minted a phantom turn keyed `null`,
|
|
626
|
+
// attributing the userShell item and its deltas to it (#23557).
|
|
627
|
+
const turnId = item.turnId;
|
|
614
628
|
if (turnId != null)
|
|
615
629
|
this.#handle(turnId).pushItem(item);
|
|
616
630
|
const buffered = this.#unattributedDeltas.get(item.itemId);
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* client MUST ("stop waiting for a terminal") and which stays an annotation
|
|
14
14
|
* rather than a synthesized event.
|
|
15
15
|
*/
|
|
16
|
-
import type { Item, ItemDeltaParams, TurnCompletedParams, TurnUnqueuedParams } from "
|
|
16
|
+
import type { Item, ItemDeltaParams, TurnCompletedParams, TurnUnqueuedParams } from "../msp.js";
|
|
17
17
|
import type { DeepReadonly } from "../fold/session-fold.js";
|
|
18
18
|
/**
|
|
19
19
|
* What the iterators yield: the fold's stored item, sealed.
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
import type { Connection } from "../connection/connection.js";
|
|
16
16
|
import type { PendingCommandSet } from "../pending/pending-command-set.js";
|
|
17
17
|
import type { CommandErrorResponse, PendingCommandAck, PendingRetirement, ReplayAnswer } from "../pending/pending-command-set.js";
|
|
18
|
-
import type { TurnStartParams } from "
|
|
18
|
+
import type { TurnStartParams } from "../msp.js";
|
|
19
19
|
/**
|
|
20
20
|
* What `Session.sendUserTurn` sends, COMPOSED from the generated params rather
|
|
21
21
|
* than restated (INV-001).
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
|
|
14
14
|
* working against a newer host.
|
|
15
15
|
*/
|
|
16
|
-
export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:
|
|
16
|
+
export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:7469c9e352e67def4a59df7e439984d7194fa351e1c8b7abb34060fd977ced81";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
package/dist/src/fingerprint.js
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
|
|
14
14
|
* working against a newer host.
|
|
15
15
|
*/
|
|
16
|
-
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:
|
|
16
|
+
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:7469c9e352e67def4a59df7e439984d7194fa351e1c8b7abb34060fd977ced81";
|
|
17
17
|
/**
|
|
18
18
|
* What a build-time mismatch MEANS, in the words a human needs at 2am.
|
|
19
19
|
*
|
|
@@ -26,11 +26,11 @@
|
|
|
26
26
|
* unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
|
|
27
27
|
* displaces the first durable one.
|
|
28
28
|
*/
|
|
29
|
-
import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "
|
|
29
|
+
import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
|
|
30
30
|
import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
|
|
31
31
|
import type { StateApplyOutcome, StateValue } from "./state-store.js";
|
|
32
32
|
/** The session-state families, each keyed in the store by its method name. */
|
|
33
|
-
export type SessionStateParams = SessionApprovalModeChangedParams | SessionBranchChangedParams | SessionContextUsageParams | SessionGoalChangedParams | SessionModelChangedParams | SessionTodoListChangedParams | SessionTokenUsageParams;
|
|
33
|
+
export type SessionStateParams = SessionApprovalModeChangedParams | SessionBranchChangedParams | SessionContextUsageParams | SessionGoalChangedParams | SessionModelChangedParams | SessionNameChangedParams | SessionReasoningEffortChangedParams | SessionTodoListChangedParams | SessionTokenUsageParams;
|
|
34
34
|
/** A view notification, paired with the generated params object it carries. */
|
|
35
35
|
export type ViewEvent = {
|
|
36
36
|
readonly method: "item/started";
|
|
@@ -77,6 +77,9 @@ export type ViewEvent = {
|
|
|
77
77
|
} | {
|
|
78
78
|
readonly method: "session/modelChanged";
|
|
79
79
|
readonly params: SessionModelChangedParams;
|
|
80
|
+
} | {
|
|
81
|
+
readonly method: "session/reasoningEffortChanged";
|
|
82
|
+
readonly params: SessionReasoningEffortChangedParams;
|
|
80
83
|
} | {
|
|
81
84
|
readonly method: "session/goalChanged";
|
|
82
85
|
readonly params: SessionGoalChangedParams;
|
|
@@ -95,6 +98,17 @@ export type ViewEvent = {
|
|
|
95
98
|
} | {
|
|
96
99
|
readonly method: "session/approvalModeChanged";
|
|
97
100
|
readonly params: SessionApprovalModeChangedParams;
|
|
101
|
+
} | {
|
|
102
|
+
readonly method: "session/nameChanged";
|
|
103
|
+
readonly params: SessionNameChangedParams;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* The one-shot login-swap route disclosure (#25603, tdd SS4.6.8): routed to
|
|
107
|
+
* its own non-storing outcome — a notice, never sticky session state.
|
|
108
|
+
*/
|
|
109
|
+
| {
|
|
110
|
+
readonly method: "session/modelRouteUnserved";
|
|
111
|
+
readonly params: SessionModelRouteUnservedParams;
|
|
98
112
|
}
|
|
99
113
|
/**
|
|
100
114
|
* The delivery-plane marker (tdd SS4.8). A `ViewEvent` since spec 14990
|
|
@@ -119,16 +133,34 @@ export type ViewEvent = {
|
|
|
119
133
|
};
|
|
120
134
|
/**
|
|
121
135
|
* Compile-time coverage: every `MspNotification` except the handshake's
|
|
122
|
-
* `initialized` is a fold input. A #206
|
|
123
|
-
* notification fails HERE rather than being
|
|
136
|
+
* `initialized` and the live host-state projections is a fold input. A #206
|
|
137
|
+
* enrollment that adds a view notification fails HERE rather than being
|
|
138
|
+
* silently ignored at runtime.
|
|
124
139
|
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
* removed by spec 14990 T032 when the marker became the `ViewEvent`
|
|
140
|
+
* The exclusions, each excluded because it is NOT a view event:
|
|
141
|
+
* - `initialized` is a HANDSHAKE notification, answered by `MspHandshake`
|
|
142
|
+
* before this fold exists. (The `view/gap` exclusion D-24021-1 recorded
|
|
143
|
+
* was removed by spec 14990 T032 when the marker became the `ViewEvent`
|
|
144
|
+
* arm above.)
|
|
145
|
+
* - `session/viewHealthChanged` (#32557, ADR 32557) is a COMMAND-PLANE
|
|
146
|
+
* health push, not a view-fold event: it reports that the live view
|
|
147
|
+
* stream stopped, so it carries no cursor and folds into no transcript
|
|
148
|
+
* state. A consumer handles it out of band (mark the session view
|
|
149
|
+
* unhealthy), never through this fold.
|
|
150
|
+
* - `usage/changed` (ADR 32563 D3, tdd SS3.23) is a live HOST-STATE push
|
|
151
|
+
* outside the view altitude: no `viewCursor`, no `sourceRange`, nothing
|
|
152
|
+
* seeded into either store; it reaches consumers through the ordinary
|
|
153
|
+
* notification hook, not this fold.
|
|
154
|
+
* - `skill/changed` (ADR 32471 D3, tdd SS3.22.2) is a live host-state
|
|
155
|
+
* projection carrying `sessionId` only — no `viewCursor`, no
|
|
156
|
+
* `sourceRange`, nothing durable to fold. The SDK consumer's reaction is
|
|
157
|
+
* an ACTION (re-issue `skill/list`), not fold state, so it rides the
|
|
158
|
+
* client's notification callback rather than this fold.
|
|
129
159
|
*/
|
|
130
160
|
type AssertNever<T extends never> = T;
|
|
131
|
-
type
|
|
161
|
+
type LiveHostStateProjection = "skill/changed" | "usage/changed" | "session/statusChanged" | "session/listChanged";
|
|
162
|
+
type NonFoldNotification = "initialized" | "session/viewHealthChanged" | LiveHostStateProjection;
|
|
163
|
+
type UnfoldedViewNotification = Exclude<MspNotification, NonFoldNotification | ViewEvent["method"]>;
|
|
132
164
|
export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
|
|
133
165
|
/**
|
|
134
166
|
* The reverse direction: every `ViewEvent` arm names a REAL generated
|
|
@@ -145,7 +177,7 @@ export type NoStaleViewArm = AssertNever<StaleViewArm>;
|
|
|
145
177
|
* vocabulary (the PR #23087 rule, applied to this file's only other
|
|
146
178
|
* hand-typed method set).
|
|
147
179
|
*/
|
|
148
|
-
type StaleExclusion = Exclude<
|
|
180
|
+
type StaleExclusion = Exclude<NonFoldNotification, MspNotification>;
|
|
149
181
|
export type NoStaleExclusion = AssertNever<StaleExclusion>;
|
|
150
182
|
/**
|
|
151
183
|
* A recursively read-only view of a value.
|
|
@@ -215,12 +247,32 @@ export type FoldOutcome = {
|
|
|
215
247
|
readonly kind: "turn";
|
|
216
248
|
readonly turnId: string;
|
|
217
249
|
readonly state: TurnState;
|
|
218
|
-
}
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* `outcome` is sealed for the same reason every getter is (D-14): the
|
|
253
|
+
* store hands back the very object it just stored, so an unsealed
|
|
254
|
+
* `current` is a live handle into fold state — `out.outcome.current
|
|
255
|
+
* .modelId = "..."` would mutate the fold with no cast and break INV-002
|
|
256
|
+
* replay equality. This and `approvalPending.requested` (#36949) are the
|
|
257
|
+
* two `FoldOutcome` arms that carry a params object; every other arm
|
|
258
|
+
* carries only ids, numbers, and booleans, which is why D-14 originally
|
|
259
|
+
* missed this one (#23556 item 2). Both seals are pinned by
|
|
260
|
+
* `@ts-expect-error` write probes in `session-fold.test.ts`.
|
|
261
|
+
*/
|
|
262
|
+
| {
|
|
219
263
|
readonly kind: "sessionState";
|
|
220
|
-
readonly outcome: StateApplyOutcome<SessionStateParams
|
|
264
|
+
readonly outcome: DeepReadonly<StateApplyOutcome<SessionStateParams>>;
|
|
221
265
|
} | {
|
|
222
266
|
readonly kind: "approvalPending";
|
|
223
267
|
readonly approvalId: string;
|
|
268
|
+
/**
|
|
269
|
+
* The pending entry's retained request (#36949): the facade's
|
|
270
|
+
* `approval/updated` re-route needs the request-shape members, and
|
|
271
|
+
* carrying them on the verdict itself makes "the fold vouched for this
|
|
272
|
+
* entry" and "here is that entry" one fact instead of a re-lookup a
|
|
273
|
+
* contract drift could silently miss.
|
|
274
|
+
*/
|
|
275
|
+
readonly requested: DeepReadonly<ApprovalRequestParams>;
|
|
224
276
|
} | {
|
|
225
277
|
readonly kind: "approvalResolved";
|
|
226
278
|
readonly approvalId: string;
|
|
@@ -248,6 +300,16 @@ export type FoldOutcome = {
|
|
|
248
300
|
readonly kind: "deliveryGap";
|
|
249
301
|
readonly after: string;
|
|
250
302
|
readonly next: string;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* The one-shot login-swap route disclosure (#25603, tdd SS4.6.8): a NOTICE,
|
|
306
|
+
* not a state family — it seeds no store (a repair via `session/setModel`
|
|
307
|
+
* would never clear a stored copy, and a snapshot reseed would wipe it), so
|
|
308
|
+
* the params ride the outcome verbatim for the consumer to render once.
|
|
309
|
+
*/
|
|
310
|
+
| {
|
|
311
|
+
readonly kind: "modelRouteUnserved";
|
|
312
|
+
readonly params: SessionModelRouteUnservedParams;
|
|
251
313
|
} | {
|
|
252
314
|
readonly kind: "ignoredUnrecognizedMethod";
|
|
253
315
|
readonly method: string;
|
|
@@ -174,13 +174,17 @@ export class SessionFold {
|
|
|
174
174
|
return this.#userInputSettled(typed.params);
|
|
175
175
|
case "view/gap":
|
|
176
176
|
return this.#deliveryGap(typed.params);
|
|
177
|
+
case "session/modelRouteUnserved":
|
|
178
|
+
return { kind: "modelRouteUnserved", params: typed.params };
|
|
177
179
|
case "session/modelChanged":
|
|
180
|
+
case "session/reasoningEffortChanged":
|
|
178
181
|
case "session/goalChanged":
|
|
179
182
|
case "session/todoListChanged":
|
|
180
183
|
case "session/branchChanged":
|
|
181
184
|
case "session/tokenUsage":
|
|
182
185
|
case "session/contextUsage":
|
|
183
186
|
case "session/approvalModeChanged":
|
|
187
|
+
case "session/nameChanged":
|
|
184
188
|
return {
|
|
185
189
|
kind: "sessionState",
|
|
186
190
|
outcome: this.#sessionStateStore.apply(typed.method, typed.params, typed.params.viewCursor),
|
|
@@ -352,7 +356,7 @@ export class SessionFold {
|
|
|
352
356
|
// the new request with the OLD update would show stale stage/choices and
|
|
353
357
|
// a decide against them bounces -32053.
|
|
354
358
|
this.#pendingApprovals.set(params.approvalId, { requested: params });
|
|
355
|
-
return { kind: "approvalPending", approvalId: params.approvalId };
|
|
359
|
+
return { kind: "approvalPending", approvalId: params.approvalId, requested: params };
|
|
356
360
|
}
|
|
357
361
|
#approvalUpdated(params) {
|
|
358
362
|
// An update REFRESHES a pending view; it never opens one. An update for an
|
|
@@ -370,7 +374,7 @@ export class SessionFold {
|
|
|
370
374
|
return { kind: "ignoredStaleFrame", method: "approval/updated", id: params.approvalId };
|
|
371
375
|
}
|
|
372
376
|
held.latestUpdate = params;
|
|
373
|
-
return { kind: "approvalPending", approvalId: params.approvalId };
|
|
377
|
+
return { kind: "approvalPending", approvalId: params.approvalId, requested: held.requested };
|
|
374
378
|
}
|
|
375
379
|
#approvalResolved(params) {
|
|
376
380
|
this.#pendingApprovals.delete(params.approvalId);
|
package/dist/src/index.d.ts
CHANGED
|
@@ -33,7 +33,14 @@ export type { DeltaApplyOutcome, ItemApplyOutcome, RevisionedItem, TerminalUnkno
|
|
|
33
33
|
export { SessionStateStore } from "./fold/state-store.js";
|
|
34
34
|
export type { StateApplyOutcome, StateValue } from "./fold/state-store.js";
|
|
35
35
|
export { SessionFold } from "./fold/session-fold.js";
|
|
36
|
-
export type {
|
|
36
|
+
export type {
|
|
37
|
+
/**
|
|
38
|
+
* Exported because it is CONSUMER SURFACE, not an internal pin: every
|
|
39
|
+
* getter on `SessionFold` returns `DeepReadonly<…>`, so a consumer naming
|
|
40
|
+
* one of those values needs the type. Without it they are stuck with
|
|
41
|
+
* `ReturnType<>` gymnastics or a deep `dist/` import (#23556 item 4).
|
|
42
|
+
*/
|
|
43
|
+
DeepReadonly, FoldItems, FoldOutcome, FoldSessionState, PendingApproval, SessionStateMethod, SessionStateParams, StaleDroppableMethod, TurnEntry, TurnState, ViewEvent, } from "./fold/session-fold.js";
|
|
37
44
|
export { COMMAND_REJECTED_CODE, COMMAND_REJECTED_KIND, PendingCommandSet, } from "./pending/pending-command-set.js";
|
|
38
45
|
export type { CommandErrorResponse, PendingCommandAck, PendingCommandEntry, PendingCommandSetOptions, PendingDisposition, PendingJoinPlan, PendingRetirement, ReplayAnswer, SnapshotJoinFacts, } from "./pending/pending-command-set.js";
|
|
39
46
|
export { Connection, createUuidV7Mint, MspError, ProtocolError, } from "./connection/connection.js";
|