@muse-code/sdk 1.4.6 → 1.4.8

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.
@@ -60,7 +60,7 @@ const START_FORWARDED = [
60
60
  * Every `ResumeParams` member `resumeSession` forwards. `config` has the same
61
61
  * temporary capability-check boundary as the start facade above.
62
62
  */
63
- const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history"];
63
+ const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "permissionProfile"];
64
64
  /**
65
65
  * The committed profile id a session snapshot claims, or null when the
66
66
  * snapshot is silent (the stable bundle strips the member; absent and null
@@ -340,6 +340,8 @@ export class MuseClient {
340
340
  params.excludeItems = options.excludeItems;
341
341
  if (options.history != null)
342
342
  params.history = options.history;
343
+ if (options.permissionProfile != null)
344
+ params.permissionProfile = options.permissionProfile;
343
345
  return this.#open("session/resume", params, (raw) => ({
344
346
  result: raw,
345
347
  verb: "session/resume",
@@ -277,6 +277,7 @@ export class Session {
277
277
  case "view/gap":
278
278
  case "turn/retracted": // the turn still reaches its own terminal
279
279
  case "turn/retryScheduled": // non-terminal by contract (SS4.5.1)
280
+ case "turn/modelRetryScheduled": // non-terminal by contract (SS4.5.1)
280
281
  case "turn/foregroundCompleted": // non-terminal by contract (SS4.5.12)
281
282
  case "approval/resolved":
282
283
  case "userInput/requested":
@@ -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:eae467ab60cb9a5d5af4de616830f065e59375c987fd59269c8cc33ed2a1137f";
16
+ export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:4e3200c3c9dc0cd7919d11022630d43f9bc1c5cdda375381e90b0183b5665069";
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:eae467ab60cb9a5d5af4de616830f065e59375c987fd59269c8cc33ed2a1137f";
16
+ export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:4e3200c3c9dc0cd7919d11022630d43f9bc1c5cdda375381e90b0183b5665069";
17
17
  /**
18
18
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
19
  *
@@ -13,8 +13,8 @@
13
13
  * are neither an item nor a state family:
14
14
  *
15
15
  * - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
16
- * `turn/unqueued`, and the non-terminal `turn/retryScheduled` and
17
- * `turn/foregroundCompleted`;
16
+ * `turn/unqueued`, and the non-terminal `turn/retryScheduled`,
17
+ * `turn/modelRetryScheduled`, and `turn/foregroundCompleted`;
18
18
  * - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
19
19
  * sets and their first durable terminal. The decision flow (choosing and
20
20
  * sending a resolution) is the facade's, not the fold's;
@@ -27,7 +27,7 @@
27
27
  * unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
28
28
  * displaces the first durable one.
29
29
  */
