@muse-code/sdk 1.4.13 → 1.4.14

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.
@@ -52,6 +52,7 @@ const REFRESH_FROM_REQUEST = [
52
52
  "judgeEscalated",
53
53
  "protectedWrite",
54
54
  "rawArgs",
55
+ "reviewerReason",
55
56
  "taskId",
56
57
  "toolCallId",
57
58
  "toolName",
@@ -190,6 +191,11 @@ export class ApprovalRouter {
190
191
  if (requested.cuaCardFacts !== undefined) {
191
192
  refreshed.cuaCardFacts = requested.cuaCardFacts;
192
193
  }
194
+ // The escalation reason belongs to the call, so it stays with the
195
+ // retained request across stages; omitted when absent.
196
+ if (requested.reviewerReason !== undefined) {
197
+ refreshed.reviewerReason = requested.reviewerReason;
198
+ }
193
199
  const acked = this.#inFlight.get(requested.approvalId);
194
200
  if (acked !== undefined)
195
201
  return this.#afterAck(acked, refreshed);
@@ -45,9 +45,11 @@ import type { InitializeParams, InitializeResult, SessionResumeParams, SessionSt
45
45
  * Caller-facing options for `session/start` (tdd SS2.5.1).
46
46
  *
47
47
  * `config` is excluded as well as `commandId` until the facade implements the
48
- * required `sessionMcp` grant check and forwarding.
48
+ * required `sessionMcp` grant check and forwarding; `previousSessionId` is
49
+ * excluded because the facade starts root sessions, and `spawnedBy` because
50
+ * the facade does not expose a spawner yet.
49
51
  */
50
- export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "config"> & {
52
+ export type StartSessionOptions = Readonly<Omit<SessionStartParams, "commandId" | "config" | "previousSessionId" | "spawnedBy"> & {
51
53
  /**
52
54
  * Require the `permissionProfile` selection (TEST-42624-10): when set,
53
55
  * the client proves the committed selection equals the requested id —
@@ -45,7 +45,10 @@ import { Session } from "./session.js";
45
45
  /**
46
46
  * Every `StartParams` member `startSession` forwards. `config` is temporarily
47
47
  * excluded until the facade can pair forwarding with the required
48
- * `sessionMcp` grant check.
48
+ * `sessionMcp` grant check, `previousSessionId` is excluded because the
49
+ * facade starts root sessions (the predecessor link belongs to a client that
50
+ * switches sessions), and `spawnedBy` because the facade does not expose a
51
+ * spawner yet.
49
52
  */
50
53
  const START_FORWARDED = [
51
54
  "approvalMode",
@@ -61,7 +64,7 @@ const START_FORWARDED = [
61
64
  * Every `ResumeParams` member `resumeSession` forwards. `config` has the same
62
65
  * temporary capability-check boundary as the start facade above.
63
66
  */
64
- const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "permissionProfile", "recoveryMode"];
67
+ const RESUME_FORWARDED = ["sessionId", "cursor", "excludeItems", "history", "modelId", "permissionProfile", "recoveryMode"];
65
68
  /**
66
69
  * The committed profile id a session snapshot claims, or null when the
67
70
  * snapshot is silent (the stable bundle strips the member; absent and null
@@ -367,6 +370,8 @@ export class MuseClient {
367
370
  params.excludeItems = options.excludeItems;
368
371
  if (options.history != null)
369
372
  params.history = options.history;
373
+ if (options.modelId != null)
374
+ params.modelId = options.modelId;
370
375
  if (options.recoveryMode != null)
371
376
  params.recoveryMode = options.recoveryMode;
372
377
  if (options.permissionProfile != null)
@@ -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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
16
+ export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:c94c3d1f2f51e6424074b9ec43eac3eedcf532d3dcd77351ec1383a87d3049c6";
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:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b";
16
+ export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:c94c3d1f2f51e6424074b9ec43eac3eedcf532d3dcd77351ec1383a87d3049c6";
17
17
  /**
18
18
  * What a build-time mismatch MEANS, in the words a human needs at 2am.
19
19
  *
package/dist/src/msp.d.ts CHANGED
@@ -214,6 +214,8 @@ export interface ApprovalRequestParams {
214
214
  protectedWrite: boolean;
215
215
  /** The tool call's arguments as a string, usually JSON. With `toolName`, it lets a client show a subject whose `kind` it does not recognize. */
216
216
  rawArgs: string;
217
+ /** The judge's escalation reason as one bounded display line (ADR 8609 D3: first sentence, whitespace controls folded, other control and format scalars stripped, 100 extended grapheme clusters max). Present only on a request released by a valid structured `escalate` with a non-blank judge rationale; absent on every other approval. A display hint only, like `judge_escalated`: it never authorizes anything. */
218
+ reviewerReason?: string;
217
219
  /** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
218
220
  sessionId: string;
219
221
  /** The stored records this event was folded from: an opaque token clients must not interpret. */
@@ -715,6 +717,20 @@ export interface DamagedRange {
715
717
  unreadableLines: number;
716
718
  }
717
719
 
720
+ /** `earlierHistory`: the boundary checkpoint's transcript tail, served in place of every item that opened in its pruned prefix (ADR 71910 D1/D3). No log record carries it; the host derives it from the checkpoint. */
721
+ export interface EarlierHistory {
722
+ /** The tail entries whose source record is in the pruned prefix, in tail order (at most 50, spec 6127 INV-002). May be empty. */
723
+ messages: EarlierHistoryMessage[];
724
+ }
725
+
726
+ /** One transcript-tail message of an [`EarlierHistory`] item. */
727
+ export interface EarlierHistoryMessage {
728
+ /** Open string enum: `"user"` or `"assistant"`, the only roles a host serves; a client skips any other value (spec 6127 FM-004). */
729
+ role: string;
730
+ /** The stored tail text verbatim (at most 1,000 characters); clients apply their own assistant display rules. */
731
+ text: string;
732
+ }
733
+
718
734
  /** The effective approval-mode projection (`EffectiveApprovalModeState`, tdd SS5.12): the same object `session/setApprovalMode` returns as `effectiveMode` and the `Session` object carries as `approvalMode`. */
719
735
  export interface EffectiveApprovalModeState {
720
736
  /** The command that last set it; `null` when no command did. */
@@ -964,6 +980,9 @@ export interface GoalSetParams {
964
980
  sessionId: string;
965
981
  }
966
982
 
983
+ /** What holds a tool call before it is admitted to execute (ADR 50063 D6). Open: a client reads an unknown value as held by something it does not know, never as released. */
984
+ export type HeldFor = "approval" | "hook" | (string & {});
985
+
967
986
  /** What history a lifecycle result actually served (tdd SS2.5.2). Open on the client side: report-what-was-served means a client treats an unknown mode as "page it yourself". */
968
987
  export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
969
988
 
@@ -1093,6 +1112,8 @@ export interface Item {
1093
1112
  displayText?: string;
1094
1113
  /** `userShell`/`subagent`: observed wall-clock duration. `workflow`: the run's wall time from launch to reconciliation, set only on the settling `item/completed` — never a sum of child durations. `toolCall`: the Backgrounded row's duration (ADR 50041 D11) — the open→update record delta in whole ms, served on the `backgroundStatus` re-emission and frozen there; absent otherwise. */
1095
1114
  durationMs?: number;
1115
+ /** `earlierHistory`: the boundary checkpoint's transcript tail (ADR 71910 D3, tdd SS4.5.22). */
1116
+ earlierHistory?: EarlierHistory;
1096
1117
  /** `workflow`: launched entry identity. */
1097
1118
  entryId?: string;
1098
1119
  /** `hookRun`: the hook event in Q2 camelCase vocabulary (tdd SS4.5.11). */
@@ -1111,9 +1132,13 @@ export interface Item {
1111
1132
  finalSummary?: string;
1112
1133
  /** `reminderChild`: the reminder generation. */
1113
1134
  generationId?: number;
1135
+ /** `toolCall` (ADR 50063 D4/D6): `true` while the call is held before it is admitted to execute. Present on an item started at hold time, cleared by the release `item/updated`, absent on calls never held. */
1136
+ held?: boolean;
1137
+ /** `toolCall` (ADR 50063 D6): what holds the call; present exactly when `held` is. */
1138
+ heldFor?: HeldFor;
1114
1139
  /** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
1115
1140
  hookKey?: string;
1116
- /** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), `EventId::derive` over the session id and the range's starting sequence number for `damagedRange` (no record carries it, SS4.5.16), and the opening durable record's event id for everything else. Opaque to clients. */
1141
+ /** Bare UUIDv7; the item's identity across its whole lifecycle. Identity rule (tdd SS4.4.1): the task id for task-backed kinds (`toolCall`, `subagent`), the pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`, `reasoning`), `EventId::derive` over the session id and the range's starting sequence number for `damagedRange` (no record carries it, SS4.5.16), the same over the boundary checkpoint's sequence number for `earlierHistory` (SS4.5.22), and the opening durable record's event id for everything else. Opaque to clients. */
1117
1142
  itemId: string;
1118
1143
  /** `scheduledFire`: the cron job id that fired (tdd SS4.5.17; ADR 45446 D2, spec 13929 amendment #62595 FR-62595-1). */
1119
1144
  jobId?: string;
@@ -1223,12 +1248,14 @@ export interface Item {
1223
1248
  triggerSource?: string;
1224
1249
  /** `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). */
1225
1250
  truncated?: boolean;
1226
- /** 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), `sideChat` always (SS4.5.13), `damagedRange` always (ADR 60914 D2). */
1251
+ /** 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), `sideChat` always (SS4.5.13), `damagedRange` always (ADR 60914 D2), `earlierHistory` always (ADR 71910 D3). */
1227
1252
  turnId?: string | null;
1228
1253
  /** `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). */
1229
1254
  usage?: TokenUsage;
1230
1255
  /** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
1231
1256
  visibleOutput?: string;
1257
+ /** `agentMessage`: the Monitor source descriptions for the wake turn's first answer (ADR 62265 D1, #62265) — stripped, bounded, one entry per arming drain in drain order. Absent (or empty) means untagged: the row renders the ordinary untagged shape. The client scrubs per part before joining. */
1258
+ wakeSourceDescriptions?: string[];
1232
1259
  /** `toolCall`: the task's registered Work ID, verbatim (`work.v2.managed_bash.sha256.…`); present only when the task registered a ManagedBash id, absent otherwise (tdd SS4.5.5, ADR 50041 D20). Stable from day one: no `x-msp-stability` marker. The host serves it at the later of the task terminal and the inbox admission (D21); absence keeps the client's v1 derivation. */
1233
1260
  workId?: string;
1234
1261
  /** `subagent`/`workflow`: the owning durable workflow run id (opaque string — not a UUID family). */
@@ -1262,7 +1289,7 @@ export interface ItemDeltaParams {
1262
1289
  }
1263
1290
 
1264
1291
  /** 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). */
1265
- export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | (string & {});
1292
+ export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | "webSearch" | "monitorFeed" | "damagedRange" | "scheduledFire" | "backgroundTerminalCompletion" | "overdueNotice" | "earlierHistory" | (string & {});
1266
1293
 
1267
1294
  /** 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. */
1268
1295
  export type ItemReadOutputEncoding = "utf8" | "base64";
@@ -1975,6 +2002,33 @@ export interface RequestReceipt {
1975
2002
  /** 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. */
1976
2003
  export type RetractOutcome = "accepted" | "declined" | (string & {});
1977
2004
 
2005
+ /** The runtime-owned git worktree a child session runs in, mirrored from the `subagent.worktree.*` records on its parent's log (tdd SS2.5.5, ADR 50042-child-worktree-on-read D2). The three enums are open: clients treat an unknown value as unknown. */
2006
+ export interface RuntimeWorktree {
2007
+ /** The commit the worktree was created from. */
2008
+ baseCommit: string;
2009
+ /** How the worktree is cleaned up. */
2010
+ cleanupPolicy: RuntimeWorktreeCleanupPolicy;
2011
+ /** Where the worktree's cleanup stands. */
2012
+ cleanupState: RuntimeWorktreeCleanupState;
2013
+ /** The head commit the active lease recorded. */
2014
+ headCommit: string;
2015
+ /** Who owns the worktree. */
2016
+ ownership: RuntimeWorktreeOwnership;
2017
+ /** True exactly when the parent's uncommitted changes were recorded as excluded from the checkout. */
2018
+ parentDirtyExcluded: boolean;
2019
+ /** The recorded worktree root, verbatim (recorded history; serving it never probes the path). */
2020
+ worktreeRoot: string;
2021
+ }
2022
+
2023
+ /** How a session's worktree is cleaned up. The set is open, so newer hosts may send other values. */
2024
+ export type RuntimeWorktreeCleanupPolicy = "removeIfClean" | (string & {});
2025
+
2026
+ /** Where a session's worktree cleanup stands. The set is open, so newer hosts may send other values. */
2027
+ export type RuntimeWorktreeCleanupState = "active" | "cleaned" | "retained" | "cleanupFailed" | (string & {});
2028
+
2029
+ /** Who owns a session's worktree. The set is open, so newer hosts may send other values. */
2030
+ export type RuntimeWorktreeOwnership = "runtimeOwned" | (string & {});
2031
+
1978
2032
  /** 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. */
1979
2033
  export type SandboxAvailability = "available" | "unavailable" | (string & {});
1980
2034
 
@@ -2011,16 +2065,22 @@ export interface Session {
2011
2065
  createdAt: string;
2012
2066
  /** The handshake `ClientInfo` recorded when the session was opened (FR-003), echoed verbatim — provenance, never an interpretation, and never a visibility gate (INV-005). **Additive-optional**; absence has four indistinguishable causes (INV-004): an in-process open; a pre-#23124 record; a half stamp where only one of name/version was recorded (FM-005) and `ClientInfo` requires both; and a session with no admitting handshake of its own — a fork child or a subagent — which never carries a stamp to begin with. */
2013
2067
  createdByClient?: ClientInfo;
2068
+ /** The handshake `ClientInfo` of the connection that currently holds this session's drive grant (spec 39851 INV-001; spec 42713 FR-58706-1, ADR 58706 D2), served on `session/read` only, as `name` and `version` (the handshake's display `title` is never served, the `createdByClient` rule). **Additive-optional, loaded-only, live**: present exactly when a live connection holds the grant and its handshake is known; absent on `notLoaded` rows, once the holder's connection drops (its orphaned turn included), and for a holder with no handshake stamp. Provenance only (INV-005): whether a client may drive is answered by `session/resume` / `turn/start` (`sessionInUse`), never by this member (FR-58706-4). */
2069
+ driveHolder?: ClientInfo;
2014
2070
  /** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
2015
2071
  firstUserPrompt?: string;
2016
2072
  /** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
2017
2073
  forkedFrom: ForkProvenance | null;
2018
2074
  /** 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. */
2019
2075
  generatedName?: string;
2076
+ /** The published head's ordinal (kt-dvw5): the head reference's own ordinal — the count of head slots in its sequence, including any reserved ones — as of the probe that served this row. A sizing hint for a first `view/page`, so the Console can size its page without folding the log. **Additive-optional**, present only on metadata reads (`session/read` with `excludeItems`), where the client has no items to count; full reads carry the items themselves and omit it. Absent when no head is published (unknown), never fabricated. May lag a live log: the head is a snapshot, and appends after its publication are not counted. */
2077
+ itemCount?: number;
2020
2078
  /** 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). */
2021
2079
  kind?: SessionKind;
2022
2080
  /** 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`. */
2023
2081
  lastActivityAt?: string;
2082
+ /** The durable log's byte length at read time (kt-dvw5): the size hint paired with `itemCount`, so the Console can size its first page without folding the log. **Additive-optional**, present only on metadata reads (`session/read` with `excludeItems`); full reads omit it. Absent when the log's length is not known (unknown), never fabricated. A live log grows after the read; the value is a snapshot. */
2083
+ logBytes?: number;
2024
2084
  /** The winning metadata fold's model; `null` when that record omits it. */
2025
2085
  modelId: string | null;
2026
2086
  /** 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`. */
@@ -2033,10 +2093,14 @@ export interface Session {
2033
2093
  path: string;
2034
2094
  /** The winning metadata fold's provider; `null` when that record omits it. */
2035
2095
  providerId: string | null;
2096
+ /** The handshake `ClientInfo` of the connection whose wire `session/resume` most recently loaded this session (spec 42713 FR-58706-2, ADR 58706 D2): stamped on the durable `session.resumed` marker, folded into the session index, and served from that column by every carrier; while the session is loaded, the stamp the loading resume wrote replaces the column on every carrier (the ack, `session/read`, `session/list`, `session/listChanged`), and after the next fold the column serves it. **Additive-optional** and **provenance only** (INV-005); a resume with no admitting handshake (TUI, exec) stamps nothing, a warm attach to an already-loaded session writes no marker, and a half stamp serves nothing (FR-003a), so absence asserts nothing. `createdByClient` never follows a resume (FR-58706-3). */
2097
+ resumedByClient?: ClientInfo;
2036
2098
  /** The session identity. */
2037
2099
  sessionId: string;
2038
2100
  /** `null` for root sessions and forks; side provenance otherwise (tdd SS2.4/SS2.5.7; ADR 45435 D2). A session carries at most one of `forkedFrom` and `sideFrom`. */
2039
2101
  sideFrom?: SideProvenance | null;
2102
+ /** The session that opened this one (spec 42713 FR-69621-6, ADR 69621 D4), recorded once in this session's creation record and served from the session index. Its `parentSessionId` is the exact spawner, unlike the containing session `parentSessionId` names above; `project` and `thread` are opaque labels the spawner may name beside it. **Additive-optional** and **provenance only** (INV-005): never a visibility or authority gate. Absence asserts nothing — no recorded spawner, a later session of the spawned process, a row folded before the member existed, or a session the index has not folded yet. */
2103
+ spawnedBy?: SessionSpawnedBy;
2040
2104
  /** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
2041
2105
  status: SessionStatus;
2042
2106
  /** Derived display title (tdd SS2.14.1, #27598): a heuristic that may evolve — its carriage, not its derivation, is the contract. **Additive-optional**, omitted when underivable. */
@@ -2385,6 +2449,8 @@ export interface SessionReadResult {
2385
2449
  session: Session;
2386
2450
  /** The fold head at read time. */
2387
2451
  viewCursor: string;
2452
+ /** The facts of the runtime-owned worktree a child read session's subagent runs in (tdd SS2.5.5, ADR 50042-child-worktree-on-read D2). A root read serves it absent; absent means no worktree facts, never an error. */
2453
+ worktree?: RuntimeWorktree;
2388
2454
  }
2389
2455
 
2390
2456
  /** `session/reasoningEffortChanged` params (tdd SS4.6.9, ADR 31255 D1): a durable reasoning-effort reconfigure record landed (tdd SS3.21). Replace wholesale, latest wins; the snapshot carries the latest value (SS4.9.1). */
@@ -2433,6 +2499,8 @@ export interface SessionResumeParams {
2433
2499
  excludeItems?: boolean;
2434
2500
  /** 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. */
2435
2501
  history?: HistoryPreference;
2502
+ /** The explicit MSP model override (T-51858-304; INV-51858-11 rank 1): a model string the caller supplies at resume time. When present it wins over the retained binding's recorded origin — over a stamped label and over a stamped pin — and it recovers an otherwise-unresolved label binding by sending the override as the wire model instead of the unresolved refusal. Omitted preserves arm (2): the retained binding resolves by recorded origin exactly as without this member. Explicit `null` is invalid params (the same closed null-tolerant set as at start). The override changes the model within the retained provider; it never names a provider, and it never touches the retained profile. */
2503
+ modelId?: string;
2436
2504
  /** The launch permission-profile pick (amendment 42624 FR-42624-1, #50054): a profile id the host catalog already admits. Select, never create. Omitted restores retained authority only, with no override. The host restores first, then applies the pick in the same pre-marker step; over a declared lost record the restore is the never-wider reset, committed before the pick, and where the reset cannot commit the pick is committed alone as that reset (spec 11237 FR-57059-4). 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). */
2437
2505
  permissionProfile?: string;
2438
2506
  /** Cold-resume replacement choice; omission preserves the retained choice. A warm attach rejects a different or unestablished choice as invalidParams. Explicit null is invalid. */
@@ -2535,6 +2603,16 @@ export interface SessionSideChatResult {
2535
2603
  viewCursor: string;
2536
2604
  }
2537
2605
 
2606
+ /** Who opened a session (`Session.spawnedBy`, spec 42713 FR-69621-6, ADR 69621 D4). */
2607
+ export interface SessionSpawnedBy {
2608
+ /** The exact session that opened this one (ADR 69621 D2). */
2609
+ parentSessionId: string;
2610
+ /** An opaque project label the spawner named, when it named one. */
2611
+ project?: string;
2612
+ /** An opaque thread label the spawner named, when it named one. */
2613
+ thread?: string;
2614
+ }
2615
+
2538
2616
  /** `session/start` params (tdd SS2.5.1). */
2539
2617
  export interface SessionStartParams {
2540
2618
  /** The session's starting approval mode; server default when omitted or explicit `null` — both spellings select the default (#23468). Select, never create — the value names a mode the host's configuration already defines (tdd SS2.5.1, SS5.12). This is the only surface that declares a non-interactive run's policy (tdd SS5.11, D-008). */
@@ -2547,12 +2625,16 @@ export interface SessionStartParams {
2547
2625
  modelId?: string;
2548
2626
  /** 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`. */
2549
2627
  permissionProfile?: string;
2628
+ /** The `/new` predecessor link (spec 207 amendment 50054, FR-50054-1): the outgoing session this start succeeds. Any syntactically valid session UUID; there is no existence check, so a link to a session that is gone still commits. Omitted means a true root. Explicit `null` is invalid params. */
2629
+ previousSessionId?: string;
2550
2630
  /** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
2551
2631
  providerId?: string | null;
2552
2632
  /** Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid. */
2553
2633
  recoveryMode?: RecoveryMode;
2554
2634
  /** Exact identity for this new root session. When omitted the server mints a UUIDv7. This field never selects an existing session: a retained or reserved id is rejected `commandRejected` with reason `session_id_conflict` (tdd SS2.5.1). */
2555
2635
  sessionId?: string;
2636
+ /** The session that opens this one (spec 42713 FR-69621-8, ADR 69621 D7), in the `Session.spawnedBy` shape: a spawner that starts a worker session over MSP names its own session here. The host writes it once into the new session's creation record, as a worker process records its environment hand-over, and `session/list` / `session/read` serve it back as `Session.spawnedBy`; `session/resume` never takes it. **Additive-optional** and **provenance only** (INV-005). A value the host cannot use (a `parentSessionId` that is not a session id, a malformed member) records nothing and never refuses the start; an unusable `project` or `thread` is dropped on its own. Hosts that predate the member ignore it. */
2637
+ spawnedBy?: SessionSpawnedBy;
2556
2638
  /** Absolute path, folded into the first metadata record. */
2557
2639
  workspaceRoot?: string;
2558
2640
  /** 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). */
@@ -3237,6 +3319,8 @@ export interface TurnError {
3237
3319
  message: string;
3238
3320
  /** Typed quota-exhaustion detail (ADR 50047 D2/D3): present iff the stopping failure was the quota class. Clients branch on presence, never by parsing `message`. */
3239
3321
  quota?: QuotaDetail;
3322
+ /** `true` when the provider refused this request. Present only on the live `turn/completed`: replayed, snapshot-served and `workflow/resume` terminals omit it, so absence does not mean the request was not denied. Never `false`. (ADR 39289 D2/D3) */
3323
+ requestDenied?: boolean;
3240
3324
  /** The server's judgment that resubmitting the same input may succeed. */
3241
3325
  retryable: boolean;
3242
3326
  }
@@ -3785,6 +3869,8 @@ export interface ViewPageParams {
3785
3869
  direction?: ViewPageDirection;
3786
3870
  /** Maximum events to return, 1–1000. The server MAY return fewer. The 1–1000 range is ratified and **published**: the model carries the bound and the bundle renders `minimum`/`maximum` instead of a bare `integer`. Range 1–1000 inclusive. */
3787
3871
  limit: number;
3872
+ /** The caller's page byte cap (kt-dvw5, additive-optional). The page serves under `min(server budget, maxBytes)`, so a Console page stays under its own budget without the server's frame cap alone deciding. Absent means the server budget governs. `0` is refused typed (`invalid_params`): a 0 cap admits no progress. A single event over the cap is truncated (marked) instead of erroring, except verbatim and fetch-key content (`item.args`, `structuredData`, `outputRef`/ `patchRef`), which is never cut and still answers typed `PageEventTooLarge`. */
3873
+ maxBytes?: number;
3788
3874
  /** The session to page. */
3789
3875
  sessionId: string;
3790
3876
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muse-code/sdk",
3
- "version": "1.4.13",
3
+ "version": "1.4.14",
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",