@muse-code/sdk 1.4.12 → 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:
|
|
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
|
*
|
package/dist/src/fingerprint.js
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
|
|
14
14
|
* working against a newer host.
|
|
15
15
|
*/
|
|
16
|
-
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:
|
|
16
|
+
export const EXPECTED_SCHEMA_FINGERPRINT = "sha256: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
|
@@ -62,6 +62,8 @@ export type ApprovalChoiceScope = "once" | "session" | "localPersistent" | (stri
|
|
|
62
62
|
|
|
63
63
|
/** One Computer Use card's facts. Empty collections and absent rows are omitted, never `null`. */
|
|
64
64
|
export interface ApprovalCuaCardFacts {
|
|
65
|
+
/** The data the call would send that the card must name; a card with any offers only one-shot choices. */
|
|
66
|
+
data?: ApprovalCuaDataFact[];
|
|
65
67
|
/** For a browser, the host of the window's current page. */
|
|
66
68
|
page?: ApprovalCuaPage;
|
|
67
69
|
/** Only the consequential steps, in call order. */
|
|
@@ -70,6 +72,26 @@ export interface ApprovalCuaCardFacts {
|
|
|
70
72
|
windowTitle?: string;
|
|
71
73
|
}
|
|
72
74
|
|
|
75
|
+
/** One piece of data the call would send. An open union on `kind` (`secret`, or `other` for a row the host can't word); a client shows `other` and any kind it doesn't know as a generic data row. */
|
|
76
|
+
export interface ApprovalCuaDataFact {
|
|
77
|
+
/** Open discriminator: `secret` or `other`. */
|
|
78
|
+
kind: string;
|
|
79
|
+
/** For `secret`, the parts of it the card may show, never the value. */
|
|
80
|
+
mask?: ApprovalCuaMask;
|
|
81
|
+
/** For `secret`, the scanner's open tag (`github_token`, `secret_named_value` and so on); a client words the tags it knows and shows any other as "a secret". */
|
|
82
|
+
secretKind?: string;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** A secret's mask: a vendor token's prefix and last 4 characters (`ghp_…3f9a`), a named value's name and length (`password=… (12 chars)`), or the length alone; all absent names the kind only. */
|
|
86
|
+
export interface ApprovalCuaMask {
|
|
87
|
+
/** The secret's length in characters. */
|
|
88
|
+
chars?: number;
|
|
89
|
+
/** A vendor token's last 4 characters. */
|
|
90
|
+
last4?: string;
|
|
91
|
+
/** A vendor token's fixed prefix (`ghp_`), or a named value's name and its `=` (`password=`). */
|
|
92
|
+
prefix?: string;
|
|
93
|
+
}
|
|
94
|
+
|
|
73
95
|
/** The page's full host, no path or query. */
|
|
74
96
|
export interface ApprovalCuaPage {
|
|
75
97
|
/** The host in Unicode. */
|
|
@@ -192,6 +214,8 @@ export interface ApprovalRequestParams {
|
|
|
192
214
|
protectedWrite: boolean;
|
|
193
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. */
|
|
194
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;
|
|
195
219
|
/** The owning session. For a subagent's approval shown on the parent, this is the parent session. */
|
|
196
220
|
sessionId: string;
|
|
197
221
|
/** The stored records this event was folded from: an opaque token clients must not interpret. */
|
|
@@ -693,6 +717,20 @@ export interface DamagedRange {
|
|
|
693
717
|
unreadableLines: number;
|
|
694
718
|
}
|
|
695
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
|
+
|
|
696
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`. */
|
|
697
735
|
export interface EffectiveApprovalModeState {
|
|
698
736
|
/** The command that last set it; `null` when no command did. */
|
|
@@ -942,6 +980,9 @@ export interface GoalSetParams {
|
|
|
942
980
|
sessionId: string;
|
|
943
981
|
}
|
|
944
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
|
+
|
|
945
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". */
|
|
946
987
|
export type HistoryMode = "anchoredSnapshot" | "inline" | "snapshot" | "none" | (string & {});
|
|
947
988
|
|
|
@@ -1071,6 +1112,8 @@ export interface Item {
|
|
|
1071
1112
|
displayText?: string;
|
|
1072
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. */
|
|
1073
1114
|
durationMs?: number;
|
|
1115
|
+
/** `earlierHistory`: the boundary checkpoint's transcript tail (ADR 71910 D3, tdd SS4.5.22). */
|
|
1116
|
+
earlierHistory?: EarlierHistory;
|
|
1074
1117
|
/** `workflow`: launched entry identity. */
|
|
1075
1118
|
entryId?: string;
|
|
1076
1119
|
/** `hookRun`: the hook event in Q2 camelCase vocabulary (tdd SS4.5.11). */
|
|
@@ -1089,9 +1132,13 @@ export interface Item {
|
|
|
1089
1132
|
finalSummary?: string;
|
|
1090
1133
|
/** `reminderChild`: the reminder generation. */
|
|
1091
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;
|
|
1092
1139
|
/** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
|
|
1093
1140
|
hookKey?: string;
|
|
1094
|
-
/** 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. */
|
|
1095
1142
|
itemId: string;
|
|
1096
1143
|
/** `scheduledFire`: the cron job id that fired (tdd SS4.5.17; ADR 45446 D2, spec 13929 amendment #62595 FR-62595-1). */
|
|
1097
1144
|
jobId?: string;
|
|
@@ -1131,6 +1178,8 @@ export interface Item {
|
|
|
1131
1178
|
recordedAt?: string;
|
|
1132
1179
|
/** `reminderChild`: the reminder agent's id. */
|
|
1133
1180
|
reminderAgentId?: string;
|
|
1181
|
+
/** Monitor `toolCall`: the D26 hint verdict plus anchor (`ReplayHint`); absent means no hint. */
|
|
1182
|
+
replayHint?: ReplayHint;
|
|
1134
1183
|
/** `subagent`: the result envelope from `ResultReady` (tdd SS4.5.7). */
|
|
1135
1184
|
result?: SubagentResult;
|
|
1136
1185
|
/** `workflow`: set on resumed launches. */
|
|
@@ -1179,6 +1228,8 @@ export interface Item {
|
|
|
1179
1228
|
summary?: string[];
|
|
1180
1229
|
/** `reminderChild`: the linked task id. */
|
|
1181
1230
|
taskId?: string;
|
|
1231
|
+
/** Terminal `toolCall`: the item after whose rows the terminal row renders (tdd SS4.5.21, ADR 56496 D2/D3). */
|
|
1232
|
+
terminalRowAfterItemId?: string;
|
|
1182
1233
|
/** `userMessage`: the prompt text as submitted. `agentMessage`: the accumulated reply, streamed via `item/delta` field `"text"`. `reasoning`: raw committed reasoning text where the provider exposes it (never streamed in v1, tdd SS4.5.4). */
|
|
1183
1234
|
text?: string;
|
|
1184
1235
|
/** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
|
|
@@ -1197,12 +1248,16 @@ export interface Item {
|
|
|
1197
1248
|
triggerSource?: string;
|
|
1198
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). */
|
|
1199
1250
|
truncated?: boolean;
|
|
1200
|
-
/** 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). */
|
|
1201
1252
|
turnId?: string | null;
|
|
1202
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). */
|
|
1203
1254
|
usage?: TokenUsage;
|
|
1204
1255
|
/** `toolCall`/`userShell`: bounded transcript-visible result text (budget per tdd SS4.5.4); streams via `item/delta` field `"output"`. */
|
|
1205
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[];
|
|
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. */
|
|
1260
|
+
workId?: string;
|
|
1206
1261
|
/** `subagent`/`workflow`: the owning durable workflow run id (opaque string — not a UUID family). */
|
|
1207
1262
|
workflowRunId?: string;
|
|
1208
1263
|
}
|
|
@@ -1234,7 +1289,7 @@ export interface ItemDeltaParams {
|
|
|
1234
1289
|
}
|
|
1235
1290
|
|
|
1236
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). */
|
|
1237
|
-
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 & {});
|
|
1238
1293
|
|
|
1239
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. */
|
|
1240
1295
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
@@ -1799,6 +1854,18 @@ export interface PluginMarketplaceUpdateParams {
|
|
|
1799
1854
|
/** A plugin row's source provenance (tdd SS3.26.2, ADR 33398 D7 item 3): camelCase of `PluginSourceProvenance`. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future provenance is additive. */
|
|
1800
1855
|
export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});
|
|
1801
1856
|
|
|
1857
|
+
/** One input still queued for delivery to a session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2): the full message body plus its log record sequence, the delivery-order and re-read dedupe key, plus the run-log record id clients join served entries against record-seeded rows by. */
|
|
1858
|
+
export interface QueuedInput {
|
|
1859
|
+
/** The queued record's log sequence: delivery order, and the key clients deduplicate re-reads by. */
|
|
1860
|
+
sequence: number;
|
|
1861
|
+
/** The `SubagentInput` record's model-authored command id: the key wire-twin rows join by in either order (the twin reads the same string from the verbatim wire args). Absent for root own-queue members, which are never `SubagentInput`. */
|
|
1862
|
+
sourceCommandId?: string;
|
|
1863
|
+
/** The run-log record id the served mirror was taken from: the key clients join served entries against record-seeded rows by, so an already-rendered input never mints a second row under diverged sequences. Absent when the host's record carries no mirror metadata (a pre-feature host), which falls back to sequence-key dedup only. */
|
|
1864
|
+
sourceRunRecordId?: string;
|
|
1865
|
+
/** The full message body, verbatim (never truncated, never a summary). */
|
|
1866
|
+
text: string;
|
|
1867
|
+
}
|
|
1868
|
+
|
|
1802
1869
|
/** Typed quota-exhaustion detail (tdd SS4.5.1, ADR 50047 D2): the limit kind plus the provider's reset instant. */
|
|
1803
1870
|
export interface QuotaDetail {
|
|
1804
1871
|
/** Which quota was exhausted (open enum; unknown values fall back). */
|
|
@@ -1905,6 +1972,12 @@ export type RecoveryObservedMode = "on" | "off" | "unknown" | (string & {});
|
|
|
1905
1972
|
/** This construction's assessment, never an operation acceptance receipt. */
|
|
1906
1973
|
export type RecoveryQualification = "qualified" | "unavailable" | "notRequired" | "unknown" | (string & {});
|
|
1907
1974
|
|
|
1975
|
+
/** The D26 first-tree-transition hint verdict plus anchor (tdd SS4.5.21, ADR 56496 D3): `rowKinds` is the open lowercase row-kind vocabulary the client formats through its shared kind-noun constructor; `afterItemId` is the item id after whose rows the hint renders. Both members always ride when the object does. */
|
|
1976
|
+
export interface ReplayHint {
|
|
1977
|
+
afterItemId: string;
|
|
1978
|
+
rowKinds: string[];
|
|
1979
|
+
}
|
|
1980
|
+
|
|
1908
1981
|
/** A request frame, either direction (SS1.2 §2.1). */
|
|
1909
1982
|
export interface Request {
|
|
1910
1983
|
/** Client-chosen id, unique among that client's in-flight requests. */
|
|
@@ -1929,6 +2002,33 @@ export interface RequestReceipt {
|
|
|
1929
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. */
|
|
1930
2003
|
export type RetractOutcome = "accepted" | "declined" | (string & {});
|
|
1931
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
|
+
|
|
1932
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. */
|
|
1933
2033
|
export type SandboxAvailability = "available" | "unavailable" | (string & {});
|
|
1934
2034
|
|
|
@@ -1965,16 +2065,22 @@ export interface Session {
|
|
|
1965
2065
|
createdAt: string;
|
|
1966
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. */
|
|
1967
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;
|
|
1968
2070
|
/** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
|
|
1969
2071
|
firstUserPrompt?: string;
|
|
1970
2072
|
/** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
|
|
1971
2073
|
forkedFrom: ForkProvenance | null;
|
|
1972
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. */
|
|
1973
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;
|
|
1974
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). */
|
|
1975
2079
|
kind?: SessionKind;
|
|
1976
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`. */
|
|
1977
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;
|
|
1978
2084
|
/** The winning metadata fold's model; `null` when that record omits it. */
|
|
1979
2085
|
modelId: string | null;
|
|
1980
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`. */
|
|
@@ -1987,10 +2093,14 @@ export interface Session {
|
|
|
1987
2093
|
path: string;
|
|
1988
2094
|
/** The winning metadata fold's provider; `null` when that record omits it. */
|
|
1989
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;
|
|
1990
2098
|
/** The session identity. */
|
|
1991
2099
|
sessionId: string;
|
|
1992
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`. */
|
|
1993
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;
|
|
1994
2104
|
/** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
|
|
1995
2105
|
status: SessionStatus;
|
|
1996
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. */
|
|
@@ -2331,12 +2441,16 @@ export interface SessionReadResult {
|
|
|
2331
2441
|
lastTurn?: LastTurn;
|
|
2332
2442
|
/** The same pointer shape as `session/resume`. Because `session/read` never subscribes this is a point-in-time log read only: no requests are re-issued after it (tdd SS2.5.5). */
|
|
2333
2443
|
pendingRequests: PendingRequestPointer[];
|
|
2444
|
+
/** The inputs still queued for delivery to the read session (tdd SS2.5.5, ADR 63254-queued-inputs-on-read D2). Absent-when-empty: a missing member means nothing queued, never an error. */
|
|
2445
|
+
queuedInputs?: QueuedInput[];
|
|
2334
2446
|
/** Current local construction only; never inferred from retained history. Absence establishes neither a choice nor supported recovery. */
|
|
2335
2447
|
recoveryObservation?: RecoveryObservation;
|
|
2336
2448
|
/** The session as folded point-in-time. */
|
|
2337
2449
|
session: Session;
|
|
2338
2450
|
/** The fold head at read time. */
|
|
2339
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;
|
|
2340
2454
|
}
|
|
2341
2455
|
|
|
2342
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). */
|
|
@@ -2385,7 +2499,9 @@ export interface SessionResumeParams {
|
|
|
2385
2499
|
excludeItems?: boolean;
|
|
2386
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. */
|
|
2387
2501
|
history?: HistoryPreference;
|
|
2388
|
-
/** The
|
|
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;
|
|
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). */
|
|
2389
2505
|
permissionProfile?: string;
|
|
2390
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. */
|
|
2391
2507
|
recoveryMode?: RecoveryMode;
|
|
@@ -2487,6 +2603,16 @@ export interface SessionSideChatResult {
|
|
|
2487
2603
|
viewCursor: string;
|
|
2488
2604
|
}
|
|
2489
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
|
+
|
|
2490
2616
|
/** `session/start` params (tdd SS2.5.1). */
|
|
2491
2617
|
export interface SessionStartParams {
|
|
2492
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). */
|
|
@@ -2499,12 +2625,16 @@ export interface SessionStartParams {
|
|
|
2499
2625
|
modelId?: string;
|
|
2500
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`. */
|
|
2501
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;
|
|
2502
2630
|
/** Initial provider routing; server default when omitted or explicit `null` — both spellings select the default (#23468). */
|
|
2503
2631
|
providerId?: string | null;
|
|
2504
2632
|
/** Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid. */
|
|
2505
2633
|
recoveryMode?: RecoveryMode;
|
|
2506
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). */
|
|
2507
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;
|
|
2508
2638
|
/** Absolute path, folded into the first metadata record. */
|
|
2509
2639
|
workspaceRoot?: string;
|
|
2510
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). */
|
|
@@ -3189,6 +3319,8 @@ export interface TurnError {
|
|
|
3189
3319
|
message: string;
|
|
3190
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`. */
|
|
3191
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;
|
|
3192
3324
|
/** The server's judgment that resubmitting the same input may succeed. */
|
|
3193
3325
|
retryable: boolean;
|
|
3194
3326
|
}
|
|
@@ -3737,6 +3869,8 @@ export interface ViewPageParams {
|
|
|
3737
3869
|
direction?: ViewPageDirection;
|
|
3738
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. */
|
|
3739
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;
|
|
3740
3874
|
/** The session to page. */
|
|
3741
3875
|
sessionId: string;
|
|
3742
3876
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@muse-code/sdk",
|
|
3
|
-
"version": "1.4.
|
|
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",
|