@muse-code/sdk 1.3.0 → 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.
@@ -50,6 +50,7 @@ const START_FORWARDED = [
50
50
  "providerId",
51
51
  "sessionId",
52
52
  "workspaceRoot",
53
+ "workspaceRoots",
53
54
  "modelId",
54
55
  ];
55
56
  /**
@@ -198,6 +199,8 @@ export class MuseClient {
198
199
  params.sessionId = options.sessionId;
199
200
  if (options.workspaceRoot != null)
200
201
  params.workspaceRoot = options.workspaceRoot;
202
+ if (options.workspaceRoots != null)
203
+ params.workspaceRoots = options.workspaceRoots;
201
204
  if (options.modelId != null)
202
205
  params.modelId = options.modelId;
203
206
  const raw = await this.#connection.command("session/start", params);
@@ -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:7469c9e352e67def4a59df7e439984d7194fa351e1c8b7abb34060fd977ced81";
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:7469c9e352e67def4a59df7e439984d7194fa351e1c8b7abb34060fd977ced81";
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
  *
@@ -142,6 +142,14 @@ export type ViewEvent = {
142
142
  * before this fold exists. (The `view/gap` exclusion D-24021-1 recorded
143
143
  * was removed by spec 14990 T032 when the marker became the `ViewEvent`
144
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.
145
153
  * - `session/viewHealthChanged` (#32557, ADR 32557) is a COMMAND-PLANE
146
154
  * health push, not a view-fold event: it reports that the live view
147
155
  * stream stopped, so it carries no cursor and folds into no transcript
@@ -159,7 +167,8 @@ export type ViewEvent = {
159
167
  */
160
168
  type AssertNever<T extends never> = T;
161
169
  type LiveHostStateProjection = "skill/changed" | "usage/changed" | "session/statusChanged" | "session/listChanged";
162
- type NonFoldNotification = "initialized" | "session/viewHealthChanged" | LiveHostStateProjection;
170
+ type SessionLifecycleBroadcast = "session/started" | "session/closed";
171
+ type NonFoldNotification = "initialized" | "session/viewHealthChanged" | "session/deleteCompleted" | SessionLifecycleBroadcast | LiveHostStateProjection;
163
172
  type UnfoldedViewNotification = Exclude<MspNotification, NonFoldNotification | ViewEvent["method"]>;
164
173
  export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification>;
165
174
  /**
@@ -171,11 +180,11 @@ export type EveryViewNotificationIsFolded = AssertNever<UnfoldedViewNotification
171
180
  type StaleViewArm = Exclude<ViewEvent["method"], MspNotification>;
172
181
  export type NoStaleViewArm = AssertNever<StaleViewArm>;
173
182
  /**
174
- * The same reverse pin for the hand-typed exclusion literal above:
183
+ * The same reverse pin for the hand-typed exclusion literals above:
175
184
  * `Exclude` silently ignores excluder members outside the union, so a
176
- * retired or renamed `initialized` would otherwise compile clean as dead
177
- * vocabulary (the PR #23087 rule, applied to this file's only other
178
- * 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).
179
188
  */
180
189
  type StaleExclusion = Exclude<NonFoldNotification, MspNotification>;
181
190
  export type NoStaleExclusion = AssertNever<StaleExclusion>;
package/dist/src/msp.d.ts CHANGED
@@ -243,7 +243,7 @@ export interface BranchState {
243
243
  }
244
244
 
245
245
  /** A grantable capability name (SS1.4.4). Open: the reserved `rawLog` entry joins this domain as an additive open-enum extension when SS6 un-defers (#13929, Scenario 5 AS-3) — closed would make that a retype. */
246
- export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | (string & {});
246
+ export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | (string & {});
247
247
 
