@muse-code/sdk 0.1.1 → 1.4.2

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.
@@ -18,7 +18,13 @@ import { MspError } from "../connection/connection.js";
18
18
  * the guard chain in `#params` is hand-listed — so a regenerated member fails
19
19
  * the BUILD here until it is forwarded.
20
20
  */
21
- const TURN_START_FORWARDED = ["input", "displayText", "ifBusy", "reasoningEffort"];
21
+ const TURN_START_FORWARDED = [
22
+ "input",
23
+ "displayText",
24
+ "ifBusy",
25
+ "reasoningEffort",
26
+ "workspaceRoots",
27
+ ];
22
28
  /**
23
29
  * An `MspError` as the pending set reads it (SS4.13's settlement test).
24
30
  *
@@ -163,6 +169,8 @@ export class TurnSubmitter {
163
169
  params.ifBusy = options.ifBusy;
164
170
  if (options.reasoningEffort != null)
165
171
  params.reasoningEffort = options.reasoningEffort;
172
+ if (options.workspaceRoots != null)
173
+ params.workspaceRoots = options.workspaceRoots;
166
174
  return params;
167
175
  }
168
176
  }
@@ -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:03312c213efd14277a0e0a102f70adeae497a469ca4edf7242f479953ed758b7";
16
+ export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:61afea3112e0906e9dc3a536144278a74cb4b36fc6e20901a91d4432ba3568e2";
17
17
  /**
18
18
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
19
  *
@@ -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:03312c213efd14277a0e0a102f70adeae497a469ca4edf7242f479953ed758b7";
16
+ export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:61afea3112e0906e9dc3a536144278a74cb4b36fc6e20901a91d4432ba3568e2";
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 "../msp.js";
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,43 @@ 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 enrollment that adds a view
123
- * notification fails HERE rather than being silently ignored at runtime.
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
- * `initialized` is the sole remaining exclusion, and it is a HANDSHAKE
126
- * notification rather than a view one — it is answered by `MspHandshake`
127
- * before this fold exists. The `view/gap` exclusion D-24021-1 recorded was
128
- * removed by spec 14990 T032 when the marker became the `ViewEvent` arm above.
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/started` and `session/closed` (#33065's enrollment) are SS2.6
146
+ * control-plane lifecycle broadcasts, not view events — they carry no
147
+ * foldable view envelope (no `sourceRange`; `closed`'s `viewCursor` is a
148
+ * final session head, not view state), and a fold over session-view state
149
+ * has nothing to apply. Today a lifecycle frame keeps the pre-enrollment
150
+ * runtime answer (`ignoredUnrecognizedMethod`, pinned by the session-fold
151
+ * test); #33102 owns consciously surfacing the pair, the same sanctioned
152
+ * initial-drop shape D-24021-1 used for `view/gap` before T032 flipped it.
153
+ * - `session/viewHealthChanged` (#32557, ADR 32557) is a COMMAND-PLANE
154
+ * health push, not a view-fold event: it reports that the live view
155
+ * stream stopped, so it carries no cursor and folds into no transcript
156
+ * state. A consumer handles it out of band (mark the session view
157
+ * unhealthy), never through this fold.
158
+ * - `usage/changed` (ADR 32563 D3, tdd SS3.23) is a live HOST-STATE push
159
+ * outside the view altitude: no `viewCursor`, no `sourceRange`, nothing
160
+ * seeded into either store; it reaches consumers through the ordinary
161
+ * notification hook, not this fold.
162
+ * - `skill/changed` (ADR 32471 D3, tdd SS3.22.2) is a live host-state
163
+ * projection carrying `sessionId` only — no `viewCursor`, no
164
+ * `sourceRange`, nothing durable to fold. The SDK consumer's reaction is
165
+ * an ACTION (re-issue `skill/list`), not fold state, so it rides the
166
+ * client's notification callback rather than this fold.
129
167
  */
130
168
  type AssertNever<T extends never> = T;
131
- type UnfoldedViewNotification = Exclude<MspNotification, "initialized" | ViewEvent["method"]>;
169
+ type LiveHostStateProjection = "skill/changed" | "usage/changed" | "session/statusChanged" | "session/listChanged";
170
+ type SessionLifecycleBroadcast = "session/started" | "session/closed";
171
+ type NonFoldNotification = "initialized" | "session/viewHealthChanged" | "session/deleteCompleted" | SessionLifecycleBroadcast | LiveHostStateProjection;
172
+ type UnfoldedViewNotification = Exclude<MspNotification, NonFoldNotification | ViewEvent["method"]>;
132
173
  export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