30
- import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, MspNotification, SessionApprovalModeChangedParams, SessionBranchChangedParams, SessionContextUsageParams, SessionGoalChangedParams, SessionModelChangedParams, SessionModelRouteUnservedParams, SessionNameChangedParams, SessionReasoningEffortChangedParams, SessionTodoListChangedParams, SessionTokenUsageParams, TurnCompletedParams, TurnError, TurnForegroundCompletedParams, TurnRetractedParams, TurnRetryScheduledParams, TurnStartedParams, TurnTerminal, TurnUnqueuedParams, UserInputRequestParams, UserInputSettledParams, ViewGapParams } from "../msp.js";
30
+ import type { ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item, ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, 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
31
  import type { DeltaApplyOutcome, ItemApplyOutcome, TerminalUnknownItemAnnotation } from "./item-store.js";
32
32
  import type { StateApplyOutcome, StateValue } from "./state-store.js";
33
33
  /** The session-state families, each keyed in the store by its method name. */
@@ -60,6 +60,9 @@ export type ViewEvent = {
60
60
  } | {
61
61
  readonly method: "turn/retryScheduled";
62
62
  readonly params: TurnRetryScheduledParams;
63
+ } | {
64
+ readonly method: "turn/modelRetryScheduled";
65
+ readonly params: TurnModelRetryScheduledParams;
63
66
  } | {
64
67
  readonly method: "turn/unqueued";
65
68
  readonly params: TurnUnqueuedParams;
@@ -218,7 +221,7 @@ export type SessionStateMethod = ViewEvent["method"] & `session/${string}`;
218
221
  * and could never match exhaustively. A future arm that starts dropping
219
222
  * widens this deliberately (PR #23087 review round).
220
223
  */
221
- export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/foregroundCompleted" | "turn/retryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested";
224
+ export type StaleDroppableMethod = "turn/started" | "turn/completed" | "turn/foregroundCompleted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "approval/requested" | "approval/updated" | "userInput/requested";
222
225
  /**
223
226
  * The `NoStaleViewArm` sibling for the union above: these are hand-typed
224
227
  * literals, so without this pin a typo'd or later-retired member compiles
@@ -241,6 +244,13 @@ export interface TurnEntry {
241
244
  readonly error?: TurnError;
242
245
  /** The latest scheduled model retry; non-terminal (tdd SS4.5.1, D-026). */
243
246
  readonly retryScheduled?: TurnRetryScheduledParams;
247
+ /**
248
+ * The latest scheduled provider-backoff retry; non-terminal
249
+ * (tdd SS4.5.1, ADR 50047 D1/D2). The model-attempt twin of
250
+ * `retryScheduled`: a failing model attempt's backoff is waiting out
251
+ * its delay. Clears on the turn's terminal.
252
+ */
253
+ readonly modelRetryScheduled?: TurnModelRetryScheduledParams;
244
254
  /**
245
255
  * The latest foreground-completed notice; non-terminal (tdd SS4.5.12).
246
256
  * Tells a renderer the answer is done while `blockingAgents` hold the
@@ -13,8 +13,8 @@
13
13
  * are neither an item nor a state family:
14
14
  *
15
15
  * - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
16
- * `turn/unqueued`, and the non-terminal `turn/retryScheduled` and
17
- * `turn/foregroundCompleted`;
16
+ * `turn/unqueued`, and the non-terminal `turn/retryScheduled`,
17
+ * `turn/modelRetryScheduled`, and `turn/foregroundCompleted`;
18
18
  * - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
19
19
  * sets and their first durable terminal. The decision flow (choosing and
20
20
  * sending a resolution) is the facade's, not the fold's;
@@ -163,6 +163,8 @@ export class SessionFold {
163
163
  return this.#turnUnqueued(typed.params);
164
164
  case "turn/retryScheduled":
165
165
  return this.#turnRetryScheduled(typed.params);
166
+ case "turn/modelRetryScheduled":
167
+ return this.#turnModelRetryScheduled(typed.params);
166
168
  case "turn/foregroundCompleted":
167
169
  return this.#turnForegroundCompleted(typed.params);
168
170
  case "approval/requested":
@@ -268,6 +270,9 @@ export class SessionFold {
268
270
  // turn's next event — which a completion is (tdd SS4.5.1). Leaving it set
269
271
  // makes a renderer show the countdown on a finished turn.
270
272
  turn.retryScheduled = undefined;
273
+ // Same for the provider-backoff hint: a finished turn is not waiting
274
+ // out a backoff (tdd SS4.5.1).
275
+ turn.modelRetryScheduled = undefined;
271
276
  // Same for the foreground hint: a finished turn is not background-waiting
272
277
  // (tdd SS4.5.12).
273
278
  turn.foregroundCompleted = undefined;
@@ -313,6 +318,18 @@ export class SessionFold {
313
318
  turn.retryScheduled = params;
314
319
  return { kind: "turn", turnId: params.turnId, state: turn.state };
315
320
  }
321
+ #turnModelRetryScheduled(params) {
322
+ // Non-terminal by contract: it never resolves a turn-wait (tdd SS4.5.1).
323
+ const turn = this.#turnFor(params.turnId);
324
+ // …but it is still a turn frame, so it takes the same redelivery guard
325
+ // as the retry hint: a replayed page must not re-plant the
326
+ // provider-backoff hint on a turn that already left `running`.
327
+ if (turn.state !== "running") {
328
+ return { kind: "ignoredStaleFrame", method: "turn/modelRetryScheduled", id: params.turnId };
329
+ }
330
+ turn.modelRetryScheduled = params;
331
+ return { kind: "turn", turnId: params.turnId, state: turn.state };
332
+ }
316
333
  #turnForegroundCompleted(params) {
317
334
  // Non-terminal by contract: it never resolves a turn-wait (tdd SS4.5.12).
318
335
  const turn = this.#turnFor(params.turnId);
@@ -345,6 +362,9 @@ export class SessionFold {
345
362
  ...(turn.terminal !== undefined ? { terminal: turn.terminal } : {}),
346
363
  ...(turn.error !== undefined ? { error: turn.error } : {}),
347
364
  ...(turn.retryScheduled !== undefined ? { retryScheduled: turn.retryScheduled } : {}),
365
+ ...(turn.modelRetryScheduled !== undefined
366
+ ? { modelRetryScheduled: turn.modelRetryScheduled }
367
+ : {}),
348
368
  ...(turn.foregroundCompleted !== undefined
349
369
  ? { foregroundCompleted: turn.foregroundCompleted }
350
370
  : {}),
package/dist/src/msp.d.ts CHANGED
@@ -245,7 +245,7 @@ export interface BranchState {
245
245
  }
246
246
 
247
247
  /** 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. */
248
- export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | (string & {});
248
+ export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | "computerUseSetup" | "computerUseHostSetup" | "sessionRename" | (string & {});
249
249
 
250
250
  /** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
251
251
  export interface ClientCapabilities {
@@ -320,6 +320,36 @@ export type CompactionOutcome = "compacted" | "noop" | "failed" | "cancelled" |
320
320
  /** What initiated a compaction (tdd SS4.5.10). Open. */
321
321
  export type CompactionTrigger = "manual" | "auto" | (string & {});
322
322
 
323
+ /** One row of the Settings apps list. */
324
+ export interface ComputerUseApp {
325
+ /** The app's bundle ID: the stored key. */
326
+ bundleId: string;
327
+ /** The choice as it applies: a block wins over a grant. */
328
+ choice: ComputerUseAppChoice;
329
+ /** When Computer Use last showed an approval card for the app, RFC3339 UTC; absent when it never has. */
330
+ lastAskedAt?: string;
331
+ /** Settings can't change this row; its choice is `blocked`. Omitted means false. */
332
+ locked?: boolean;
333
+ /** Why the row is locked, when it is. */
334
+ lockedBy?: ComputerUseAppLock;
335
+ /** The name the approval card shows for it, else the name stored with its grant or its last card; absent when there is none. */
336
+ name?: string;
337
+ }
338
+
339
+ /** A per-app choice. **Open**, like `ComputerUseChoice`. */
340
+ export type ComputerUseAppChoice = "ask" | "alwaysAllow" | "blocked" | (string & {});
341
+
342
+ /** Why Settings can't change a row. **Open**. */
343
+ export type ComputerUseAppLock = "builtIn" | "file" | (string & {});
344
+
345
+ /** One per-app choice to set in `computerUseSettings/update`. */
346
+ export interface ComputerUseAppPatch {
347
+ /** The app's bundle ID. */
348
+ bundleId: string;
349
+ /** `ask` removes the app's grant and the user's block; `alwaysAllow` saves a grant and removes the user's block; `blocked` adds the user's block and removes the grant. */
350
+ choice: ComputerUseAppChoice;
351
+ }
352
+
323
353
  /** One row of the Settings blocked-apps list. */
324
354
  export interface ComputerUseBlockedApp {
325
355
  /** The app's bundle ID, or the family prefix when `prefix` is true. */
@@ -333,27 +363,43 @@ export interface ComputerUseBlockedApp {
333
363
  /** A capability dropdown's value (ADR 630 D18.4). **Open**: the read result carries it, so an older client tolerates a value it does not know. */
334
364
  export type ComputerUseChoice = "ask" | "alwaysAllow" | (string & {});
335
365
 
366
+ /** One installed or running app, for Settings' app picker. */
367
+ export interface ComputerUseInstalledApp {
368
+ /** The app's bundle ID. */
369
+ bundleId: string;
370
+ /** The name the approval card shows for it. */
371
+ name: string;
372
+ }
373
+
336
374
  /** One macOS permission as setup last saw it. **Open**, like the phase. */
337
375
  export type ComputerUsePermission = "granted" | "missing" | "unknown" | (string & {});
338
376
 
339
377
  /** `computerUseSettings/read` result, also answered by `computerUseSettings/update`. */
340
378
  export interface ComputerUseSettings {
379
+ /** The apps list: apps Computer Use has asked about, most recent first; then the other saved grants, then the user's other blocks; then the locked rows. Each app once. A host that serves the list always answers it, so its absence means an older host. */
380
+ apps?: ComputerUseApp[];
341
381
  /** The user's blocks in the order they were added, then the built-in blocks when `showBuiltIns` asked for them. */
342
382
  blockedApps: ComputerUseBlockedApp[];
343
383
  /** The computer-control dropdown, as it applies: `ask` while the stored blocked-apps list can't be read (ADR 630 D18.4). */
344
384
  computerControl: ComputerUseChoice;
385
+ /** The installed and running apps, sorted by name, when the read asked for `installed`. */
386
+ installedApps?: ComputerUseInstalledApp[];
345
387
  /** The screenshots dropdown, under the same rule. */
346
388
  screenshots: ComputerUseChoice;
347
389
  }
348
390
 
349
391
  /** `computerUseSettings/read` params. */
350
392
  export interface ComputerUseSettingsReadParams {
393
+ /** Also answer `installedApps`, for an app picker. Omitted means false. */
394
+ installed?: boolean;
351
395
  /** Also list the built-in blocks as locked rows (the D18.8 toggle). Omitted means false. */
352
396
  showBuiltIns?: boolean;
353
397
  }
354
398
 
355
399
  /** `computerUseSettings/update` params: a patch. Omitted members are left alone; the whole patch applies or none of it does. */
356
400
  export interface ComputerUseSettingsUpdateParams {
401
+ /** Per-app choices to set. A locked app is refused; so is a bundle ID named twice, or also in `blockApps` or `unblockApps`. */
402
+ apps?: ComputerUseAppPatch[];
357
403
  /** Bundle IDs to add to the user's blocked apps. A built-in block is refused: it is already blocked. */
358
404
  blockApps?: string[];
359
405
  /** The new computer-control dropdown value. */
@@ -366,8 +412,8 @@ export interface ComputerUseSettingsUpdateParams {
366
412
 
367
413
  /** `computerUseSetup/changed` params. */
368
414
  export interface ComputerUseSetupChanged {
369
- /** The session whose setup state changed. */
370
- sessionId: string;
415
+ /** The session whose setup state changed; absent for the host's own setup, which only `computerUseHostSetup` holders receive. */
416
+ sessionId?: string;
371
417
  /** Its new state. */
372
418
  state: ComputerUseSetupState;
373
419
  }
@@ -377,16 +423,16 @@ export type ComputerUseSetupPhase = "dormant" | "inProgress" | "restartRequired"
377
423
 
378
424
  /** `computerUseSetup/read` params. */
379
425
  export interface ComputerUseSetupReadParams {
380
- /** The session whose setup to read. */
381
- sessionId: string;
426
+ /** The session whose setup to read. Omitted reads the host's own setup, which needs the `computerUseHostSetup` grant. */
427
+ sessionId?: string;
382
428
  }
383
429
 
384
430
  /** `computerUseSetup/start` params: a human command. */
385
431
  export interface ComputerUseSetupStartParams {
386
432
  /** The client's id for this command. */
387
433
  commandId: string;
388
- /** The session whose setup to start. */
389
- sessionId: string;
434
+ /** The session whose setup to start. Omitted starts the host's own setup, which needs the `computerUseHostSetup` grant. */
435
+ sessionId?: string;
390
436
  }
391
437
 
392
438
  /** The session's setup state: the result of both methods and the `computerUseSetup/changed` payload's `state`. */
@@ -768,6 +814,10 @@ export interface InitializeResult {
768
814
  platformFamily: PlatformFamily;
769
815
  /** Server operating system. */
770
816
  platformOs: PlatformOs;
817
+ /** Whether this host can enforce the sandbox (ADR 50064-startup-report-sandbox-availability D2/D4). Optional so the addition is additive under SS1.5.4; a v1 host always sends it, and a client reads absent as unknown — the host predates the field, so the client falls back to its own probe rather than inventing an answer. */
818
+ sandboxAvailability?: SandboxAvailability;
819
+ /** Why enforcement is impossible. Sent only when `sandbox_availability` is `unavailable`; a client MUST NOT infer a reason when none is sent. */
820
+ sandboxUnavailableReason?: SandboxUnavailableReason;
771
821
  /** Envelope schema version and stable-surface fingerprint. */
772
822
  schema: SchemaInfo;
773
823
  /** Server identification. */
@@ -810,6 +860,8 @@ export interface Item {
810
860
  commandText?: string;
811
861
  /** `subagent`: camelCased `SubagentControlStatus` (open enum); `status` stays the generic item vocabulary. */
812
862
  controlStatus?: SubagentControlStatus;
863
+ /** `agentMessage`: `true` when the provider stream died mid-reply and the run failed with this partial text committed (ADR 50063 D2) — the wire mark for the gate-off "incomplete response" rule (#13328). Absent otherwise; never cleared once set. */
864
+ cutOff?: boolean;
813
865
  /** `workflow`: the run-level declared-phase label — the last `Phase` detail-row label of the reconciled projection; terminal-only, absent while live (tdd SS4.5.8, #45449). */
814
866
  declaredPhase?: string;
815
867
  /** `subagent`: nesting depth. */
@@ -846,8 +898,14 @@ export interface Item {
846
898
  label?: string;
847
899
  /** `workflow`: the reconciled terminal message, set on completion. */
848
900
  message?: string;
901
+ /** `agentMessage`: the phase the model declared on the commit; see [`MessagePhase`]. */
902
+ messagePhase?: MessagePhase;
849
903
  /** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
850
904
  modelVisibleContent?: ModelVisibleContent[];
905
+ /** `monitorFeed`: the monitor's arm-time description with the durable `"Monitor event: "` summary prefix stripped; model- controlled tool input under the 64 KiB per-surface budget — sanitize before render (ADR 50058-monitor-feed-wire D1/D3). */
906
+ monitorDescription?: string;
907
+ /** `monitorFeed`: the monitor task id — the same value as that monitor's `toolCall` `itemId` (ADR 50058-monitor-feed-wire D1). */
908
+ monitorId?: string;
851
909
  /** `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. */
852
910
  objective?: string;
853
911
  /** `compaction`: terminal only — folds installed/fallback status. */
@@ -930,9 +988,9 @@ export interface Item {
930
988
  trigger?: CompactionTrigger;
931
989
  /** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
932
990
  triggerSource?: string;
933
- /** `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). */
991
+ /** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`), or cut a `monitorFeed` surface (`text`, `fallbackText`, `monitorDescription`) (ADR 50058-monitor-feed-wire D3). 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). */
934
992
  truncated?: boolean;
935
- /** 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). */
993
+ /** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` for the kinds outside a turn: `userShell` always (tdd SS4.5.6), `hookRun` for session-boundary runs, `monitorFeed` always (ADR 50058-monitor-feed-wire D1). */
936
994
  turnId?: string | null;
937
995
  /** `subagent`: **transitive** observed usage — the child and its own descendants; updated in place, absent until first observation; never folded into `session/tokenUsage.cumulative` (tdd SS4.6.5). */
938
996
  usage?: TokenUsage;
@@ -969,7 +1027,7 @@ export interface ItemDeltaParams {
969
1027
  }
970
1028
 
971
1029
  /** The eleven v1 item kinds (tdd SS4.5.2–4.5.13) plus post-v1 kinds (tdd SS4.5.14+). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
972
- export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | (string & {});
1030
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | (string & {});
973
1031
 
974
1032
  /** The `item/readOutput` content encoding (tdd SS4.7.4). Closed: text media is ALWAYS `utf8` and binary media `base64`; a third value would change the client's decode contract. */
975
1033
  export type ItemReadOutputEncoding = "utf8" | "base64";
@@ -1089,6 +1147,9 @@ export interface MessageAttachment {
1089
1147
  width?: number;
1090
1148
  }
1091
1149
 
1150
+ /** `agentMessage.messagePhase` (tdd SS4.5.3, #50254): the phase the model declared on the commit, never inferred from position. Set on the completed item only; absent on `item/started`, which opens before the phase is recorded. Open: a client reads an absent or unknown value on a completed item as `"finalAnswer"` and still decodes the item. Not a turn-done signal; `turn/completed` is. */
1151
+ export type MessagePhase = "commentary" | "finalAnswer" | (string & {});
1152
+
1092
1153
  /** One visible catalog row (tdd SS3.10). Catalog rows marked hidden never reach the wire, so a client cannot select one. */
1093
1154
  export interface ModelCatalogEntry {
1094
1155
  /** Context limit; `null` when the catalog source declared nothing. */
@@ -1577,6 +1638,12 @@ export interface RequestReceipt {
1577
1638
  /** A `turn/retracted` settlement outcome (tdd SS4.5.1, ADR 50074 D1). Open enum (D-033): decode is tolerant — a value outside the list reads as `Accepted` (the event's historical meaning — pre-feature hosts emit it only for accepted retracts), never fails. The bundle keeps enumerating the known values for codegen and docs. */
1578
1639
  export type RetractOutcome = "accepted" | "declined" | (string & {});
1579
1640
 
1641
+ /** Whether this host can enforce the sandbox (ADR 50064-startup-report-sandbox-availability D2/D4). A property of the host process, probed once 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: a future enforcement posture arrives as a new value, read by older clients as unknown. */
1642
+ export type SandboxAvailability = "available" | "unavailable" | (string & {});
1643
+
1644
+ /** Why sandbox enforcement is impossible on this host. Sent only when [`SandboxAvailability`] is `unavailable`; a client MUST NOT infer a reason when none is sent. Open: a future reason arrives as a new value, read by older clients as unknown. */
1645
+ export type SandboxUnavailableReason = "userNamespacesDenied" | "bubblewrapUnavailable" | (string & {});
1646
+
1580
1647
  /** The `schema` pair in [`InitializeResult`] (SS1.4.1, SS1.5.3). `version` is the wire **envelope** schema version — distinct from the session-view `schemaVersion`, the raw-log `schema_version`, and the 0.x/1.0 stability posture, which is not on the wire at all (INV-006a). */
1581
1648
  export interface SchemaInfo {
1582
1649
  /** `sha256:<64 lower hex>` content hash of this server binary's stable-surface bundle (INV-003). A mismatch is a warning condition, not an error (SS1.4.1). */
@@ -1611,6 +1678,8 @@ export interface Session {
1611
1678
  firstUserPrompt?: string;
1612
1679
  /** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
1613
1680
  forkedFrom: ForkProvenance | null;
1681
+ /** The served generated short title (tdd SS2.4/SS2.14.1, #50048; ADR 50048-generated-name D1). **Additive-optional**, **fold-only**: the snapshot fold derives the latest retained generated pair's short title from the log; `session/list` rows never carry it. Omitted when no pair was ever published — absent reads as unpublished, never fabricated, never inferred from the name text. `name` stays the canonical name it always was. */
1682
+ generatedName?: string;
1614
1683
  /** What kind of session this is (spec 42713 FR-001, ADR 42713 D1/D4). **Open enum**, v1 values `"root"` and `"subagent"`; a client treats an unknown value as an unknown-but-present kind and renders it, never rejecting the row. **Additive-optional**: absence asserts nothing — the host could not determine the home shape (FM-001), or the value is not yet available to serve (FM-003). */
1615
1684
  kind?: SessionKind;
1616
1685
  /** Content-activity recency, RFC3339 (tdd SS2.4, ADR 31983 D5). **Additive-optional**: omitted when no content record exists. Never advanced by lifecycle bookkeeping (the resume marker, re-stamps) or a fork's copied seed-replay records, and never precedes `createdAt`. */
@@ -1619,6 +1688,8 @@ export interface Session {
1619
1688
  modelId: string | null;
1620
1689
  /** The durable allocated session name (tdd SS2.4/SS2.14.1, #27598; ADR 27598 D2/D4). **Additive-optional**: present when the serving path holds an allocated name, omitted otherwise — absent is never fabricated. Authoritative and renameable via `session/rename`. */
1621
1690
  name?: string;
1691
+ /** How the served `name` was set (tdd SS2.4/SS2.14.1, #50048; ADR 50048 D1/D2). **Additive-optional**, **fold-only**: the snapshot fold (`session/read`, the resume/start/fork-ack snapshot) derives and carries it from the log; `session/list` rows never carry it. Absent — and any value the client does not recognize — reads as unknown, never fabricated. */
1692
+ nameOrigin?: SessionNameOrigin;
1622
1693
  /** The containing session's id when `kind` is `"subagent"` (FR-002, INV-002) — the id of the TOP-LEVEL session whose home holds this child, which is **not necessarily the session that spawned it**: native-child homes are physical siblings under the outer session's `subagent/` directory, so a subagent spawned by another subagent resolves to the outer session, not to its spawner. A client building a tree from this field gets one level, not a chain. Flat rather than nested: there is exactly one fact to carry, unlike `forkedFrom`'s four-field `ForkProvenance`. **Additive-optional**; a root carries none. */
1623
1694
  parentSessionId?: string;
1624
1695
  /** Absolute path of the session's durable log; non-nullable. Under the ephemeral session profile it is the **empty string**, meaning "no durable log exists" (tdd SS2.13.2) — the one value a client must not hand to a filesystem call. */
@@ -1894,8 +1965,12 @@ export interface SessionModelRouteUnservedParams {
1894
1965
 
1895
1966
  /** `session/nameChanged` params (tdd SS4.6.7, #27598): the fold of ANY durable session-name record — the FIRST-NAMING automatic allocate as well as an accepted `session/rename` (or the same in-process runtime command). Replace-wholesale like every SS4.6 sibling. */
1896
1967
  export interface SessionNameChangedParams {
1968
+ /** The latest retained generated short title (tdd SS2.4/SS4.6.7, #50048; ADR 50048-generated-name D1). **Additive-optional**: carried at generated-pair publication and at settlement when a pair is already published; omitted when no pair was ever published — absent reads as unpublished, never fabricated. `name` stays canonical. */
1969
+ generatedName?: string;
1897
1970
  /** The new canonical name now in effect. */
1898
1971
  name: string;
1972
+ /** How the new name was set (tdd SS2.4/SS4.6.7, #50048; ADR 50048 D1/D2). **Additive-optional**: omitted when the emitting fold cannot prove an origin — absent reads as unknown, never fabricated. */
1973
+ nameOrigin?: SessionNameOrigin;
1899
1974
  /** The owning session. */
1900
1975
  sessionId: string;
1901
1976
  /** The durable records this event folded from. */
@@ -1904,6 +1979,9 @@ export interface SessionNameChangedParams {
1904
1979
  viewCursor: string;
1905
1980
  }
1906
1981
 
1982
+ /** How the served session name was set (tdd SS2.4/SS4.6.7, #50048; ADR 50048 D1). **Open enum** (`x-msp-openness: open`): v1 serves `automatic` and `custom`; a client MUST read absent — and any value it does not recognize — as unknown, never fabricated. Open: a future source such as conversation-generated names (#35260) adds a value here, so closed would make that a breaking change. */
1983
+ export type SessionNameOrigin = "automatic" | "custom" | (string & {});
1984
+
1907
1985
  /** `session/read` params (tdd SS2.5.5): read one stored session **without attaching** — no writer lease, no load, no subscription, no `SessionResumed` record. */
1908
1986
  export interface SessionReadParams {
1909
1987
  /** Metadata-only unless you ask: `false` carries the folded item history. Same name and polarity as `session/resume`/`session/fork`; only the default differs — here it is `true` (tdd SS2.5.5). */
@@ -1972,6 +2050,8 @@ export interface SessionResumeParams {
1972
2050
  excludeItems?: boolean;
1973
2051
  /** History mode preference, default `auto`. A PREFERENCE, not a budget override: when the requested mode does not fit the history budget the server downgrades it and `history.mode` reports what was actually served (tdd SS2.5.2). Ignored when `cursor` or `excludeItems` makes it moot. */
1974
2052
  history?: HistoryPreference;
2053
+ /** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted means today's behavior: restore retained authority only, no override. The host restores first, then applies the pick in the same pre-marker step; a pick that fails admission refuses the resume `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte. Explicit `null` is invalid params (the same closed null-tolerant set as at start). */
2054
+ permissionProfile?: string;
1975
2055
  /** The session to load. */
1976
2056
  sessionId: string;
1977
2057
  }
@@ -2078,7 +2158,7 @@ export interface SessionStartParams {
2078
2158
  config?: SessionConfig;
2079
2159
  /** Initial model; server default when omitted. */
2080
2160
  modelId?: string;
2081
- /** The new session's initial permission profile (amendment 42624 FR-42624-1, ADR 42197 D2): a profile id the host catalog already admits — the rows `permissionProfile/list` serves without `sessionId`. Select, never create. Omitted means today's behavior: the host's configured default under native admission, unchanged. An id the catalog does not carry, or one it serves unavailable, refuses the start `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte, and an ephemeral host refuses any id (`permission_profile_ephemeral_fixed`). `session/resume` and `session/fork` do not admit the member. Explicit `null` is invalid params: the set of members that tolerate `null` is closed and excludes this one, exactly as it excludes `workspaceRoots`. */
2161
+ /** The new session's initial permission profile (amendment 42624 FR-42624-1, ADR 42197 D2): a profile id the host catalog already admits — the rows `permissionProfile/list` serves without `sessionId`. Select, never create. Omitted means today's behavior: the host's configured default under native admission, unchanged. An id the catalog does not carry, or one it serves unavailable, refuses the start `commandRejected` (-32030; `permission_profile_unknown` / `permission_profile_unavailable`) before any durable byte, and an ephemeral host refuses any id (`permission_profile_ephemeral_fixed`). `session/fork` does not admit the member; `session/resume` admits it as the launch pick (FR-42624-1, #50054). Explicit `null` is invalid params: the set of members that tolerate `null` is closed and excludes this one, exactly as it excludes `workspaceRoots`. */
2082
2162
  permissionProfile?: string;
2083
2163
  /** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
2084
2164
  providerId?: string | null;
@@ -2222,6 +2302,8 @@ export interface SkillCatalogEntry {
2222
2302
  selector: string;
2223
2303
  /** Where the skill comes from. */
2224
2304
  source: SkillSource;
2305
+ /** The skill's declared human-readable name (`SKILL.md` `metadata.display-name`), for clients to show where people read the skill's name; absent when the skill declares none (ADR 56597 D2). The palette keeps showing `displayName`. */
2306
+ title?: string;
2225
2307
  }
2226
2308
 
2227
2309
  /** `skill/changed` params (tdd SS3.22.2): the session's user-invocable set changed; clients re-issue `skill/list`. Advisory — the host may coalesce bursts and guarantees no ordering relative to view events (ADR 32471 D3). */
@@ -2812,6 +2894,32 @@ export interface TurnInterruptResult {
2812
2894
  turnId: string;
2813
2895
  }
2814
2896
 
2897
+ /** `turn/modelRetryScheduled` params (tdd SS4.5.1; ADR `50047-model-retry-scheduled-members` D1): a durable model-stream retry-scheduled fact folded — the provider backoff behind one model attempt is observable BEFORE the turn terminates, so a streaming client can render "system words · retrying in Ss · attempt N/M" instead of dead air. Non-terminal: it never resolves a turn-wait. The sibling `turn/retryScheduled` shape at the model layer: same member names and semantics (attempt/nextAttempt/maxAttempts/ retryDelayMs/system/errorKind/httpStatus), minus `reason` — the row's words derive from `errorKind` through the shared gate-off mapping, and the recorded machine message is not user text. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally. `sourceRange` cites the session stream's mirror of the task-lifecycle record (tdd SS4.2). */
2898
+ export interface TurnModelRetryScheduledParams {
2899
+ /** The failed model attempt (producer-normalized, >= 1). */
2900
+ attempt: number;
2901
+ /** The failing model attempt's durable kind, verbatim (ADR 50047 D2) — a plain string: the durable vocabulary is open-ended. */
2902
+ errorKind?: string;
2903
+ /** The failing model attempt's HTTP status (ADR 50047 D2). */
2904
+ httpStatus?: number;
2905
+ /** The model-retry chain bound. */
2906
+ maxAttempts: number;
2907
+ /** The scheduled model attempt (producer contract: attempt < nextAttempt <= maxAttempts; not a schema constraint). */
2908
+ nextAttempt: number;
2909
+ /** The scheduled backoff delay in milliseconds, verbatim from the durable fact. */
2910
+ retryDelayMs: number;
2911
+ /** The owning session. */
2912
+ sessionId: string;
2913
+ /** The durable record this event folded from (the session stream's mirror of the scheduled model task status; `first == last`). */
2914
+ sourceRange: SourceRange;
2915
+ /** The failing model attempt's provider system, verbatim (ADR 50047 D2) — e.g. `"meta"`. Always present from this producer (the durable `system` is a required `String`); optional on the wire so a future omission folds absent instead of failing the frame. */
2916
+ system?: string;
2917
+ /** The running turn whose model attempt is being retried. */
2918
+ turnId: string;
2919
+ /** Opaque, strictly monotonic view cursor (tdd SS4.1). */
2920
+ viewCursor: string;
2921
+ }
2922
+
2815
2923
  /** A turn named by the snapshot's active/queued lists (tdd SS4.9.1). */
2816
2924
  export interface TurnRef {
2817
2925
  /** The `commandId` of the submit that minted it. */
@@ -3371,9 +3479,9 @@ export interface WorkflowTokenBudget {
3371
3479
  }
3372
3480
 
3373
3481
  /** Every wire method in this schema (SS1.9 index). */
3374
- 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" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start";
3482
+ 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" | "session/sideChat" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "skill/setActivation" | "skill/import" | "hook/list" | "plugin/list" | "plugin/install" | "plugin/marketplaceAdd" | "plugin/marketplaceUpdate" | "plugin/marketplaceRemove" | "task/background" | "task/stop" | "task/stopAll" | "task/list" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "workflow/resume" | "media/upload" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "userInput/interrupt" | "usage/read" | "feedback/submit" | "recap/request" | "recap/cancel" | "computerUseSettings/read" | "computerUseSettings/update" | "computerUseSetup/read" | "computerUseSetup/start" | "computerUseSetup/check";
3375
3483
  /** Every wire notification in this schema (SS1.9 index). */
3376
- export type MspNotification = "initialized" | "session/started" | "session/closed" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged";
3484
+ export type MspNotification = "initialized" | "session/started" | "session/closed" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/modelRetryScheduled" | "turn/unqueued" | "turn/foregroundCompleted" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "userInput/engaged" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "recap/completed" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed" | "computerUseSetup/changed" | "plugin/changed" | "plugin/marketplaceChanged";
3377
3485
  /** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
3378
3486
  export type MspServerRequest = "approval/request" | "userInput/request";
3379
3487
  /** 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.4.6",
3
+ "version": "1.4.8",
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",