248
248
  /** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
249
249
  export interface ClientCapabilities {
@@ -303,8 +303,22 @@ export interface ContextUsage {
303
303
  windowTokens?: number;
304
304
  }
305
305
 
306
- /** Session running totals of counted-once usage (tdd SS4.6.5). */
306
+ /** Server-computed session cost member of [`CumulativeTokenUsage`] (tdd SS4.6.5, Amendment #41610 FR-41610-2/3). */
307
+ export interface CumulativeCost {
308
+ /** True when at least one leg lacked price data — clients render `(partial)`. */
309
+ partial: boolean;
310
+ /** Estimated USD total, finite and non-negative. */
311
+ usd: number;
312
+ }
313
+
314
+ /** Session running totals of counted-once usage (tdd SS4.6.5). Amendment #41610: the cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate (INV-41610-1). `Copy` was dropped for the `cost` member. */
307
315
  export interface CumulativeTokenUsage {
316
+ /** Cache-read tokens, session total (FR-41610-1): saturating sum of the per-completion splits; an absent split contributes 0. Additive-optional: absent on the wire reads as 0 and zero totals are omitted, so pre-feature bytes decode and re-encode identically. */
317
+ cacheReadTokens?: number;
318
+ /** Cache-write tokens, session total (FR-41610-1). Additive-optional like the read split. */
319
+ cacheWriteTokens?: number;
320
+ /** Server-computed session cost (FR-41610-2): `None` (wire-absent) when no leg is priced — clients omit the row. Additive-optional: absent reads as unpriced. */
321
+ cost?: CumulativeCost;
308
322
  /** Output tokens, session total. */
309
323
  outputTokens: number;
310
324
  /** Counted-once prompt tokens, session total. */
@@ -414,6 +428,52 @@ export interface ErrorResponse {
414
428
  jsonrpc: JsonRpcVersion;
415
429
  }
416
430
 
431
+ /** `feedback/submit` classification (tdd SS3.25): the four TUI classes in camelCase wire spelling. **Closed**: a client-selected param vocabulary (#22785 E2). */
432
+ export type FeedbackClassification = "bug" | "badResult" | "goodResult" | "other";
433
+
434
+ /** `feedback/submit` result `outcome` (tdd SS3.25): how one confirmed submit resolved, mirroring the TUI `FeedbackSubmitOutcome` taxonomy. **Open**: a server-produced result vocabulary (#22785 E2) — an older client reading a newer value it does not know follows the open-enum tolerance rule instead of rejecting it. */
435
+ export type FeedbackSubmitOutcome = "uploaded" | "recorded" | "acceptedWithoutReceipt" | "trackingFailed" | "trackingUncertain" | "dark" | "disabled" | "noCredential" | "authRejected" | "rateLimited" | "failed" | (string & {});
436
+
437
+ /** `feedback/submit` params (tdd SS3.25): mirrors the TUI confirm-time `FeedbackRequest`. The call itself is the explicit confirm. */
438
+ export interface FeedbackSubmitParams {
439
+ /** Consent to attach the session record; honored only for `bug`/`badResult`. `true` with `with_files: false` or a non-`bug`/`badResult` classification is `invalidParams` (F4). Defaults to `false`. */
440
+ attachSessionRecord?: boolean;
441
+ /** The report class (required). */
442
+ classification: FeedbackClassification;
443
+ /** An absolute same-host path to a client-packed bundle, admitted only as a regular file under a size cap. */
444
+ clientArtifactsPath?: string;
445
+ /** The user report text (required; non-empty for `bug`). */
446
+ note: string;
447
+ /** Names the session this call is about (required, F3): the bundle always lands in that session's dir. Names a session this host owns; a client with no session cannot send feedback. */
448
+ sessionId: string;
449
+ /** The files-consent decision (required). */
450
+ withFiles: boolean;
451
+ }
452
+
453
+ /** `feedback/submit` result (tdd SS3.25): the upload receipt. */
454
+ export interface FeedbackSubmitResult {
455
+ /** The host-local absolute path of the always-written local bundle. */
456
+ bundlePath: string;
457
+ /** The failure cause on the `failed`, `acceptedWithoutReceipt`, `trackingFailed`, and `trackingUncertain` arms. */
458
+ cause?: string;
459
+ /** The consent-vs-reality local-tracing note, kept for display. */
460
+ localTracingNote?: string;
461
+ /** How the submit resolved. */
462
+ outcome: FeedbackSubmitOutcome;
463
+ /** The effective retry delay in milliseconds, on `rateLimited`. */
464
+ retryAfterMs?: number;
465
+ /** The consent-vs-reality session note, kept for display. */
466
+ sessionNote?: string;
467
+ /** Whether the consented session record rode at all. */
468
+ sessionRecordAttached: boolean;
469
+ /** Whether the consented session record rode shortened to fit. */
470
+ sessionRecordTruncated: boolean;
471
+ /** The internal receipt-Task id once that Task succeeds. */
472
+ taskId?: string;
473
+ /** The intake's accept id — always present on the `uploaded` arm, optional on `trackingFailed`/`trackingUncertain`; never fabricated on `recorded`. */
474
+ uploadId?: string;
475
+ }
476
+
417
477
  /** Where a fork cuts the source history (tdd SS2.5.3). Turn ids are used instead of counts because ids stay stable across compaction and concurrent appends while indices do not. */
418
478
  export interface ForkCutPoint {
419
479
  /** The last completed turn to copy, inclusive. Naming an in-progress or unknown turn fails `forkBoundaryInvalid`. */
@@ -598,7 +658,7 @@ export interface Item {
598
658
  message?: string;
599
659
  /** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
600
660
  modelVisibleContent?: ModelVisibleContent[];
601
- /** `subagent`: objective as spawned. */
661
+ /** `subagent`: objective as spawned, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4, ADR 35691 D9); a cut sets `truncated`. The durable record stays verbatim. */
602
662
  objective?: string;
603
663
  /** `compaction`: terminal only — folds installed/fallback status. */
604
664
  outcome?: CompactionOutcome;
@@ -654,7 +714,7 @@ export interface Item {
654
714
  trigger?: CompactionTrigger;
655
715
  /** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
656
716
  triggerSource?: string;
657
- /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`); the durable full text remains in the log (tdd SS4.5.4). */
717
+ /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), or cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`). On a `subagent` item the flag is item-level and never cleared: once any of those four is cut, every later update keeps it, even when `result.text` arrives whole (ADR 35691 D9). The durable full text remains in the log (tdd SS4.5.4). */
658
718
  truncated?: boolean;
659
719
  /** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` only for `userShell` — the one kind outside a turn (tdd SS4.5.6). */
660
720
  turnId?: string | null;
@@ -776,6 +836,8 @@ export interface ModelCatalogEntry {
776
836
  contextLimit: number | null;
777
837
  /** Cost block; `null` when the catalog source declared nothing. */
778
838
  cost: ModelCost | null;
839
+ /** The row's catalog default. Optional only for decoding older hosts; a present value is never null and is always a member of `variants`. Absent under `"unknown"` (ADR 33400 D2). */
840
+ defaultReasoningEffort?: ReasoningEffort;
779
841
  /** Description; `null` when the catalog source declared nothing. */
780
842
  description: string | null;
781
843
  /** Presentation label. */
@@ -792,8 +854,12 @@ export interface ModelCatalogEntry {
792
854
  profileId: string | null;
793
855
  /** Provider routing. */
794
856
  providerId: string;
857
+ /** Described selectable tiers, a same-order subset of `variants`. Optional only for decoding older hosts; a present value is never null. Absent under `"unknown"` (ADR 33400 D2). */
858
+ reasoningEffortVariants?: ModelDescribedReasoningEffort[];
795
859
  /** Release date; `null` when the catalog source declared nothing. */
796
860
  releaseDate: string | null;
861
+ /** Complete ordered selectable efforts. Optional only for decoding older hosts; a present value is never null. Current hosts always send it. */
862
+ variants?: ModelReasoningEffortVariants;
797
863
  }
798
864
 
799
865
  /** Where a model catalog came from (tdd SS3.10). **Open**: an unrecognized value is an unknown source, not an error. */
@@ -814,6 +880,14 @@ export interface ModelCost {
814
880
  output: string;
815
881
  }
816
882
 
883
+ /** One described reasoning-effort tier of a `model/list` row (tdd SS3.10, ADR 33400 D2): a selectable tier plus the catalog's display string for it when declared. */
884
+ export interface ModelDescribedReasoningEffort {
885
+ /** The catalog's per-tier display string; absent when the catalog declared none. Optional only for decoding; a present value is never null. */
886
+ description?: string;
887
+ /** The tier, in the closed D-024 vocabulary. */
888
+ tier: ReasoningEffort;
889
+ }
890
+
817
891
  /** `model/list` params (tdd SS3.10): the discovery half of the model-picker gesture. **A query, not a command** — no `commandId`, no durable intake record, no view event. */
818
892
  export interface ModelListParams {
819
893
  /** When present, the row matching that session's effective model is flagged `isActive`. When absent, no row is active — a client may list before it has a session (tdd SS3.10). */
@@ -832,6 +906,9 @@ export interface ModelListResult {
832
906
  source: ModelCatalogSource;
833
907
  }
834
908
 
909
+ /** A complete ordered effort set, or an explicit unknown capability. */
910
+ export type ModelReasoningEffortVariants = ReasoningEffort[] | UnknownModelReasoningEffortVariants;
911
+
835
912
  /** A model selection (tdd SS3.8). Empty strings are normalized to absent. */
836
913
  export interface ModelSelection {
837
914
  /** Presentation label. */
@@ -1079,13 +1156,26 @@ export interface SessionBranchChangedParams {
1079
1156
  workspaceRoot: string;
1080
1157
  }
1081
1158
 
1159
+ /** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the two orderly unload paths do, and both write the durable `SessionEnd` record first. */
1160
+ export interface SessionClosedParams {
1161
+ /** Which orderly unload path fired. */
1162
+ reason: SessionClosedReason;
1163
+ /** The unloaded session. */
1164
+ sessionId: string;
1165
+ /** The final view head; a client that stores it can later `session/resume {cursor}` and receive exactly the (empty) suffix. An **opaque** view cursor: clients relay it, never parse it (tdd SS4.1). **Required-nullable**: the producers always write the member and write `null` when the final fold failed at unload (`session/idle.rs`, `serve/shutdown.rs`; PR #16779 review) — the host defines no cursor values of its own and never invents one, and the subscriber still learns the session closed. */
1166
+ viewCursor: string | null;
1167
+ }
1168
+
1169
+ /** The SS2.6.2 closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the #33065 menu-B pick (PR #33201 comment 5638727249, recorded in the enrollment decision record), which settles that this notification reason enum publishes open rather than resting on E2's result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all. */
1170
+ export type SessionClosedReason = "idle" | "hostShutdown" | (string & {});
1171
+
1082
1172
  /** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
1083
1173
  export interface SessionCompactParams {
1084
1174
  /** The SS3.1.1 idempotency handle (UUIDv7). */
1085
1175
  commandId: string;
1086
1176
  /** The target session. */
1087
1177
  sessionId: string;
1088
- /** The run whose context to compact. Omit and the server resolves the session's current/latest run; a session with no resolvable run rejects with `commandRejected` reason `missing_run` (tdd SS3.7). */
1178
+ /** The run whose context to compact. Omit and the server resolves the session's current/latest run; a session with no resolvable run rejects with `commandRejected` reason `missing_run` (tdd SS3.7). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
1089
1179
  turnId?: string;
1090
1180
  }
1091
1181
 
@@ -1121,6 +1211,37 @@ export interface SessionContextUsageParams {
1121
1211
  windowTokens?: number;
1122
1212
  }
1123
1213
 
1214
+ /** The persisted deletion terminal, separate from admission (SS3.24). The shared schema is one object. Actual failed producers send both optional fields; completed producers omit both. Clients enforce those obligations before interpreting a known outcome. Preserve unknown strings without treating them as successful completion. */
1215
+ export interface SessionDeleteCompletedParams {
1216
+ /** Idempotency key of the original deletion command. */
1217
+ commandId: string;
1218
+ /** Deletion result; an unknown value leaves the command pending. */
1219
+ outcome: SessionDeleteOutcome;
1220
+ /** Erasure evidence for a failed result; omitted for a completed result. */
1221
+ physicalChange?: SessionDeletePhysicalChange;
1222
+ /** Required for a failed result and omitted for a completed result. */
1223
+ reason?: SessionDeleteFailureReason;
1224
+ /** Session named by the original deletion command. */
1225
+ sessionId: string;
1226
+ }
1227
+
1228
+ /** Stable deletion-failure vocabulary known to this version (SS3.24). The server emits only these values. Future reason strings remain an open result vocabulary; consumers cannot infer completion from any reason. */
1229
+ export type SessionDeleteFailureReason = "ownershipUnavailable" | "sharedSource" | "writerBusy" | "unsafeSource" | "sourceChanged" | "quiescenceFailed" | "cancelled" | "storageFailure" | "cleanupIncomplete" | "unsupportedLayout" | (string & {});
1230
+
1231
+ /** Known terminal outcomes. A future outcome cannot authorize success or exit. */
1232
+ export type SessionDeleteOutcome = "completed" | "failed" | (string & {});
1233
+
1234
+ /** `session/delete` params. The host validates a non-nil legacy-valid UUID target and a UUID-v7 command identity before admission. Unknown members are ignored and do not enter the normalized command identity (SS1.5.4). */
1235
+ export interface SessionDeleteParams {
1236
+ /** UUID-v7 idempotency key for this deletion command. */
1237
+ commandId: string;
1238
+ /** Non-nil UUID of the session selected for deletion. */
1239
+ sessionId: string;
1240
+ }
1241
+
1242
+ /** The failed attempt's immutable snapshot of persisted physical evidence. `possible` is recorded before a detach/unlink, `confirmed` after a proved owned effect. A failure never resets that evidence merely because the session path is absent. Unknown strings remain representable; consumers must treat them conservatively as `possible`. */
1243
+ export type SessionDeletePhysicalChange = "none" | "possible" | "confirmed" | (string & {});
1244
+
1124
1245
  /** Whether this host writes its sessions to disk (SS1.4.1, SS2.13). A property of the host process, fixed at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: the unrepresented degraded state (#14401) has candidate resolutions that add a third value here, so closed would make that a breaking change. */
1125
1246
  export type SessionDurability = "durable" | "ephemeral" | (string & {});
1126
1247
 
@@ -1172,16 +1293,34 @@ export interface SessionHistory {
1172
1293
  snapshot: ViewSnapshot | null;
1173
1294
  }
1174
1295
 
1296
+ /** Exact branch selection (#42035 FR-42035-2). */
1297
+ export interface SessionListBranchFilter {
1298
+ /** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
1299
+ anyOf: (string | null)[];
1300
+ }
1301
+
1175
1302
  /** `session/listChanged` params (#33084, ADR 33084 D3): one changed row of the `session/list` shape — the full SS2.4 Session object as the answering host's list face serves it at emission (the ADR 29243 live-overlaid row), a replace, never a delta. Emitted only on connections that negotiated the `sessionListStream` capability at `initialize` (ADR 33084 D2); row birth stays on `session/started`, unload pairs with `session/closed`. */
1176
1303
  export interface SessionListChangedParams {
1177
1304
  /** The served list row for the changed session. */
1178
1305
  session: Session;
1179
1306
  }
1180
1307
 
1308
+ /** The `session/list` filter (#42035, spec 207 FR-42035-2..5). Members are ANDed with each other and with the top-level `workspaceRoot` and `updatedAfter`; values inside each `anyOf` are ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orders `text.fields` `name` then `title`. */
1309
+ export interface SessionListFilter {
1310
+ /** Only sessions whose branch is one of these. */
1311
+ branch?: SessionListBranchFilter;
1312
+ /** Only sessions whose ID is one of these. */
1313
+ sessionId?: SessionListSessionIdFilter;
1314
+ /** Only sessions whose served name or title matches these token prefixes. */
1315
+ text?: SessionListTextFilter;
1316
+ }
1317
+
1181
1318
  /** `session/list` params (tdd SS2.5.4). Read-only; never touches leases. */
1182
1319
  export interface SessionListParams {
1183
1320
  /** Opaque page cursor from a prior result. Page cursors are a distinct opaque-string family from view cursors and stream cursors, valid only for re-issuing the same listing (tdd SS2.5.4). Omitted and explicit `null` both mean "first page" (#23468). */
1184
1321
  cursor?: string | null;
1322
+ /** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
1323
+ filter?: SessionListFilter;
1185
1324
  /** Page size; default 50, max 200 — the cap is published under #22785 E6c (owner-ruled 2026-08-26). Maximum 200. */
1186
1325
  limit?: number;
1187
1326
  /** Only sessions with log activity after this RFC3339 instant. */
@@ -1192,12 +1331,33 @@ export interface SessionListParams {
1192
1331
 
1193
1332
  /** `session/list` result (tdd SS2.5.4). Ordering is `updatedAt` descending. */
1194
1333
  export interface SessionListResult {
1334
+ /** The canonical filter the server applied, present exactly when the request carried `filter` (#42035, spec 207 FR-42035-1). The probe is per-predicate PRESENCE (ADR 42035 D6): a client that requires filtering checks that every predicate it sent comes back as a member here, and treats a missing member as unsupported. Value equality is the wrong test — canonicalization trims, lowercases, NFC-normalizes, dedupes and sorts, so the echoed values often differ from the sent ones on a correctly filtered page. */
1335
+ appliedFilter?: SessionListFilter;
1195
1336
  /** The next page's cursor; `null` on the last page. */
1196
1337
  nextCursor: string | null;
1197
1338
  /** The page of stored sessions. */
1198
1339
  sessions: Session[];
1199
1340
  }
1200
1341
 
1342
+ /** Exact session-ID selection (#42035 FR-42035-2). */
1343
+ export interface SessionListSessionIdFilter {
1344
+ /** 1–200 session UUIDs, counted before deduplication. */
1345
+ anyOf: string[];
1346
+ }
1347
+
1348
+ /** A served session field `session/list` text search reads (#42035 FR-42035-3). The client selects it, so the set is closed. */
1349
+ export type SessionListTextField = "name" | "title";
1350
+
1351
+ /** Name/title token-prefix search (#42035 FR-42035-3/FR-42035-4). Each term is trimmed, lowercased with ordinary Unicode lowercase, then NFC- normalized, and matches the beginning of an alphanumeric token, accent-sensitively (`check` matches `Checkout`; `eck` does not). NFC means a decomposed and a precomposed spelling of one term are the same term, and the echo returns the composed form. Matching never reorders rows. */
1352
+ export interface SessionListTextFilter {
1353
+ /** Every term must match at least one selected field. */
1354
+ allOf?: string[];
1355
+ /** At least one term must match a selected field. `allOf` plus `anyOf` carry 1–16 terms in total, each 1–128 UTF-8 bytes in its canonical form (trimmed, lowercased, NFC) — the bytes `appliedFilter` echoes. Lowercasing and NFC can both lengthen a term, so a term inside the bound raw may still exceed it canonically. */
1356
+ anyOf?: string[];
1357
+ /** The 1–2 unique served fields searched. */
1358
+ fields: SessionListTextField[];
1359
+ }
1360
+
1201
1361
  /** One native MCP server supplied at session construction (ADR 32760 D1). **Closed union** (#33295 owner ruling A1, extending D-033/D-050 to `oneOf`): a validator MUST reject an undeclared `transport` arm — the server fails `session/start` decode on an unknown transport, and a future transport arrives as an explicit schema addition. */
1202
1362
  export type SessionMcpServerConfig = { /** Ordered child arguments. */ args?: string[]; /** Executable name or path. Configuration diagnostics never echo it. */ command: string; /** Explicit child environment additions. */ env?: Record<string, string>; /** Stdio framing mode; defaults to automatic detection. */ framing?: SessionMcpStdioFraming; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "stdio"; } | { /** Explicit request headers. */ headers?: Record<string, string>; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "streamableHttp"; /** HTTP(S) endpoint. Configuration diagnostics never echo it. */ url: string; };
1203
1363
 
@@ -1409,6 +1569,8 @@ export interface SessionStartParams {
1409
1569
  sessionId?: string;
1410
1570
  /** Absolute path, folded into the first metadata record. */
1411
1571
  workspaceRoot?: string;
1572
+ /** The session's initial runtime workspace-root set: ordered absolute canonical existing directory paths; the first root is the CWD and plays the primary-root role; every root receives the ADR 11237 `:workspace_roots` rules; extra roots grant no Project Trust. When `workspaceRoot` is also present the two must name the same folder, compared on canonical forms (the raw `workspaceRoot` is canonicalized first; ADR 37313 D9), or the request is invalid params, and so is explicit `null` (the D-049 null-tolerant set is closed and excludes this member). Omitted preserves single-root behavior (tdd SS2.5.1, ADR 37313, #37313). */
1573
+ workspaceRoots?: string[];
1412
1574
  }
1413
1575
 
1414
1576
  /** `session/start` result (tdd SS2.5.1). */
@@ -1419,6 +1581,12 @@ export interface SessionStartResult {
1419
1581
  viewCursor: string;
1420
1582
  }
1421
1583
 
1584
+ /** `session/started` params (tdd SS2.6.1; enrolled by #33065): a session became newly loaded on this host via `session/start` or `session/fork` (never `session/resume` — Appendix C, OQ-F), broadcast to every initialized connection. The one member is the same `$defs/Session` object the `session/start`/`session/fork` results carry, so the broadcast and the result describe one fact through one type — the host builds the broadcast payload as a `$defs/Session` — the fresh-start arm reuses the result's `session` member, the start-replay arm builds the live attach snapshot — and the emission is parity-gated against this type at the producer (`session-server` prod-assembly capture) and over the committed transcript corpus (conformance `session_lifecycle_enrollment`). */
1585
+ export interface SessionStartedParams {
1586
+ /** The newly loaded session, as of the start/fork fold. */
1587
+ session: Session;
1588
+ }
1589
+
1422
1590
  /** A session's load state (tdd SS2.4). */
1423
1591
  export type SessionStatus = "notLoaded" | "idle" | "running" | (string & {});
1424
1592
 
@@ -1641,9 +1809,9 @@ export interface SubagentResult {
1641
1809
  evidenceRefs: string[];
1642
1810
  /** Structured result data, verbatim, when present. */
1643
1811
  structuredData?: Record<string, unknown>;
1644
- /** Bounded result summary (<=512 chars, runtime-enforced). */
1812
+ /** Result summary, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4 and SS4.5.7, ADR 35691 D9); a cut sets the item's `truncated`. The durable record stays verbatim. */
1645
1813
  summary: string;
1646
- /** Result text (<=32 KiB), when present. */
1814
+ /** Result text, when present, bounded on the wire at the same 64 KiB budget (ADR 35691 D9); a cut sets the item's `truncated`. */
1647
1815
  text?: string;
1648
1816
  }
1649
1817
 
@@ -1796,7 +1964,7 @@ export interface TurnCancelParams {
1796
1964
  commandId: string;
1797
1965
  /** The target session. */
1798
1966
  sessionId: string;
1799
- /** The exact turn to cancel; omit to target the current foreground turn. */
1967
+ /** The exact turn to cancel; omit to target the current foreground turn. Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
1800
1968
  turnId?: string;
1801
1969
  }
1802
1970
 
@@ -1878,7 +2046,7 @@ export interface TurnInterruptParams {
1878
2046
  retract?: boolean;
1879
2047
  /** The target session. */
1880
2048
  sessionId: string;
1881
- /** The exact turn to interrupt. Omit to target the session's current foreground turn, resolved at admission; prefer passing the explicit id when you have one (tdd SS3.4). */
2049
+ /** The exact turn to interrupt. Omit to target the session's current foreground turn, resolved at admission; prefer passing the explicit id when you have one (tdd SS3.4). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
1882
2050
  turnId?: string;
1883
2051
  }
1884
2052
 
@@ -1953,6 +2121,8 @@ export interface TurnStartParams {
1953
2121
  reasoningEffort?: ReasoningEffort;
1954
2122
  /** The target session. */
1955
2123
  sessionId: string;
2124
+ /** A sticky REPLACEMENT of the session's runtime workspace-root set, binding at this turn's launch and persisting for subsequent turns until replaced again — unlike `reasoningEffort`, which is this-turn-only. Same shape and validation as `session/start.workspaceRoots`; invalid params on an explicit `ifBusy: "steer"` submit and so is explicit `null` (the D-049 null-tolerant set is closed); omitted means "unchanged", never "reset" (tdd SS3.2, ADR 37313 D3, #37313). */
2125
+ workspaceRoots?: string[];
1956
2126
  }
1957
2127
 
1958
2128
  /** `turn/start` result (tdd SS3.2). */
@@ -1987,7 +2157,7 @@ export interface TurnStartedParams {
1987
2157
  export interface TurnSteerParams {
1988
2158
  /** The SS3.1.1 idempotency handle (UUIDv7). */
1989
2159
  commandId: string;
1990
- /** The turn you believe is running. Closes the race where the turn completes or is replaced between your read and your steer: input meant for turn A can never leak into turn B (tdd SS3.3). */
2160
+ /** The turn you believe is running. Closes the race where the turn completes or is replaced between your read and your steer: input meant for turn A can never leak into turn B (tdd SS3.3). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`; an id that is not the running turn is refused. */
1991
2161
  expectedTurnId: string;
1992
2162
  /** Same content parts as `turn/start`. */
1993
2163
  input: TurnInputPart[];
@@ -2016,7 +2186,7 @@ export interface TurnUnqueueParams {
2016
2186
  commandId: string;
2017
2187
  /** The target session. */
2018
2188
  sessionId: string;
2019
- /** The queued turn to reclaim, exactly as the queueing `turn/start`'s ack minted it and as snapshot `queuedTurns` lists it. Required, and never "whichever is newest" (tdd SS3.6). */
2189
+ /** The queued turn to reclaim, exactly as the queueing `turn/start`'s ack minted it and as snapshot `queuedTurns` lists it. Required, and never "whichever is newest" (tdd SS3.6). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
2020
2190
  turnId: string;
2021
2191
  }
2022
2192
 
@@ -2062,6 +2232,9 @@ export interface UnframedViewNotificationParams {
2062
2232
  viewCursor: string;
2063
2233
  }
2064
2234
 
2235
+ /** The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding. */
2236
+ export type UnknownModelReasoningEffortVariants = "unknown";
2237
+
2065
2238
  /** `usage/read` result: `{usage?}` — omitted, never `null`, when the host has observed nothing (ADR 32563 D2: truthful absence, no "nothing observed" error). */
2066
2239
  export interface UsageReadResult {
2067
2240
  /** The last-observed subscription usage window, when one exists. */
@@ -2354,9 +2527,9 @@ export interface WorkflowControlResult {
2354
2527
  }
2355
2528
 
2356
2529
  /** Every wire method in this schema (SS1.9 index). */
2357
- export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/list" | "session/read" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "usage/read";
2530
+ export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/list" | "session/read" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/delete" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "usage/read" | "feedback/submit";
2358
2531
  /** Every wire notification in this schema (SS1.9 index). */
2359
- export type MspNotification = "initialized" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
2532
+ export type MspNotification = "initialized" | "session/started" | "session/closed" | "session/deleteCompleted" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
2360
2533
  /** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
2361
2534
  export type MspServerRequest = "approval/request" | "userInput/request";
2362
2535
  /** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muse-code/sdk",
3
- "version": "1.3.0",
3
+ "version": "1.4.2",
4
4
  "description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/meta-models/muse-code-sdk",