133
174
  /**
134
175
  * The reverse direction: every `ViewEvent` arm names a REAL generated
@@ -139,13 +180,13 @@ export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification
139
180
  type StaleViewArm = Exclude<ViewEvent["method"], MspNotification>;
140
181
  export type NoStaleViewArm = AssertNever<StaleViewArm>;
141
182
  /**
142
- * The same reverse pin for the hand-typed exclusion literal above:
183
+ * The same reverse pin for the hand-typed exclusion literals above:
143
184
  * `Exclude` silently ignores excluder members outside the union, so a
144
- * retired or renamed `initialized` would otherwise compile clean as dead
145
- * vocabulary (the PR #23087 rule, applied to this file's only other
146
- * hand-typed method set).
185
+ * retired or renamed `initialized` — or a lifecycle name that leaves the
186
+ * union — would otherwise compile clean as dead vocabulary (the PR #23087
187
+ * rule, applied to this file's only other hand-typed method set).
147
188
  */
148
- type StaleExclusion = Exclude<"initialized", MspNotification>;
189
+ type StaleExclusion = Exclude<NonFoldNotification, MspNotification>;
149
190
  export type NoStaleExclusion = AssertNever<StaleExclusion>;
150
191
  /**
151
192
  * A recursively read-only view of a value.
@@ -215,12 +256,32 @@ export type FoldOutcome = {
215
256
  readonly kind: "turn";
216
257
  readonly turnId: string;
217
258
  readonly state: TurnState;
218
- } | {
259
+ }
260
+ /**
261
+ * `outcome` is sealed for the same reason every getter is (D-14): the
262
+ * store hands back the very object it just stored, so an unsealed
263
+ * `current` is a live handle into fold state — `out.outcome.current
264
+ * .modelId = "..."` would mutate the fold with no cast and break INV-002
265
+ * replay equality. This and `approvalPending.requested` (#36949) are the
266
+ * two `FoldOutcome` arms that carry a params object; every other arm
267
+ * carries only ids, numbers, and booleans, which is why D-14 originally
268
+ * missed this one (#23556 item 2). Both seals are pinned by
269
+ * `@ts-expect-error` write probes in `session-fold.test.ts`.
270
+ */
271
+ | {
219
272
  readonly kind: "sessionState";
220
- readonly outcome: StateApplyOutcome<SessionStateParams>;
273
+ readonly outcome: DeepReadonly<StateApplyOutcome<SessionStateParams>>;
221
274
  } | {
222
275
  readonly kind: "approvalPending";
223
276
  readonly approvalId: string;
277
+ /**
278
+ * The pending entry's retained request (#36949): the facade's
279
+ * `approval/updated` re-route needs the request-shape members, and
280
+ * carrying them on the verdict itself makes "the fold vouched for this
281
+ * entry" and "here is that entry" one fact instead of a re-lookup a
282
+ * contract drift could silently miss.
283
+ */
284
+ readonly requested: DeepReadonly<ApprovalRequestParams>;
224
285
  } | {
225
286
  readonly kind: "approvalResolved";
226
287
  readonly approvalId: string;
@@ -248,6 +309,16 @@ export type FoldOutcome = {
248
309
  readonly kind: "deliveryGap";
249
310
  readonly after: string;
250
311
  readonly next: string;
312
+ }
313
+ /**
314
+ * The one-shot login-swap route disclosure (#25603, tdd SS4.6.8): a NOTICE,
315
+ * not a state family — it seeds no store (a repair via `session/setModel`
316
+ * would never clear a stored copy, and a snapshot reseed would wipe it), so
317
+ * the params ride the outcome verbatim for the consumer to render once.
318
+ */
319
+ | {
320
+ readonly kind: "modelRouteUnserved";
321
+ readonly params: SessionModelRouteUnservedParams;
251
322
  } | {
252
323
  readonly kind: "ignoredUnrecognizedMethod";
253
324
  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);
@@ -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 { FoldItems, FoldOutcome, FoldSessionState, PendingApproval, SessionStateMethod, SessionStateParams, StaleDroppableMethod, TurnEntry, TurnState, ViewEvent, } from "./fold/session-fold.js";
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";