@muse-code/sdk 1.3.0 → 1.4.4
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.
- package/dist/src/connection/connection.d.ts +21 -0
- package/dist/src/connection/connection.js +38 -5
- package/dist/src/connection/spawn.d.ts +28 -1
- package/dist/src/connection/spawn.js +42 -8
- package/dist/src/facade/client.d.ts +9 -0
- package/dist/src/facade/client.js +90 -14
- package/dist/src/facade/gap-fill.js +14 -1
- package/dist/src/facade/host-start.d.ts +62 -0
- package/dist/src/facade/host-start.js +81 -0
- package/dist/src/facade/session.js +1 -0
- package/dist/src/facade/turn-submit.js +12 -1
- package/dist/src/fingerprint.d.ts +1 -1
- package/dist/src/fingerprint.js +1 -1
- package/dist/src/fold/session-fold.d.ts +27 -8
- package/dist/src/fold/session-fold.js +22 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.js +5 -0
- package/dist/src/msp.d.ts +654 -24
- package/package.json +1 -1
package/dist/src/msp.d.ts
CHANGED
|
@@ -142,6 +142,8 @@ export type ApprovalResolvedBy = "user" | "policy" | "llmJudge" | (string & {});
|
|
|
142
142
|
export interface ApprovalResolvedParams {
|
|
143
143
|
amendment?: ApprovalAmendment;
|
|
144
144
|
approvalId: string;
|
|
145
|
+
/** The decision time as RFC3339, projected from the durable `DecisionApplied` record's own stamp (ADR 45450 D3): optional on the wire so decoders tolerate its absence, always populated by current hosts. */
|
|
146
|
+
decidedAt?: string;
|
|
145
147
|
decidedByCommandId?: string;
|
|
146
148
|
decision: ApprovalDecision;
|
|
147
149
|
itemId: string;
|
|
@@ -243,7 +245,7 @@ export interface BranchState {
|
|
|
243
245
|
}
|
|
244
246
|
|
|
245
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. */
|
|
246
|
-
export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | (string & {});
|
|
248
|
+
export type CapabilityName = "userShell" | "sessionMcp" | "sessionListStream" | "feedback" | (string & {});
|
|
247
249
|
|
|
248
250
|
/** The client's requested capability posture (SS1.4.1). Every member defaults; an absent `capabilities` object means all defaults. */
|
|
249
251
|
export interface ClientCapabilities {
|
|
@@ -267,6 +269,34 @@ export interface ClientInfo {
|
|
|
267
269
|
version: string;
|
|
268
270
|
}
|
|
269
271
|
|
|
272
|
+
/** The language a Code Mode cell ran in (ADR 42727 D2). Open: values are lowercase VS Code language identifiers, and only `javascript` (the V8 engine) is minted today. */
|
|
273
|
+
export type CodeModeLanguage = "javascript" | (string & {});
|
|
274
|
+
|
|
275
|
+
/** One public-output span inside the item's `visibleOutput` (ADR 42727 D3). Offsets index the UTF-8 encoding of the **decoded** `visibleOutput` string, never the JSON-escaped wire text; both ends fall on code-point boundaries; named and measured like `item/readOutput`'s byte range. */
|
|
276
|
+
export interface CodeModeOutputSpan {
|
|
277
|
+
/** Length of the span, in bytes. Range 0–9007199254740991 inclusive. */
|
|
278
|
+
lengthBytes: number;
|
|
279
|
+
/** Start of the span, in bytes. Range 0–9007199254740991 inclusive. */
|
|
280
|
+
offsetBytes: number;
|
|
281
|
+
/** What the bytes are. */
|
|
282
|
+
stream: CodeModeOutputStream;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/** What a Code Mode output span's bytes are (ADR 42727 D3). Open: each engine mints its own values. */
|
|
286
|
+
export type CodeModeOutputStream = "transcript" | (string & {});
|
|
287
|
+
|
|
288
|
+
/** Code Mode's `details` payload (ADR 42727 D2/D3). Every member is absent when it does not apply, never `null`; an empty `outputSpans` list is never served. */
|
|
289
|
+
export interface CodeModeReceipt {
|
|
290
|
+
/** `wait` only, when the producer resolved it: the `itemId` of the `execute` item that started the cell. */
|
|
291
|
+
cellItemId?: string;
|
|
292
|
+
/** `execute`, and `wait` when the producer resolved the originating execute: the language the cell ran in. */
|
|
293
|
+
language?: CodeModeLanguage;
|
|
294
|
+
/** The public cell-output spans, ascending and non-overlapping; absent when there is no cell body or a hook rewrote the served body. */
|
|
295
|
+
outputSpans?: CodeModeOutputSpan[];
|
|
296
|
+
/** `execute` only: the top-level key of the item's `args` object whose value is the cell source. A pointer, never source bytes. */
|
|
297
|
+
sourceArg?: string;
|
|
298
|
+
}
|
|
299
|
+
|
|
270
300
|
/** The uniform SS3.1.2 command acknowledgement: admission only, never an outcome. `session/compact` alone may answer `"noop"`; every other command answers `"accepted"`. */
|
|
271
301
|
export interface CommandAcceptedResult {
|
|
272
302
|
/** Echo of the client-minted UUIDv7 `commandId` (SS3.1.1). */
|
|
@@ -290,6 +320,47 @@ export type CompactionOutcome = "compacted" | "noop" | "failed" | "cancelled" |
|
|
|
290
320
|
/** What initiated a compaction (tdd SS4.5.10). Open. */
|
|
291
321
|
export type CompactionTrigger = "manual" | "auto" | (string & {});
|
|
292
322
|
|
|
323
|
+
/** One row of the Settings blocked-apps list. */
|
|
324
|
+
export interface ComputerUseBlockedApp {
|
|
325
|
+
/** The app's bundle ID, or the family prefix when `prefix` is true. */
|
|
326
|
+
bundleId: string;
|
|
327
|
+
/** A built-in block, which Settings cannot remove (ADR 630 D18.8). */
|
|
328
|
+
locked: boolean;
|
|
329
|
+
/** A built-in family row: it blocks every bundle ID that starts with `bundleId`. Omitted means false; only locked rows are prefixes. */
|
|
330
|
+
prefix?: boolean;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/** 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
|
+
export type ComputerUseChoice = "ask" | "alwaysAllow" | (string & {});
|
|
335
|
+
|
|
336
|
+
/** `computerUseSettings/read` result, also answered by `computerUseSettings/update`. */
|
|
337
|
+
export interface ComputerUseSettings {
|
|
338
|
+
/** The user's blocks in the order they were added, then the built-in blocks when `showBuiltIns` asked for them. */
|
|
339
|
+
blockedApps: ComputerUseBlockedApp[];
|
|
340
|
+
/** The computer-control dropdown, as it applies: `ask` while the stored blocked-apps list can't be read (ADR 630 D18.4). */
|
|
341
|
+
computerControl: ComputerUseChoice;
|
|
342
|
+
/** The screenshots dropdown, under the same rule. */
|
|
343
|
+
screenshots: ComputerUseChoice;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** `computerUseSettings/read` params. */
|
|
347
|
+
export interface ComputerUseSettingsReadParams {
|
|
348
|
+
/** Also list the built-in blocks as locked rows (the D18.8 toggle). Omitted means false. */
|
|
349
|
+
showBuiltIns?: boolean;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** `computerUseSettings/update` params: a patch. Omitted members are left alone; the whole patch applies or none of it does. */
|
|
353
|
+
export interface ComputerUseSettingsUpdateParams {
|
|
354
|
+
/** Bundle IDs to add to the user's blocked apps. A built-in block is refused: it is already blocked. */
|
|
355
|
+
blockApps?: string[];
|
|
356
|
+
/** The new computer-control dropdown value. */
|
|
357
|
+
computerControl?: ComputerUseChoice;
|
|
358
|
+
/** The new screenshots dropdown value. */
|
|
359
|
+
screenshots?: ComputerUseChoice;
|
|
360
|
+
/** Bundle IDs to remove from the user's blocked apps. Only the user's own entries can be removed; a built-in block stays. */
|
|
361
|
+
unblockApps?: string[];
|
|
362
|
+
}
|
|
363
|
+
|
|
293
364
|
/** Context pressure level (tdd SS4.6.6): hard threshold first, both inclusive `>=`. Open. */
|
|
294
365
|
export type ContextPressureLevel = "normal" | "warning" | "blocked" | (string & {});
|
|
295
366
|
|
|
@@ -303,8 +374,40 @@ export interface ContextUsage {
|
|
|
303
374
|
windowTokens?: number;
|
|
304
375
|
}
|
|
305
376
|
|
|
306
|
-
/**
|
|
377
|
+
/** Cron's `details` payload (ADR 42728 D2, thirteenth directive). Every field a family owns lives here, under the container's one `details` key, rather than flat beside the discriminators — ADR 43399 D5 as amended. Each is a **bounded machine fact**: scalars, short identifiers and a small fixed-shape array of those. */
|
|
378
|
+
export interface CronReceipt {
|
|
379
|
+
/** Cron `create` and `delete`: the job id. On `delete`'s `missing` arm this is the caller's own id echoed back under ADR 43399 D1's declared echo — that arm has no server-side subject to name. Also the field ADR 42728 D4's D8 declaration names as conveying the hidden fact on the declared `created` + `cancelled` pairing: a job row was committed and will fire. */
|
|
380
|
+
jobId?: string;
|
|
381
|
+
/** Cron `list`: the served jobs in server order, `active` and `firing` rows only. */
|
|
382
|
+
jobs?: CronReceiptJob[];
|
|
383
|
+
/** Cron `create` (`created`, `duplicate`): absolute epoch-milliseconds of the job's next scheduled fire (the existing job's on `duplicate`, ADR 42728 D2). */
|
|
384
|
+
nextFireAtMs?: number;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/** One row of the Cron `list` receipt's `jobs` array (ADR 42728 D2). Server order, and **`active` + `firing` rows only** — the owner's `Serve active+firing only` directive. A small fixed-shape array of scalars, which is what keeps it inside D5's bounded-machine-fact rule. */
|
|
388
|
+
export interface CronReceiptJob {
|
|
389
|
+
/** The job's server-owned id. */
|
|
390
|
+
jobId: string;
|
|
391
|
+
/** Absolute epoch-milliseconds of the job's next scheduled fire. */
|
|
392
|
+
nextFireAtMs: number;
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/** Server-computed session cost member of [`CumulativeTokenUsage`] (tdd SS4.6.5, Amendment #41610 FR-41610-2/3). */
|
|
396
|
+
export interface CumulativeCost {
|
|
397
|
+
/** True when at least one leg lacked price data — clients render `(partial)`. */
|
|
398
|
+
partial: boolean;
|
|
399
|
+
/** Estimated USD total, finite and non-negative. */
|
|
400
|
+
usd: number;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/** Session running totals of counted-once usage (tdd SS4.6.5). Amendment #41610: the cache splits and server-computed `cost` join the counters. The counters stay accumulate-only; `cost` is the documented exception — it may move either way on price re-adoption and is labeled estimate (INV-41610-1). `Copy` was dropped for the `cost` member. */
|
|
307
404
|
export interface CumulativeTokenUsage {
|
|
405
|
+
/** Cache-read tokens, session total (FR-41610-1): saturating sum of the per-completion splits; an absent split contributes 0. Additive-optional: absent on the wire reads as 0 and zero totals are omitted, so pre-feature bytes decode and re-encode identically. */
|
|
406
|
+
cacheReadTokens?: number;
|
|
407
|
+
/** Cache-write tokens, session total (FR-41610-1). Additive-optional like the read split. */
|
|
408
|
+
cacheWriteTokens?: number;
|
|
409
|
+
/** Server-computed session cost (FR-41610-2): `None` (wire-absent) when no leg is priced — clients omit the row. Additive-optional: absent reads as unpriced. */
|
|
410
|
+
cost?: CumulativeCost;
|
|
308
411
|
/** Output tokens, session total. */
|
|
309
412
|
outputTokens: number;
|
|
310
413
|
/** Counted-once prompt tokens, session total. */
|
|
@@ -385,6 +488,8 @@ export interface ErrorData {
|
|
|
385
488
|
sessionId?: string;
|
|
386
489
|
/** Winning settlement on `userInputAlreadySettled`. */
|
|
387
490
|
settlement?: UserInputSettlementSummary;
|
|
491
|
+
/** The rejected upload id on `uploadNotFound` (`-32038`, SS3.33). */
|
|
492
|
+
uploadId?: string;
|
|
388
493
|
/** User-input prompt identity on SS5.10 errors. */
|
|
389
494
|
userInputId?: string;
|
|
390
495
|
/** The blocked view position on `pageEventTooLarge` errors. */
|
|
@@ -392,7 +497,7 @@ export interface ErrorData {
|
|
|
392
497
|
}
|
|
393
498
|
|
|
394
499
|
/** A stable `error.data.kind` category (SS1.6): camelCase, the value clients branch on. Open: SS2–SS5 lanes add kinds additively as their methods land (Appendix B already registers them), and the spec's edge-case rule makes a new `kind` additive only because this domain is declared open. */
|
|
395
|
-
export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
|
|
500
|
+
export type ErrorKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "invalidParams" | "experimentalRequired" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid" | (string & {});
|
|
396
501
|
|
|
397
502
|
/** The `error` member of an error response (SS1.2 §2.4). */
|
|
398
503
|
export interface ErrorObject {
|
|
@@ -414,6 +519,52 @@ export interface ErrorResponse {
|
|
|
414
519
|
jsonrpc: JsonRpcVersion;
|
|
415
520
|
}
|
|
416
521
|
|
|
522
|
+
/** `feedback/submit` classification (tdd SS3.25): the four TUI classes in camelCase wire spelling. **Closed**: a client-selected param vocabulary (#22785 E2). */
|
|
523
|
+
export type FeedbackClassification = "bug" | "badResult" | "goodResult" | "other";
|
|
524
|
+
|
|
525
|
+
/** `feedback/submit` result `outcome` (tdd SS3.25): how one confirmed submit resolved, mirroring the TUI `FeedbackSubmitOutcome` taxonomy. **Open**: a server-produced result vocabulary (#22785 E2) — an older client reading a newer value it does not know follows the open-enum tolerance rule instead of rejecting it. */
|
|
526
|
+
export type FeedbackSubmitOutcome = "uploaded" | "recorded" | "acceptedWithoutReceipt" | "trackingFailed" | "trackingUncertain" | "dark" | "disabled" | "noCredential" | "authRejected" | "rateLimited" | "failed" | (string & {});
|
|
527
|
+
|
|
528
|
+
/** `feedback/submit` params (tdd SS3.25): mirrors the TUI confirm-time `FeedbackRequest`. The call itself is the explicit confirm. */
|
|
529
|
+
export interface FeedbackSubmitParams {
|
|
530
|
+
/** Consent to attach the session record; honored only for `bug`/`badResult` with `session_id` present. `true` with `with_files: false`, with a non-`bug`/`badResult` classification, or without `session_id` is `invalidParams` (F4, F8). Defaults to `false`. */
|
|
531
|
+
attachSessionRecord?: boolean;
|
|
532
|
+
/** The report class (required). */
|
|
533
|
+
classification: FeedbackClassification;
|
|
534
|
+
/** An absolute same-host path to a client-packed bundle, admitted only as a regular file under a size cap. */
|
|
535
|
+
clientArtifactsPath?: string;
|
|
536
|
+
/** The user report text (required; non-empty for `bug`). */
|
|
537
|
+
note: string;
|
|
538
|
+
/** Names the session this call is about when present (F8, superseding F3): the bundle lands in that session's dir. Names a session this host owns. When absent, the bundle lands in the host-level feedback folder and the `session_id` tag is omitted. */
|
|
539
|
+
sessionId?: string;
|
|
540
|
+
/** The files-consent decision (required). */
|
|
541
|
+
withFiles: boolean;
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
/** `feedback/submit` result (tdd SS3.25): the upload receipt. */
|
|
545
|
+
export interface FeedbackSubmitResult {
|
|
546
|
+
/** The host-local absolute path of the always-written local bundle. */
|
|
547
|
+
bundlePath: string;
|
|
548
|
+
/** The failure cause on the `failed`, `acceptedWithoutReceipt`, `trackingFailed`, and `trackingUncertain` arms. */
|
|
549
|
+
cause?: string;
|
|
550
|
+
/** The consent-vs-reality local-tracing note, kept for display. */
|
|
551
|
+
localTracingNote?: string;
|
|
552
|
+
/** How the submit resolved. */
|
|
553
|
+
outcome: FeedbackSubmitOutcome;
|
|
554
|
+
/** The effective retry delay in milliseconds, on `rateLimited`. */
|
|
555
|
+
retryAfterMs?: number;
|
|
556
|
+
/** The consent-vs-reality session note, kept for display. */
|
|
557
|
+
sessionNote?: string;
|
|
558
|
+
/** Whether the consented session record rode at all. */
|
|
559
|
+
sessionRecordAttached: boolean;
|
|
560
|
+
/** Whether the consented session record rode shortened to fit. */
|
|
561
|
+
sessionRecordTruncated: boolean;
|
|
562
|
+
/** The internal receipt-Task id once that Task succeeds. */
|
|
563
|
+
taskId?: string;
|
|
564
|
+
/** The intake's accept id — always present on the `uploaded` arm, optional on `trackingFailed`/`trackingUncertain`; never fabricated on `recorded`. */
|
|
565
|
+
uploadId?: string;
|
|
566
|
+
}
|
|
567
|
+
|
|
417
568
|
/** Where a fork cuts the source history (tdd SS2.5.3). Turn ids are used instead of counts because ids stay stable across compaction and concurrent appends while indices do not. */
|
|
418
569
|
export interface ForkCutPoint {
|
|
419
570
|
/** The last completed turn to copy, inclusive. Naming an in-progress or unknown turn fails `forkBoundaryInvalid`. */
|
|
@@ -509,6 +660,39 @@ export type HistoryNoneReason = "excluded" | "cursorSuffix" | "historyBudget" |
|
|
|
509
660
|
/** The `history` request preference of `session/resume` (tdd SS2.5.2). The forced values downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none. */
|
|
510
661
|
export type HistoryPreference = "auto" | "inline" | "snapshot" | "anchored";
|
|
511
662
|
|
|
663
|
+
/** One installed handler (tdd SS3.26.1). */
|
|
664
|
+
export interface HookCatalogEntry {
|
|
665
|
+
/** The row's own switch (tdd SS3.26.1). Non-enabled rows are included as `false`, never dropped. */
|
|
666
|
+
enabled: boolean;
|
|
667
|
+
/** The event the handler runs on (ADR 33398 D7 item 2). */
|
|
668
|
+
event: HookEventName;
|
|
669
|
+
/** Where the handler comes from (ADR 33398 D7 item 1). */
|
|
670
|
+
handlerKind: HookHandlerKind;
|
|
671
|
+
/** The handler key (config key or plugin hook id). */
|
|
672
|
+
key: string;
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
/** Hook event names (tdd SS3.26.1, ADR 33398 D7 item 2): the lowercase-first-letter spelling of every `HookEventKind::all()` variant. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future event value is additive. */
|
|
676
|
+
export type HookEventName = "sessionStart" | "userPromptSubmit" | "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "subagentStart" | "subagentStop" | "stop" | "sessionEnd" | "notification" | "postToolUseFailure" | "stopFailure" | "postToolBatch" | "interrupt" | "sessionFork" | "toolUseStart" | "preLLMCall" | "postLLMCall" | (string & {});
|
|
677
|
+
|
|
678
|
+
/** A hook row's origin (tdd SS3.26.1, ADR 33398 D7 item 1): the config `HookSourceKind` values plus plugin-contributed. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future origin is additive. */
|
|
679
|
+
export type HookHandlerKind = "managed" | "user" | "project" | "plugin" | (string & {});
|
|
680
|
+
|
|
681
|
+
/** `hook/list` params (tdd SS3.26.1). Per-session because hook scope follows the session's workspace and plugin state. */
|
|
682
|
+
export interface HookListParams {
|
|
683
|
+
/** The target session. */
|
|
684
|
+
sessionId: string;
|
|
685
|
+
}
|
|
686
|
+
|
|
687
|
+
/** `hook/list` result (tdd SS3.26.1): one row per installed handler per event — a `ResolvedHookHandler` carries one event, and grouping would lose matcher/command identity (ADR 33398 D7 item 1). */
|
|
688
|
+
export interface HookListResult {
|
|
689
|
+
/** The session's installed hook rows (tdd SS3.26.1 promises the set, not an order). */
|
|
690
|
+
hooks: HookCatalogEntry[];
|
|
691
|
+
}
|
|
692
|
+
|
|
693
|
+
/** `hookRun` durable outcome (tdd SS4.5.11). Open: new outcomes are additive, and clients MUST render unknown values generically. */
|
|
694
|
+
export type HookRunStatus = "completed" | "blocked" | "failed" | "timedOut" | "cancelled" | (string & {});
|
|
695
|
+
|
|
512
696
|
/** Disposition when a turn is already running (tdd SS3.2). The wire default is `queue`: an SDK caller who has not looked at session state should not silently mutate an in-flight turn. */
|
|
513
697
|
export type IfBusy = "queue" | "steer" | "replace";
|
|
514
698
|
|
|
@@ -542,7 +726,7 @@ export interface InitializeResult {
|
|
|
542
726
|
userAgent: string;
|
|
543
727
|
}
|
|
544
728
|
|
|
545
|
-
/** One transcript item at one revision (tdd SS4.4.1 common fields plus the per-kind fields of SS4.5.2–4.5.
|
|
729
|
+
/** One transcript item at one revision (tdd SS4.4.1 common fields plus the per-kind fields of SS4.5.2–4.5.11, all optional and owned by the kind their doc names). `item/started`, `item/updated`, and `item/completed` carry the full object; `item/delta` appends to it by field path. */
|
|
546
730
|
export interface Item {
|
|
547
731
|
/** `subagent`: agent definition path. */
|
|
548
732
|
agentPath?: string;
|
|
@@ -556,8 +740,12 @@ export interface Item {
|
|
|
556
740
|
background?: boolean;
|
|
557
741
|
/** `toolCall`: who backgrounded the task; absent on pre-split records — never inferred (tdd SS4.5.5). */
|
|
558
742
|
backgroundInitiator?: BackgroundInitiator;
|
|
743
|
+
/** `reminderChild`: `true` when this child is a blocking reminder (it holds the turn open until it settles); absent otherwise, never `false` (ADR 41191 D4). The status word stays off the wire; clients name the reminder from `reminderAgentId`. */
|
|
744
|
+
blocking?: boolean;
|
|
559
745
|
/** `toolCall`: the provider call id (`call_...`), opaque. */
|
|
560
746
|
callId?: string;
|
|
747
|
+
/** `workflow`: one `outputRef`-shaped link per recorded child spawn with an objective (`kind: "workflow_child_prompt"`), fetched via `item/readOutput` (tdd SS4.5.8/SS4.7.4, #45449). */
|
|
748
|
+
childPromptRefs?: OutputRef[];
|
|
561
749
|
/** `subagent`/`reminderChild`: the child's own session id, readable via `session/read`/`view/page` — child transcript drill-down without a second protocol (tdd SS4.5.7). */
|
|
562
750
|
childSessionId?: string;
|
|
563
751
|
/** `reminderChild`: parent-session-dir-relative child log path; absent when no filesystem log. */
|
|
@@ -570,14 +758,18 @@ export interface Item {
|
|
|
570
758
|
commandText?: string;
|
|
571
759
|
/** `subagent`: camelCased `SubagentControlStatus` (open enum); `status` stays the generic item vocabulary. */
|
|
572
760
|
controlStatus?: SubagentControlStatus;
|
|
761
|
+
/** `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). */
|
|
762
|
+
declaredPhase?: string;
|
|
573
763
|
/** `subagent`: nesting depth. */
|
|
574
764
|
depth?: number;
|
|
575
765
|
/** `userMessage`: presentation form (tdd SS3.2); absent when the client sent none. */
|
|
576
766
|
displayText?: string;
|
|
577
|
-
/** `userShell`/`subagent`: observed wall-clock duration. */
|
|
767
|
+
/** `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. */
|
|
578
768
|
durationMs?: number;
|
|
579
769
|
/** `workflow`: launched entry identity. */
|
|
580
770
|
entryId?: string;
|
|
771
|
+
/** `hookRun`: the hook event in Q2 camelCase vocabulary (tdd SS4.5.11). */
|
|
772
|
+
event?: HookEventName;
|
|
581
773
|
/** `userShell`: the process exit code, when it exited by code. */
|
|
582
774
|
exitCode?: number;
|
|
583
775
|
/** `userShell`: the terminating signal NUMBER, when signalled (e.g. 9) — the durable payload verbatim; nothing maps numbers to names, and the fold never invents one. */
|
|
@@ -588,17 +780,23 @@ export interface Item {
|
|
|
588
780
|
failureReason?: string;
|
|
589
781
|
/** Server-provided one-line human summary any kind MAY carry, for generic rendering of kinds a client does not recognize; new kinds SHOULD carry it during their first release cycle (tdd SS4.10). */
|
|
590
782
|
fallbackText?: string;
|
|
783
|
+
/** `workflow`: the human terminal summary projected from the reconciled Launch envelope, bounded at the 64 KiB surface budget; terminal-only (tdd SS4.5.8, #45449). */
|
|
784
|
+
finalSummary?: string;
|
|
591
785
|
/** `reminderChild`: the reminder generation. */
|
|
592
786
|
generationId?: number;
|
|
787
|
+
/** `hookRun`: the durable `hook_key` (tdd SS4.5.11). */
|
|
788
|
+
hookKey?: string;
|
|
593
789
|
/** 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`), and the opening durable record's event id for everything else. Opaque to clients. */
|
|
594
790
|
itemId: string;
|
|
595
791
|
/** The item kind (open enum): clients MUST render unknown kinds generically — kind name plus `status` plus `fallbackText` (tdd SS4.10). */
|
|
596
792
|
kind: ItemKind;
|
|
793
|
+
/** `hookRun`: capped display label (tdd SS4.5.11). */
|
|
794
|
+
label?: string;
|
|
597
795
|
/** `workflow`: the reconciled terminal message, set on completion. */
|
|
598
796
|
message?: string;
|
|
599
797
|
/** `toolCall`: rich content the model saw beyond text; base64 is not inlined on the view (tdd SS4.5.5). */
|
|
600
798
|
modelVisibleContent?: ModelVisibleContent[];
|
|
601
|
-
/** `subagent`: objective as spawned. */
|
|
799
|
+
/** `subagent`: objective as spawned, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4, ADR 35691 D9); a cut sets `truncated`. The durable record stays verbatim. */
|
|
602
800
|
objective?: string;
|
|
603
801
|
/** `compaction`: terminal only — folds installed/fallback status. */
|
|
604
802
|
outcome?: CompactionOutcome;
|
|
@@ -608,9 +806,11 @@ export interface Item {
|
|
|
608
806
|
patchRef?: OutputRef;
|
|
609
807
|
/** `toolCall`: server-authored edit-family diff summary (#33025) — always beside `patchRef`; absent = no diff available (tdd SS4.5.5). */
|
|
610
808
|
patchSummary?: PatchSummary;
|
|
809
|
+
/** `workflow`: `true` only while a durable pause fact is in force for the run's generation; absent otherwise, never `false` (tdd SS4.5.8, ADR 45437 D2; the fold sets it on pause commit and clears it on resume-commit supersession or the generation's terminal). */
|
|
810
|
+
paused?: boolean;
|
|
611
811
|
/** `reasoning`: provider reasoning item id (e.g. `rs_...`), for provider-side correlation. */
|
|
612
812
|
providerItemId?: string;
|
|
613
|
-
/** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). */
|
|
813
|
+
/** `compaction`: noop/failure reason, verbatim (snake_case durable vocabulary, e.g. `"no_compactable_history"`). `hookRun`: terminal-only capped terminal reason (tdd SS4.5.11). */
|
|
614
814
|
reason?: string;
|
|
615
815
|
/** RFC3339 timestamp of the item's driving durable record. Absent on ephemeral-opened items until first durable re-emission (tdd SS4.4.1). */
|
|
616
816
|
recordedAt?: string;
|
|
@@ -626,12 +826,32 @@ export interface Item {
|
|
|
626
826
|
revision: number;
|
|
627
827
|
/** `subagent`: role as spawned. */
|
|
628
828
|
role?: string;
|
|
829
|
+
/** `hookRun`: terminal-only durable outcome; stays `blocked` when the item settles `rejected` (tdd SS4.5.11). */
|
|
830
|
+
runStatus?: HookRunStatus;
|
|
629
831
|
/** `workflow`: launched script identity. */
|
|
630
832
|
scriptId?: string;
|
|
833
|
+
/** `sideChat`: the side's own session id, readable via `session/read`/`view/page` — drill-down without a second protocol (tdd SS4.5.13; ADR 45435 D3). */
|
|
834
|
+
sideSessionId?: string;
|
|
631
835
|
/** Open enum; terminal = anything other than `"inProgress"`. Unknown values MUST be treated as terminal-unknown and rendered generically (tdd SS4.4.1). */
|
|
632
836
|
status: ItemStatus;
|
|
837
|
+
/** `toolCall`: the latest external-attempt facet, field-for-field — countdown inputs the client renders the tick from; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
838
|
+
statusAttempt?: StatusAttempt;
|
|
839
|
+
/** `toolCall`: the latest child-summary facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
840
|
+
statusChildren?: StatusChildren;
|
|
841
|
+
/** `toolCall`: the latest health facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
842
|
+
statusHealth?: StatusHealth;
|
|
843
|
+
/** `toolCall`: the task's visible latest-status line — the latest `Status` message through the shared detail normalization; absent when no status folded or nothing displayable remains (tdd SS4.5.5, #45448). */
|
|
844
|
+
statusLine?: string;
|
|
845
|
+
/** `toolCall`: the latest detail's phase row, verbatim; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
846
|
+
statusPhase?: string;
|
|
847
|
+
/** `toolCall`: the latest progress facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
848
|
+
statusProgress?: StatusProgress;
|
|
849
|
+
/** `toolCall`: the latest active-step facet, field-for-field; absent when the latest detail carries none (tdd SS4.5.5, #45448). */
|
|
850
|
+
statusStep?: StatusStep;
|
|
633
851
|
/** `userMessage`: `true` when injected mid-turn via `turn/steer` or `ifBusy: "steer"`; absent otherwise. */
|
|
634
852
|
steered?: boolean;
|
|
853
|
+
/** `workflow`: display-only stop affordance — `true` while the run is open, `false` once settled; stopping rides `workflow/cancel` (tdd SS4.5.8, #45449). Authorizes nothing. */
|
|
854
|
+
stopAvailable?: boolean;
|
|
635
855
|
/** `compaction`: summarizer strategy (installed only). */
|
|
636
856
|
strategyId?: string;
|
|
637
857
|
/** `subagent`: durable child identity (`subagent_id`). */
|
|
@@ -644,17 +864,21 @@ export interface Item {
|
|
|
644
864
|
taskId?: string;
|
|
645
865
|
/** `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). */
|
|
646
866
|
text?: string;
|
|
867
|
+
/** `workflow`: the run's launch token budget, set from the launch fact (tdd SS4.5.8, #45449); absent when the launch carried none. */
|
|
868
|
+
tokenBudget?: WorkflowTokenBudget;
|
|
647
869
|
/** `compaction`: token budget snapshot after, when measured. */
|
|
648
870
|
tokensAfter?: number;
|
|
649
871
|
/** `compaction`: token budget snapshot before, when measured. */
|
|
650
872
|
tokensBefore?: number;
|
|
651
873
|
/** `toolCall`: tool name. */
|
|
652
874
|
tool?: string;
|
|
875
|
+
/** `toolCall`: the shared semantic receipt — what the operation did, as machine-readable fact (ADR 43399 D1, tdd SS4.5.5). Optional and additive: absence is always valid and is never an error (D3). When present, a server serves the **same** receipt on every item path — `item/completed`, `view/page`, seeded snapshots and resume (D3). Observation only; carries no control authority (D4), and no field in it enters model-visible content (D7). */
|
|
876
|
+
toolReceipt?: ToolReceipt;
|
|
653
877
|
/** `compaction`: what initiated the compaction. */
|
|
654
878
|
trigger?: CompactionTrigger;
|
|
655
879
|
/** `workflow`: camelCased `WorkflowLaunchTriggerSource`, verbatim (durable runtime vocabulary, e.g. `"modelProposal"`). */
|
|
656
880
|
triggerSource?: string;
|
|
657
|
-
/** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`)
|
|
881
|
+
/** `true` when the server's per-surface text budget saturated a streamed surface (`agentMessage.text`, `reasoning.summary[*]`, `toolCall.visibleOutput`, `userShell.visibleOutput`), or cut a `subagent` surface (`objective`, `fallbackText`, `result.summary`, `result.text`). On a `subagent` item the flag is item-level and never cleared: once any of those four is cut, every later update keeps it, even when `result.text` arrives whole (ADR 35691 D9). The durable full text remains in the log (tdd SS4.5.4). */
|
|
658
882
|
truncated?: boolean;
|
|
659
883
|
/** The owning turn (== the submitting `commandId` for fresh turns, tdd SS3.1.4). `null` only for `userShell` — the one kind outside a turn (tdd SS4.5.6). */
|
|
660
884
|
turnId?: string | null;
|
|
@@ -692,8 +916,8 @@ export interface ItemDeltaParams {
|
|
|
692
916
|
viewCursor: string;
|
|
693
917
|
}
|
|
694
918
|
|
|
695
|
-
/** The
|
|
696
|
-
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | (string & {});
|
|
919
|
+
/** The eleven v1 item kinds (tdd SS4.5.2–4.5.13). Open: a new kind is additive evolution, and clients MUST render unknown kinds generically (tdd SS4.10). */
|
|
920
|
+
export type ItemKind = "userMessage" | "agentMessage" | "reasoning" | "toolCall" | "userShell" | "subagent" | "workflow" | "reminderChild" | "compaction" | "hookRun" | "sideChat" | (string & {});
|
|
697
921
|
|
|
698
922
|
/** 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. */
|
|
699
923
|
export type ItemReadOutputEncoding = "utf8" | "base64";
|
|
@@ -758,8 +982,48 @@ export interface ItemUpdatedParams {
|
|
|
758
982
|
/** The literal `"2.0"` every frame carries (SS1.2). */
|
|
759
983
|
export type JsonRpcVersion = "2.0";
|
|
760
984
|
|
|
985
|
+
/** The last `turn/completed` the session-view fold applied, restated on `session/resume` and `session/read` so a reopened session can report a failed last turn (tdd SS2.5.2, ADR 36635 D2/D3). */
|
|
986
|
+
export interface LastTurn {
|
|
987
|
+
/** Copied when the `turn/completed` carried it: runtime `failed` terminals do, host-death `failed` terminals do not (ADR 36635 D2). */
|
|
988
|
+
error?: TurnError;
|
|
989
|
+
/** Copied when the `turn/completed` carried it; a synthesized host-death `failed` terminal carries only this (`crash`, `crash_inferred`, or `incomplete`). Free display text: clients never branch on it. */
|
|
990
|
+
reason?: string;
|
|
991
|
+
/** The turn's terminal (tdd SS4.5.1; open enum). */
|
|
992
|
+
terminal: TurnTerminal;
|
|
993
|
+
/** The turn's id, as on its `turn/completed`; clients deduplicate a live `turn/completed` against this member by it (ADR 36635 D2). */
|
|
994
|
+
turnId: string;
|
|
995
|
+
}
|
|
996
|
+
|
|
997
|
+
/** `media/upload` params (tdd SS3.33, ADR 45443 D5): one chunk of a client-minted upload. All members required. */
|
|
998
|
+
export interface MediaUploadParams {
|
|
999
|
+
/** This chunk's bytes; each call's frame stays in the SS1.1 budget. */
|
|
1000
|
+
chunkBase64: string;
|
|
1001
|
+
/** The upload's chunk total; positive. */
|
|
1002
|
+
chunkCount: number;
|
|
1003
|
+
/** This chunk's 0-based position. */
|
|
1004
|
+
chunkIndex: number;
|
|
1005
|
+
/** One per call; SS3.1.1 replay answers the recorded receipt. */
|
|
1006
|
+
commandId: string;
|
|
1007
|
+
/** `video/mp4` or `video/quicktime`, matching `VideoInput`. */
|
|
1008
|
+
mediaType: string;
|
|
1009
|
+
/** The session owning the video store. */
|
|
1010
|
+
sessionId: string;
|
|
1011
|
+
/** The assembled byte count; must equal the bytes the chunks deliver. */
|
|
1012
|
+
totalBytes: number;
|
|
1013
|
+
/** The client-minted upload id (UUIDv7), sent on every chunk. */
|
|
1014
|
+
uploadId: string;
|
|
1015
|
+
}
|
|
1016
|
+
|
|
1017
|
+
/** `media/upload` result (tdd SS3.33): echoes the client-minted id, on every chunk and replay. */
|
|
1018
|
+
export interface MediaUploadResult {
|
|
1019
|
+
/** The receipt the turn part references. */
|
|
1020
|
+
uploadId: string;
|
|
1021
|
+
}
|
|
1022
|
+
|
|
761
1023
|
/** `userMessage` image attachment metadata (tdd SS4.5.2): metadata only — the durable bytes live in the log and are reachable on the raw altitude. */
|
|
762
1024
|
export interface MessageAttachment {
|
|
1025
|
+
/** This attachment's name, `<itemId>/<n>` — the item's id plus this entry's 1-based position in its `attachments` array (tdd SS4.5.2, D-071, ADR 42850; #42850). Name only: no link form and no byte read by id (#42648). Set by the server on every attachment entry it emits, and identical on live, paging, snapshot and rebuild paths (tdd SS4.5.2). Optional in the schema so older servers stay valid; clients compare and store the whole string and MUST NOT parse it (ADR 42850). */
|
|
1026
|
+
attachmentId?: string;
|
|
763
1027
|
/** Pixel height, when known. */
|
|
764
1028
|
height?: number;
|
|
765
1029
|
/** The image media type (e.g. `"image/png"`). */
|
|
@@ -776,6 +1040,8 @@ export interface ModelCatalogEntry {
|
|
|
776
1040
|
contextLimit: number | null;
|
|
777
1041
|
/** Cost block; `null` when the catalog source declared nothing. */
|
|
778
1042
|
cost: ModelCost | null;
|
|
1043
|
+
/** The row's catalog default. Optional only for decoding older hosts; a present value is never null and is always a member of `variants`. Absent under `"unknown"` (ADR 33400 D2). */
|
|
1044
|
+
defaultReasoningEffort?: ReasoningEffort;
|
|
779
1045
|
/** Description; `null` when the catalog source declared nothing. */
|
|
780
1046
|
description: string | null;
|
|
781
1047
|
/** Presentation label. */
|
|
@@ -792,8 +1058,12 @@ export interface ModelCatalogEntry {
|
|
|
792
1058
|
profileId: string | null;
|
|
793
1059
|
/** Provider routing. */
|
|
794
1060
|
providerId: string;
|
|
1061
|
+
/** Described selectable tiers, a same-order subset of `variants`. Optional only for decoding older hosts; a present value is never null. Absent under `"unknown"` (ADR 33400 D2). */
|
|
1062
|
+
reasoningEffortVariants?: ModelDescribedReasoningEffort[];
|
|
795
1063
|
/** Release date; `null` when the catalog source declared nothing. */
|
|
796
1064
|
releaseDate: string | null;
|
|
1065
|
+
/** Complete ordered selectable efforts. Optional only for decoding older hosts; a present value is never null. Current hosts always send it. */
|
|
1066
|
+
variants?: ModelReasoningEffortVariants;
|
|
797
1067
|
}
|
|
798
1068
|
|
|
799
1069
|
/** Where a model catalog came from (tdd SS3.10). **Open**: an unrecognized value is an unknown source, not an error. */
|
|
@@ -814,6 +1084,14 @@ export interface ModelCost {
|
|
|
814
1084
|
output: string;
|
|
815
1085
|
}
|
|
816
1086
|
|
|
1087
|
+
/** One described reasoning-effort tier of a `model/list` row (tdd SS3.10, ADR 33400 D2): a selectable tier plus the catalog's display string for it when declared. */
|
|
1088
|
+
export interface ModelDescribedReasoningEffort {
|
|
1089
|
+
/** The catalog's per-tier display string; absent when the catalog declared none. Optional only for decoding; a present value is never null. */
|
|
1090
|
+
description?: string;
|
|
1091
|
+
/** The tier, in the closed D-024 vocabulary. */
|
|
1092
|
+
tier: ReasoningEffort;
|
|
1093
|
+
}
|
|
1094
|
+
|
|
817
1095
|
/** `model/list` params (tdd SS3.10): the discovery half of the model-picker gesture. **A query, not a command** — no `commandId`, no durable intake record, no view event. */
|
|
818
1096
|
export interface ModelListParams {
|
|
819
1097
|
/** When present, the row matching that session's effective model is flagged `isActive`. When absent, no row is active — a client may list before it has a session (tdd SS3.10). */
|
|
@@ -832,6 +1110,9 @@ export interface ModelListResult {
|
|
|
832
1110
|
source: ModelCatalogSource;
|
|
833
1111
|
}
|
|
834
1112
|
|
|
1113
|
+
/** A complete ordered effort set, or an explicit unknown capability. */
|
|
1114
|
+
export type ModelReasoningEffortVariants = ReasoningEffort[] | UnknownModelReasoningEffortVariants;
|
|
1115
|
+
|
|
835
1116
|
/** A model selection (tdd SS3.8). Empty strings are normalized to absent. */
|
|
836
1117
|
export interface ModelSelection {
|
|
837
1118
|
/** Presentation label. */
|
|
@@ -946,6 +1227,33 @@ export type PlatformFamily = "unix" | "windows";
|
|
|
946
1227
|
/** The server's operating system (SS1.4.1). Closed, for the same reason as [`PlatformFamily`]. */
|
|
947
1228
|
export type PlatformOs = "macos" | "linux" | "windows";
|
|
948
1229
|
|
|
1230
|
+
/** One installed plugin record (tdd SS3.26.2). */
|
|
1231
|
+
export interface PluginCatalogEntry {
|
|
1232
|
+
/** The record's own install switch; non-enabled rows are included as `false`, never dropped. */
|
|
1233
|
+
enabled: boolean;
|
|
1234
|
+
/** The installed plugin's identifier. */
|
|
1235
|
+
id: string;
|
|
1236
|
+
/** The installed record's source provenance (ADR 33398 D7 item 3). */
|
|
1237
|
+
source: PluginSource;
|
|
1238
|
+
/** The installed version. */
|
|
1239
|
+
version: string;
|
|
1240
|
+
}
|
|
1241
|
+
|
|
1242
|
+
/** `plugin/list` params (tdd SS3.26.2). Per-session params; rows are the installed plugin records. */
|
|
1243
|
+
export interface PluginListParams {
|
|
1244
|
+
/** The target session. */
|
|
1245
|
+
sessionId: string;
|
|
1246
|
+
}
|
|
1247
|
+
|
|
1248
|
+
/** `plugin/list` result (tdd SS3.26.2): one row per installed plugin record; the spec promises the set, not an order. */
|
|
1249
|
+
export interface PluginListResult {
|
|
1250
|
+
/** The installed plugin rows. */
|
|
1251
|
+
plugins: PluginCatalogEntry[];
|
|
1252
|
+
}
|
|
1253
|
+
|
|
1254
|
+
/** 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. */
|
|
1255
|
+
export type PluginSource = "curated" | "marketplaceUserAdded" | "foreignImport" | "nativeLocal" | (string & {});
|
|
1256
|
+
|
|
949
1257
|
/** The reasoning-effort tier sampled at submission (tdd SS3.2, SS3.3). The **same closed tier vocabulary** on both the fresh-turn and steer lanes, spelled identically; invalid tiers are invalid params. `none` is a tier of the vocabulary (ask for no reasoning), not a way to say "unset". */
|
|
950
1258
|
export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
|
|
951
1259
|
|
|
@@ -1017,22 +1325,30 @@ export interface Session {
|
|
|
1017
1325
|
branch?: string;
|
|
1018
1326
|
/** RFC3339. For a fork this is the fork session id's UUIDv7 mint instant (tdd SS2.4). */
|
|
1019
1327
|
createdAt: string;
|
|
1328
|
+
/** 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. */
|
|
1329
|
+
createdByClient?: ClientInfo;
|
|
1020
1330
|
/** Derived first-user-prompt preview (tdd SS2.14.1, #27598). **Additive-optional**, omitted when underivable. */
|
|
1021
1331
|
firstUserPrompt?: string;
|
|
1022
1332
|
/** `null` for root sessions; fork provenance otherwise (tdd SS2.4). */
|
|
1023
1333
|
forkedFrom: ForkProvenance | null;
|
|
1334
|
+
/** 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). */
|
|
1335
|
+
kind?: SessionKind;
|
|
1024
1336
|
/** 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`. */
|
|
1025
1337
|
lastActivityAt?: string;
|
|
1026
1338
|
/** The winning metadata fold's model; `null` when that record omits it. */
|
|
1027
1339
|
modelId: string | null;
|
|
1028
1340
|
/** 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`. */
|
|
1029
1341
|
name?: string;
|
|
1342
|
+
/** 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. */
|
|
1343
|
+
parentSessionId?: string;
|
|
1030
1344
|
/** 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. */
|
|
1031
1345
|
path: string;
|
|
1032
1346
|
/** The winning metadata fold's provider; `null` when that record omits it. */
|
|
1033
1347
|
providerId: string | null;
|
|
1034
1348
|
/** The session identity. */
|
|
1035
1349
|
sessionId: string;
|
|
1350
|
+
/** `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`. */
|
|
1351
|
+
sideFrom?: SideProvenance;
|
|
1036
1352
|
/** Load state as this host knows it; `session/list` reports `notLoaded` for sessions loaded by *other* hosts (tdd SS2.4). */
|
|
1037
1353
|
status: SessionStatus;
|
|
1038
1354
|
/** 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. */
|
|
@@ -1079,13 +1395,26 @@ export interface SessionBranchChangedParams {
|
|
|
1079
1395
|
workspaceRoot: string;
|
|
1080
1396
|
}
|
|
1081
1397
|
|
|
1398
|
+
/** `session/closed` params (tdd SS2.6.2; enrolled by #33065): a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is `notLoaded`; the log remains on disk and `session/resume` reloads it. A crash emits nothing — only the two orderly unload paths do, and both write the durable `SessionEnd` record first. */
|
|
1399
|
+
export interface SessionClosedParams {
|
|
1400
|
+
/** Which orderly unload path fired. */
|
|
1401
|
+
reason: SessionClosedReason;
|
|
1402
|
+
/** The unloaded session. */
|
|
1403
|
+
sessionId: string;
|
|
1404
|
+
/** The final view head; a client that stores it can later `session/resume {cursor}` and receive exactly the (empty) suffix. An **opaque** view cursor: clients relay it, never parse it (tdd SS4.1). **Required-nullable**: the producers always write the member and write `null` when the final fold failed at unload (`session/idle.rs`, `serve/shutdown.rs`; PR #16779 review) — the host defines no cursor values of its own and never invents one, and the subscriber still learns the session closed. */
|
|
1405
|
+
viewCursor: string | null;
|
|
1406
|
+
}
|
|
1407
|
+
|
|
1408
|
+
/** The SS2.6.2 closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the #33065 menu-B pick (PR #33201 comment 5638727249, recorded in the enrollment decision record), which settles that this notification reason enum publishes open rather than resting on E2's result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all. */
|
|
1409
|
+
export type SessionClosedReason = "idle" | "hostShutdown" | (string & {});
|
|
1410
|
+
|
|
1082
1411
|
/** `session/compact` params (tdd SS3.7): manually compact the session's conversation context — the `/compact` gesture. Compaction runs asynchronously; the ack is admission only. */
|
|
1083
1412
|
export interface SessionCompactParams {
|
|
1084
1413
|
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
1085
1414
|
commandId: string;
|
|
1086
1415
|
/** The target session. */
|
|
1087
1416
|
sessionId: string;
|
|
1088
|
-
/** The run whose context to compact. Omit and the server resolves the session's current/latest run; a session with no resolvable run rejects with `commandRejected` reason `missing_run` (tdd SS3.7). */
|
|
1417
|
+
/** The run whose context to compact. Omit and the server resolves the session's current/latest run; a session with no resolvable run rejects with `commandRejected` reason `missing_run` (tdd SS3.7). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
|
|
1089
1418
|
turnId?: string;
|
|
1090
1419
|
}
|
|
1091
1420
|
|
|
@@ -1172,16 +1501,37 @@ export interface SessionHistory {
|
|
|
1172
1501
|
snapshot: ViewSnapshot | null;
|
|
1173
1502
|
}
|
|
1174
1503
|
|
|
1504
|
+
/** What kind of session this is (spec 42713 FR-001/FR-005, ADR 42713 D1/D4). **Open**: a new kind is additive evolution, and a client MUST render an unknown value as an unknown-but-present kind rather than rejecting the row. Both v1 values are terms the tree already uses — the child log directory is `subagent` and `ItemKind` already carries a `subagent` variant — so no new vocabulary is minted. */
|
|
1505
|
+
export type SessionKind = "root" | "subagent" | (string & {});
|
|
1506
|
+
|
|
1507
|
+
/** Exact branch selection (#42035 FR-42035-2). */
|
|
1508
|
+
export interface SessionListBranchFilter {
|
|
1509
|
+
/** 1–32 nonempty branch names, each 1–256 UTF-8 bytes, counted before deduplication; `null` selects sessions with no branch. */
|
|
1510
|
+
anyOf: (string | null)[];
|
|
1511
|
+
}
|
|
1512
|
+
|
|
1175
1513
|
/** `session/listChanged` params (#33084, ADR 33084 D3): one changed row of the `session/list` shape — the full SS2.4 Session object as the answering host's list face serves it at emission (the ADR 29243 live-overlaid row), a replace, never a delta. Emitted only on connections that negotiated the `sessionListStream` capability at `initialize` (ADR 33084 D2); row birth stays on `session/started`, unload pairs with `session/closed`. */
|
|
1176
1514
|
export interface SessionListChangedParams {
|
|
1177
1515
|
/** The served list row for the changed session. */
|
|
1178
1516
|
session: Session;
|
|
1179
1517
|
}
|
|
1180
1518
|
|
|
1519
|
+
/** The `session/list` filter (#42035, spec 207 FR-42035-2..5). Members are ANDed with each other and with the top-level `workspaceRoot` and `updatedAfter`; values inside each `anyOf` are ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orders `text.fields` `name` then `title`. */
|
|
1520
|
+
export interface SessionListFilter {
|
|
1521
|
+
/** Only sessions whose branch is one of these. */
|
|
1522
|
+
branch?: SessionListBranchFilter;
|
|
1523
|
+
/** Only sessions whose ID is one of these. */
|
|
1524
|
+
sessionId?: SessionListSessionIdFilter;
|
|
1525
|
+
/** Only sessions whose served name or title matches these token prefixes. */
|
|
1526
|
+
text?: SessionListTextFilter;
|
|
1527
|
+
}
|
|
1528
|
+
|
|
1181
1529
|
/** `session/list` params (tdd SS2.5.4). Read-only; never touches leases. */
|
|
1182
1530
|
export interface SessionListParams {
|
|
1183
1531
|
/** Opaque page cursor from a prior result. Page cursors are a distinct opaque-string family from view cursors and stream cursors, valid only for re-issuing the same listing (tdd SS2.5.4). Omitted and explicit `null` both mean "first page" (#23468). */
|
|
1184
1532
|
cursor?: string | null;
|
|
1533
|
+
/** Optional structured selection applied inside the bounded index query before paging (#42035, spec 207 FR-42035-1). Present — including `{}` — makes a supporting server echo its canonical form as `appliedFilter`; omitted keeps the pre-#42035 behavior. */
|
|
1534
|
+
filter?: SessionListFilter;
|
|
1185
1535
|
/** Page size; default 50, max 200 — the cap is published under #22785 E6c (owner-ruled 2026-08-26). Maximum 200. */
|
|
1186
1536
|
limit?: number;
|
|
1187
1537
|
/** Only sessions with log activity after this RFC3339 instant. */
|
|
@@ -1192,12 +1542,33 @@ export interface SessionListParams {
|
|
|
1192
1542
|
|
|
1193
1543
|
/** `session/list` result (tdd SS2.5.4). Ordering is `updatedAt` descending. */
|
|
1194
1544
|
export interface SessionListResult {
|
|
1545
|
+
/** The canonical filter the server applied, present exactly when the request carried `filter` (#42035, spec 207 FR-42035-1). The probe is per-predicate PRESENCE (ADR 42035 D6): a client that requires filtering checks that every predicate it sent comes back as a member here, and treats a missing member as unsupported. Value equality is the wrong test — canonicalization trims, lowercases, NFC-normalizes, dedupes and sorts, so the echoed values often differ from the sent ones on a correctly filtered page. */
|
|
1546
|
+
appliedFilter?: SessionListFilter;
|
|
1195
1547
|
/** The next page's cursor; `null` on the last page. */
|
|
1196
1548
|
nextCursor: string | null;
|
|
1197
1549
|
/** The page of stored sessions. */
|
|
1198
1550
|
sessions: Session[];
|
|
1199
1551
|
}
|
|
1200
1552
|
|
|
1553
|
+
/** Exact session-ID selection (#42035 FR-42035-2). */
|
|
1554
|
+
export interface SessionListSessionIdFilter {
|
|
1555
|
+
/** 1–200 session UUIDs, counted before deduplication. */
|
|
1556
|
+
anyOf: string[];
|
|
1557
|
+
}
|
|
1558
|
+
|
|
1559
|
+
/** A served session field `session/list` text search reads (#42035 FR-42035-3). The client selects it, so the set is closed. */
|
|
1560
|
+
export type SessionListTextField = "name" | "title";
|
|
1561
|
+
|
|
1562
|
+
/** Name/title token-prefix search (#42035 FR-42035-3/FR-42035-4). Each term is trimmed, lowercased with ordinary Unicode lowercase, then NFC- normalized, and matches the beginning of an alphanumeric token, accent-sensitively (`check` matches `Checkout`; `eck` does not). NFC means a decomposed and a precomposed spelling of one term are the same term, and the echo returns the composed form. Matching never reorders rows. */
|
|
1563
|
+
export interface SessionListTextFilter {
|
|
1564
|
+
/** Every term must match at least one selected field. */
|
|
1565
|
+
allOf?: string[];
|
|
1566
|
+
/** At least one term must match a selected field. `allOf` plus `anyOf` carry 1–16 terms in total, each 1–128 UTF-8 bytes in its canonical form (trimmed, lowercased, NFC) — the bytes `appliedFilter` echoes. Lowercasing and NFC can both lengthen a term, so a term inside the bound raw may still exceed it canonically. */
|
|
1567
|
+
anyOf?: string[];
|
|
1568
|
+
/** The 1–2 unique served fields searched. */
|
|
1569
|
+
fields: SessionListTextField[];
|
|
1570
|
+
}
|
|
1571
|
+
|
|
1201
1572
|
/** One native MCP server supplied at session construction (ADR 32760 D1). **Closed union** (#33295 owner ruling A1, extending D-033/D-050 to `oneOf`): a validator MUST reject an undeclared `transport` arm — the server fails `session/start` decode on an unknown transport, and a future transport arrives as an explicit schema addition. */
|
|
1202
1573
|
export type SessionMcpServerConfig = { /** Ordered child arguments. */ args?: string[]; /** Executable name or path. Configuration diagnostics never echo it. */ command: string; /** Explicit child environment additions. */ env?: Record<string, string>; /** Stdio framing mode; defaults to automatic detection. */ framing?: SessionMcpStdioFraming; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "stdio"; } | { /** Explicit request headers. */ headers?: Record<string, string>; /** Required/optional startup posture; defaults to required. */ mode?: SessionMcpServerMode; transport: "streamableHttp"; /** HTTP(S) endpoint. Configuration diagnostics never echo it. */ url: string; };
|
|
1203
1574
|
|
|
@@ -1265,6 +1636,8 @@ export interface SessionReadParams {
|
|
|
1265
1636
|
export interface SessionReadResult {
|
|
1266
1637
|
/** The served history. */
|
|
1267
1638
|
history: SessionHistory;
|
|
1639
|
+
/** Same member as `session/resume` (tdd SS2.5.5, ADR 36635 D2). */
|
|
1640
|
+
lastTurn?: LastTurn;
|
|
1268
1641
|
/** 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). */
|
|
1269
1642
|
pendingRequests: PendingRequestPointer[];
|
|
1270
1643
|
/** The session as folded point-in-time. */
|
|
@@ -1327,6 +1700,8 @@ export interface SessionResumeParams {
|
|
|
1327
1700
|
export interface SessionResumeResult {
|
|
1328
1701
|
/** The served history. */
|
|
1329
1702
|
history: SessionHistory;
|
|
1703
|
+
/** How the last folded turn ended (tdd SS2.5.2, ADR 36635 D2). **Additive-optional**; absence is a non-assertion. */
|
|
1704
|
+
lastTurn?: LastTurn;
|
|
1330
1705
|
/** The late-joiner pointer set; empty when nothing is pending. */
|
|
1331
1706
|
pendingRequests: PendingRequestPointer[];
|
|
1332
1707
|
/** The loaded session. */
|
|
@@ -1393,6 +1768,26 @@ export interface SessionSetReasoningEffortResult {
|
|
|
1393
1768
|
status: CommandStatus;
|
|
1394
1769
|
}
|
|
1395
1770
|
|
|
1771
|
+
/** `session/sideChat` params (tdd SS2.5.7; ADR 45435 D2). */
|
|
1772
|
+
export interface SessionSideChatParams {
|
|
1773
|
+
/** The SS2.5 idempotency handle (UUIDv7). */
|
|
1774
|
+
commandId: string;
|
|
1775
|
+
/** The source main session. */
|
|
1776
|
+
sessionId: string;
|
|
1777
|
+
}
|
|
1778
|
+
|
|
1779
|
+
/** `session/sideChat` result (tdd SS2.5.7; ADR 45435 D2): the `session/resume` envelope for the **new** side session, whose `session.sideFrom` carries the provenance. The side opens empty. */
|
|
1780
|
+
export interface SessionSideChatResult {
|
|
1781
|
+
/** The served history (inline; SS2.5.7's empty-items half is #49416 — inherited turns surface until the boundary-aware fold lands). */
|
|
1782
|
+
history: SessionHistory;
|
|
1783
|
+
/** The late-joiner pointer set. */
|
|
1784
|
+
pendingRequests: PendingRequestPointer[];
|
|
1785
|
+
/** The new side session, carrying `sideFrom` provenance. */
|
|
1786
|
+
session: Session;
|
|
1787
|
+
/** The new side session's view head. */
|
|
1788
|
+
viewCursor: string;
|
|
1789
|
+
}
|
|
1790
|
+
|
|
1396
1791
|
/** `session/start` params (tdd SS2.5.1). */
|
|
1397
1792
|
export interface SessionStartParams {
|
|
1398
1793
|
/** 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). */
|
|
@@ -1409,6 +1804,8 @@ export interface SessionStartParams {
|
|
|
1409
1804
|
sessionId?: string;
|
|
1410
1805
|
/** Absolute path, folded into the first metadata record. */
|
|
1411
1806
|
workspaceRoot?: string;
|
|
1807
|
+
/** 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). */
|
|
1808
|
+
workspaceRoots?: string[];
|
|
1412
1809
|
}
|
|
1413
1810
|
|
|
1414
1811
|
/** `session/start` result (tdd SS2.5.1). */
|
|
@@ -1419,6 +1816,12 @@ export interface SessionStartResult {
|
|
|
1419
1816
|
viewCursor: string;
|
|
1420
1817
|
}
|
|
1421
1818
|
|
|
1819
|
+
/** `session/started` params (tdd SS2.6.1; enrolled by #33065): a session became newly loaded on this host via `session/start`, `session/fork`, or `session/sideChat` (never `session/resume` — Appendix C, OQ-F), broadcast to every initialized connection. The one member is the same `$defs/Session` object the `session/start`/`session/fork` results carry, so the broadcast and the result describe one fact through one type — the host builds the broadcast payload as a `$defs/Session` — the fresh-start arm reuses the result's `session` member, the start-replay arm builds the live attach snapshot — and the emission is parity-gated against this type at the producer (`session-server` prod-assembly capture) and over the committed transcript corpus (conformance `session_lifecycle_enrollment`). */
|
|
1820
|
+
export interface SessionStartedParams {
|
|
1821
|
+
/** The newly loaded session, as of the start/fork fold. */
|
|
1822
|
+
session: Session;
|
|
1823
|
+
}
|
|
1824
|
+
|
|
1422
1825
|
/** A session's load state (tdd SS2.4). */
|
|
1423
1826
|
export type SessionStatus = "notLoaded" | "idle" | "running" | (string & {});
|
|
1424
1827
|
|
|
@@ -1507,6 +1910,22 @@ export interface SessionViewHealthChangedParams {
|
|
|
1507
1910
|
sessionId: string;
|
|
1508
1911
|
}
|
|
1509
1912
|
|
|
1913
|
+
/** Side provenance folded from the durable side provenance (`SideChatProvenance`, tdd SS2.4/SS2.5.7; ADR 45435 D2). */
|
|
1914
|
+
export interface SideProvenance {
|
|
1915
|
+
/** The `commandId` of the `session/sideChat` that created it. */
|
|
1916
|
+
commandId: string;
|
|
1917
|
+
/** An **opaque provenance string** preserved verbatim from the durable side provenance (`source_cut_cursor`). Display-only — not one of the cursor families: clients MUST NOT parse it and no method accepts it (tdd SS2.4). */
|
|
1918
|
+
cutCursor: string;
|
|
1919
|
+
/** The source main session this side was opened from. */
|
|
1920
|
+
sessionId: string;
|
|
1921
|
+
}
|
|
1922
|
+
|
|
1923
|
+
/** `skill/setActivation` activation target (tdd SS3.30.1). **Closed**: a client-selected write vocabulary (ADR 45433 D2) — a write must fail a scope the host does not implement rather than record activation against an unknown target. Contrast the open read-side [`SkillSource`]. */
|
|
1924
|
+
export type SkillActivationScope = "user" | "project" | "bundled" | "plugin";
|
|
1925
|
+
|
|
1926
|
+
/** The three-state skill activation (tdd SS3.30.1, ADR 10512 — no new state). **Closed**: a client-selected write vocabulary (ADR 45433 D2). */
|
|
1927
|
+
export type SkillActivationState = "on" | "userInvocableOnly" | "off";
|
|
1928
|
+
|
|
1510
1929
|
/** One typed-invocable shortcut spelling (tdd SS3.22.1). A plugin skill may contribute two rows: its bare-name winner and its qualified `<pluginId>:<skillId>` form. */
|
|
1511
1930
|
export interface SkillCatalogEntry {
|
|
1512
1931
|
/** Present when the skill declares an argument hint. */
|
|
@@ -1529,7 +1948,7 @@ export interface SkillChangedParams {
|
|
|
1529
1948
|
sessionId: string;
|
|
1530
1949
|
}
|
|
1531
1950
|
|
|
1532
|
-
/** `skill/list` params (tdd SS3.22.1). Per-session because skill scope follows the session's workspace and plugin state. */
|
|
1951
|
+
/** `skill/list` params (tdd SS3.22.1, SS3.30.3). Per-session because skill scope follows the session's workspace and plugin state. */
|
|
1533
1952
|
export interface SkillListParams {
|
|
1534
1953
|
/** The target session. */
|
|
1535
1954
|
sessionId: string;
|
|
@@ -1541,6 +1960,36 @@ export interface SkillListResult {
|
|
|
1541
1960
|
skills: SkillCatalogEntry[];
|
|
1542
1961
|
}
|
|
1543
1962
|
|
|
1963
|
+
/** `skill/setActivation` params (tdd SS3.30.1, #45433): turn one skill on or off in any scope through the single `SkillsService::set_activation` seam. */
|
|
1964
|
+
export interface SkillSetActivationParams {
|
|
1965
|
+
/** The activation to apply. */
|
|
1966
|
+
activation: SkillActivationState;
|
|
1967
|
+
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
1968
|
+
commandId: string;
|
|
1969
|
+
/** The activation target. */
|
|
1970
|
+
scope: SkillActivationScope;
|
|
1971
|
+
/** Names one skill: a bare or plugin-qualified token from the session's full catalog (tdd SS3.30.3), the SS3.22.1 row vocabulary. */
|
|
1972
|
+
selector: string;
|
|
1973
|
+
/** The target session. */
|
|
1974
|
+
sessionId: string;
|
|
1975
|
+
}
|
|
1976
|
+
|
|
1977
|
+
/** `skill/setActivation` result (tdd SS3.30.1, #45433): the ack envelope plus the applied state. */
|
|
1978
|
+
export interface SkillSetActivationResult {
|
|
1979
|
+
/** The applied activation. */
|
|
1980
|
+
activation: SkillActivationState;
|
|
1981
|
+
/** Echoes the client's id. */
|
|
1982
|
+
commandId: string;
|
|
1983
|
+
/** The activation value in force for that `(selector, scope)` immediately before the write: the same value a full-catalog `skill/list` row would have carried in `activation` for it. */
|
|
1984
|
+
previous: SkillActivationState;
|
|
1985
|
+
/** Echoes the applied write's scope. */
|
|
1986
|
+
scope: SkillActivationScope;
|
|
1987
|
+
/** Echoes the applied write's selector. */
|
|
1988
|
+
selector: string;
|
|
1989
|
+
/** Admission status. */
|
|
1990
|
+
status: CommandStatus;
|
|
1991
|
+
}
|
|
1992
|
+
|
|
1544
1993
|
/** A skill row's source scope (tdd SS3.22.1): the projection of the skills crate's `SkillsSourceScope`. Open (server-produced result vocabulary, the #22785 enum-openness rule): a future scope value is additive. */
|
|
1545
1994
|
export type SkillSource = "bundled" | "user" | "project" | "plugin" | (string & {});
|
|
1546
1995
|
|
|
@@ -1596,6 +2045,71 @@ export interface SourceRange {
|
|
|
1596
2045
|
stream: StreamRef;
|
|
1597
2046
|
}
|
|
1598
2047
|
|
|
2048
|
+
/** `toolCall.statusAttempt` (tdd SS4.5.5, #45448): the latest `TaskExternalAttemptDetail`, field-for-field — countdown inputs the client renders the tick from, so no event spam. */
|
|
2049
|
+
export interface StatusAttempt {
|
|
2050
|
+
/** The attempt number. */
|
|
2051
|
+
attempt: number;
|
|
2052
|
+
/** The error kind (durable vocabulary, verbatim), when recorded. */
|
|
2053
|
+
errorKind?: string;
|
|
2054
|
+
/** The HTTP status, when recorded. */
|
|
2055
|
+
httpStatus?: number;
|
|
2056
|
+
/** The maximum attempts, when known. */
|
|
2057
|
+
maxAttempts?: number;
|
|
2058
|
+
/** The scheduled next attempt, when known. */
|
|
2059
|
+
nextAttempt?: number;
|
|
2060
|
+
/** The operation (durable vocabulary, verbatim). */
|
|
2061
|
+
operation: string;
|
|
2062
|
+
/** The retry delay in ms, when known. */
|
|
2063
|
+
retryDelayMs?: number;
|
|
2064
|
+
/** The external system (durable vocabulary, verbatim). */
|
|
2065
|
+
system: string;
|
|
2066
|
+
}
|
|
2067
|
+
|
|
2068
|
+
/** `toolCall.statusChildren` (tdd SS4.5.5, #45448): the latest `TaskChildSummaryDetail`, field-for-field. */
|
|
2069
|
+
export interface StatusChildren {
|
|
2070
|
+
/** Active children. */
|
|
2071
|
+
active: number;
|
|
2072
|
+
/** Cancelled children. */
|
|
2073
|
+
cancelled: number;
|
|
2074
|
+
/** Completed children. */
|
|
2075
|
+
completed: number;
|
|
2076
|
+
/** Failed children. */
|
|
2077
|
+
failed: number;
|
|
2078
|
+
/** Total children, when known. */
|
|
2079
|
+
total?: number;
|
|
2080
|
+
}
|
|
2081
|
+
|
|
2082
|
+
/** `toolCall.statusHealth` (tdd SS4.5.5, #45448): the latest `TaskHealthDetail`, field-for-field. */
|
|
2083
|
+
export interface StatusHealth {
|
|
2084
|
+
/** The health level (the durable `TaskHealthLevel` vocabulary verbatim). */
|
|
2085
|
+
level: StatusHealthLevel;
|
|
2086
|
+
/** The reason, when recorded. */
|
|
2087
|
+
reason?: string;
|
|
2088
|
+
}
|
|
2089
|
+
|
|
2090
|
+
/** `toolCall.statusHealth.level` (tdd SS4.5.5, #45448): the durable `TaskHealthLevel` vocabulary verbatim. Open — runtime vocabulary may grow additively, and clients MUST render unknown levels generically. */
|
|
2091
|
+
export type StatusHealthLevel = "ok" | "waiting" | "degraded" | "retrying" | "blocked" | "failed" | (string & {});
|
|
2092
|
+
|
|
2093
|
+
/** `toolCall.statusProgress` (tdd SS4.5.5, #45448): the latest `TaskProgressDetail`, field-for-field. */
|
|
2094
|
+
export interface StatusProgress {
|
|
2095
|
+
/** Completed units. */
|
|
2096
|
+
current: number;
|
|
2097
|
+
/** Total units, when known. */
|
|
2098
|
+
total?: number;
|
|
2099
|
+
/** Unit label, when recorded. */
|
|
2100
|
+
unit?: string;
|
|
2101
|
+
}
|
|
2102
|
+
|
|
2103
|
+
/** `toolCall.statusStep` (tdd SS4.5.5, #45448): the latest `TaskActiveStepDetail`, field-for-field. */
|
|
2104
|
+
export interface StatusStep {
|
|
2105
|
+
/** The step index, when known. */
|
|
2106
|
+
index?: number;
|
|
2107
|
+
/** The active step's label. */
|
|
2108
|
+
label: string;
|
|
2109
|
+
/** The step count, when known. */
|
|
2110
|
+
total?: number;
|
|
2111
|
+
}
|
|
2112
|
+
|
|
1599
2113
|
/** One raw stream named by a [`SourceRange`] (tdd SS4.2). */
|
|
1600
2114
|
export interface StreamRef {
|
|
1601
2115
|
/** The stream id. */
|
|
@@ -1641,9 +2155,9 @@ export interface SubagentResult {
|
|
|
1641
2155
|
evidenceRefs: string[];
|
|
1642
2156
|
/** Structured result data, verbatim, when present. */
|
|
1643
2157
|
structuredData?: Record<string, unknown>;
|
|
1644
|
-
/**
|
|
2158
|
+
/** Result summary, bounded on the wire at the 64 KiB retained-text budget (tdd SS4.5.4 and SS4.5.7, ADR 35691 D9); a cut sets the item's `truncated`. The durable record stays verbatim. */
|
|
1645
2159
|
summary: string;
|
|
1646
|
-
/** Result text (
|
|
2160
|
+
/** Result text, when present, bounded on the wire at the same 64 KiB budget (ADR 35691 D9); a cut sets the item's `truncated`. */
|
|
1647
2161
|
text?: string;
|
|
1648
2162
|
}
|
|
1649
2163
|
|
|
@@ -1717,6 +2231,37 @@ export interface TaskCommandResult {
|
|
|
1717
2231
|
taskId: string;
|
|
1718
2232
|
}
|
|
1719
2233
|
|
|
2234
|
+
/** One background-task inventory row (tdd SS3.31). The row is the stable contract: `kind` and `status` stay open so a future state extends them without breaking clients. */
|
|
2235
|
+
export interface TaskListEntry {
|
|
2236
|
+
/** Who backgrounded the task, mirroring the item field. **Additive-optional**: absent on pre-split records and registry-only rows, never inferred. */
|
|
2237
|
+
backgroundInitiator?: BackgroundInitiator;
|
|
2238
|
+
/** What the workload is: `"tool"` or `"tool.*"` for item rows (the recorded kind when the registry records one, else `"tool"`); the recorded registry kind string verbatim for registry-only rows. Open vocabulary — clients MUST ignore unknown kinds. A `String`, not an enum: registry kind strings are unbounded. */
|
|
2239
|
+
kind: string;
|
|
2240
|
+
/** The host-known task start, RFC3339. **Additive-optional**: omitted, never guessed, when the host does not know it. */
|
|
2241
|
+
startedAt?: string;
|
|
2242
|
+
/** `"inProgress"` — the only value at this increment, since every listed row is non-terminal by construction. */
|
|
2243
|
+
status: TaskListStatus;
|
|
2244
|
+
/** The `toolCall` item's `itemId` for item rows; the runtime registry id for registry-only rows. */
|
|
2245
|
+
taskId: string;
|
|
2246
|
+
/** The short tool name on item-visible tool rows only; never a label, never arguments. **Additive-optional**: absent elsewhere. */
|
|
2247
|
+
tool?: string;
|
|
2248
|
+
}
|
|
2249
|
+
|
|
2250
|
+
/** `task/list` params (tdd SS3.31): the session whose background-task inventory to read. A read-only query in the `skill/list` mold: no `commandId`, no durable record, no view event. */
|
|
2251
|
+
export interface TaskListParams {
|
|
2252
|
+
/** The target session. */
|
|
2253
|
+
sessionId: string;
|
|
2254
|
+
}
|
|
2255
|
+
|
|
2256
|
+
/** `task/list` result (tdd SS3.31): one row per running background workload in `task/stopAll` reach, oldest first; empty when nothing is running. */
|
|
2257
|
+
export interface TaskListResult {
|
|
2258
|
+
/** The session's live background-task rows. */
|
|
2259
|
+
tasks: TaskListEntry[];
|
|
2260
|
+
}
|
|
2261
|
+
|
|
2262
|
+
/** A task row's status (tdd SS3.31). Open (server-produced result vocabulary, the #22785 enum-openness rule): a future state is additive, and clients MUST ignore unknown statuses. */
|
|
2263
|
+
export type TaskListStatus = "inProgress" | (string & {});
|
|
2264
|
+
|
|
1720
2265
|
/** `task/stopAll` params (tdd §3.15): stop every stoppable background workload live at admission. */
|
|
1721
2266
|
export interface TaskStopAllParams {
|
|
1722
2267
|
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
@@ -1782,6 +2327,14 @@ export interface TokenUsage {
|
|
|
1782
2327
|
reasoningTokens: number;
|
|
1783
2328
|
}
|
|
1784
2329
|
|
|
2330
|
+
export type ToolReceipt = { details?: CronReceipt; family: "cron"; operation: ToolReceiptOperation; outcome: ToolReceiptOutcome; } | { details?: CodeModeReceipt; family: "codeMode"; operation: ToolReceiptOperation; outcome: ToolReceiptOutcome; } | { details?: Record<string, unknown>; family: string; operation: string; outcome: string; };
|
|
2331
|
+
|
|
2332
|
+
/** Which operation within the family the receipt describes (ADR 43399 D1/D2). Open — registered per family, never derived from the tool name. */
|
|
2333
|
+
export type ToolReceiptOperation = "create" | "delete" | "list" | "execute" | "wait" | (string & {});
|
|
2334
|
+
|
|
2335
|
+
/** What the operation did (ADR 43399 D1/D2). Open, and a **single shared vocabulary**: a value appearing in two families means the same thing in both, which is why the permitted `status` values are bound to the value here rather than per family. */
|
|
2336
|
+
export type ToolReceiptOutcome = "created" | "duplicate" | "deleted" | "missing" | "listed" | "rejected" | "completed" | "pending" | "failed" | "timedOut" | "cancelled" | (string & {});
|
|
2337
|
+
|
|
1785
2338
|
/** Optional W3C trace context, on requests in both directions only — never on responses or notifications (SS1.8). */
|
|
1786
2339
|
export interface TraceContext {
|
|
1787
2340
|
/** W3C `traceparent` string; receivers that do not trace ignore it. */
|
|
@@ -1796,7 +2349,7 @@ export interface TurnCancelParams {
|
|
|
1796
2349
|
commandId: string;
|
|
1797
2350
|
/** The target session. */
|
|
1798
2351
|
sessionId: string;
|
|
1799
|
-
/** The exact turn to cancel; omit to target the current foreground turn. */
|
|
2352
|
+
/** The exact turn to cancel; omit to target the current foreground turn. Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
|
|
1800
2353
|
turnId?: string;
|
|
1801
2354
|
}
|
|
1802
2355
|
|
|
@@ -1814,7 +2367,7 @@ export interface TurnCancelResult {
|
|
|
1814
2367
|
export interface TurnCompletedParams {
|
|
1815
2368
|
/** Turn duration; absent means unmeasured, never fabricated. */
|
|
1816
2369
|
durationMs?: number;
|
|
1817
|
-
/** Present
|
|
2370
|
+
/** Present when `terminal` is `"failed"`, except on a synthesized host-death terminal, which carries `reason` instead (tdd SS4.5.1, ADR 36635 D2): mid-turn failures reach the client here — never as a JSON-RPC error. */
|
|
1818
2371
|
error?: TurnError;
|
|
1819
2372
|
/** The runtime's free-text terminal reason, verbatim. Display and diagnostics only; never branch on it. */
|
|
1820
2373
|
reason?: string;
|
|
@@ -1847,6 +2400,20 @@ export interface TurnError {
|
|
|
1847
2400
|
/** Turn failure classes (tdd SS4.5.1, `TerminalErrorKind` plus the model-task failure class). Open. */
|
|
1848
2401
|
export type TurnErrorKind = "stepLimit" | "configError" | "projectionError" | "logError" | "workflowLaunchError" | "environmentError" | "modelError" | "launchError" | "authRequired" | (string & {});
|
|
1849
2402
|
|
|
2403
|
+
/** `turn/foregroundCompleted` params (tdd SS4.5.12): the turn's foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only at `turn/completed` / `turn/unqueued`. */
|
|
2404
|
+
export interface TurnForegroundCompletedParams {
|
|
2405
|
+
/** `reminderAgentId`s of the firing's blocking set, never empty; agent ids, never display names. Live-best-effort: reads, resume, and replay may narrow it to the linked subset. */
|
|
2406
|
+
blockingAgents: string[];
|
|
2407
|
+
/** The owning session. */
|
|
2408
|
+
sessionId: string;
|
|
2409
|
+
/** The durable records this event folded from, anchored at the first blocking link of the firing window. */
|
|
2410
|
+
sourceRange: SourceRange;
|
|
2411
|
+
/** The turn whose foreground completed. */
|
|
2412
|
+
turnId: string;
|
|
2413
|
+
/** Opaque, strictly monotonic view cursor (tdd SS4.1). */
|
|
2414
|
+
viewCursor: string;
|
|
2415
|
+
}
|
|
2416
|
+
|
|
1850
2417
|
/** One ordered content part of a turn submission (tdd SS3.2). File mentions are text, not a part type: write `@relative/path` in a text part. A structured `mention` part is reserved and currently rejected, and an unknown part type is `invalidParams` (tdd SS3.1.2, SS3.2) — which is what closes [`TurnInputPartType`]. Modelled as a discriminated flat object rather than a Rust `enum`, the convention [`crate::view::approval::ApprovalSubject`] already established for a wire union in this crate: the v1 schema model names no object-variant union shape and fails closed on one. The serialized JSON is the tdd shape either way; what a flat object cannot express is "`mediaType` is required exactly when `type` is `image`". **RULED (#22785 E4, owner, 2026-08-26): the precedent is accepted.** A strict union node kind may be funded later as a follow-up; if it is, it must cover [`crate::method::lifecycle::PendingRequestPointer`] too. `height` may only appear together with `width`. `width` may only appear together with `height`. */
|
|
1851
2418
|
export interface TurnInputPart {
|
|
1852
2419
|
/** Free-text skill arguments, optional on a `skill` part — the wire twin of what the TUI accepts after the shortcut token (tdd SS3.22.3). */
|
|
@@ -1863,12 +2430,14 @@ export interface TurnInputPart {
|
|
|
1863
2430
|
text?: string;
|
|
1864
2431
|
/** The part type. */
|
|
1865
2432
|
type: TurnInputPartType;
|
|
2433
|
+
/** The upload receipt, required on a `video` part (tdd SS3.2, SS3.33; ADR 45443 D5): the client-minted id `media/upload` echoed. */
|
|
2434
|
+
uploadId?: string;
|
|
1866
2435
|
/** Pixel width; must be provided together with `height` or not at all (tdd SS3.2). Published as a `dependentRequired` pair under #22785 E6c. */
|
|
1867
2436
|
width?: number;
|
|
1868
2437
|
}
|
|
1869
2438
|
|
|
1870
2439
|
/** The `type` discriminator of a turn input part (tdd SS3.2). Closed: an unknown part type is `invalidParams` (tdd SS3.1.2). */
|
|
1871
|
-
export type TurnInputPartType = "text" | "image" | "skill";
|
|
2440
|
+
export type TurnInputPartType = "text" | "image" | "skill" | "video";
|
|
1872
2441
|
|
|
1873
2442
|
/** `turn/interrupt` params (tdd SS3.4): the "user pressed stop" gesture, on the runtime's priority lane. */
|
|
1874
2443
|
export interface TurnInterruptParams {
|
|
@@ -1878,7 +2447,7 @@ export interface TurnInterruptParams {
|
|
|
1878
2447
|
retract?: boolean;
|
|
1879
2448
|
/** The target session. */
|
|
1880
2449
|
sessionId: string;
|
|
1881
|
-
/** The exact turn to interrupt. Omit to target the session's current foreground turn, resolved at admission; prefer passing the explicit id when you have one (tdd SS3.4). */
|
|
2450
|
+
/** The exact turn to interrupt. Omit to target the session's current foreground turn, resolved at admission; prefer passing the explicit id when you have one (tdd SS3.4). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
|
|
1882
2451
|
turnId?: string;
|
|
1883
2452
|
}
|
|
1884
2453
|
|
|
@@ -1896,6 +2465,10 @@ export interface TurnInterruptResult {
|
|
|
1896
2465
|
export interface TurnRef {
|
|
1897
2466
|
/** The `commandId` of the submit that minted it. */
|
|
1898
2467
|
commandId: string;
|
|
2468
|
+
/** `queuedTurns[]` only (#45455; ADR 45443 D7): the queued submit's presentation text, so a late joiner can render it without waiting for launch. A current host sets it on every entry it admits; absent means an older host (or a pre-feature restored entry). Never set on `activeTurn`: the running turn's text is its `userMessage` item. */
|
|
2469
|
+
displayText?: string;
|
|
2470
|
+
/** `queuedTurns[]` only: set when `displayText` was cut to the committed-surface budget, mirroring `userMessage.truncated` (tdd SS4.5.2). Absent unless `true`. */
|
|
2471
|
+
truncated?: boolean;
|
|
1899
2472
|
/** The turn's id, pre-minted per tdd SS3.1.4. */
|
|
1900
2473
|
turnId: string;
|
|
1901
2474
|
}
|
|
@@ -1953,6 +2526,8 @@ export interface TurnStartParams {
|
|
|
1953
2526
|
reasoningEffort?: ReasoningEffort;
|
|
1954
2527
|
/** The target session. */
|
|
1955
2528
|
sessionId: string;
|
|
2529
|
+
/** A sticky REPLACEMENT of the session's runtime workspace-root set, binding at this turn's launch and persisting for subsequent turns until replaced again — unlike `reasoningEffort`, which is this-turn-only. Same shape and validation as `session/start.workspaceRoots`; invalid params on an explicit `ifBusy: "steer"` submit and so is explicit `null` (the D-049 null-tolerant set is closed); omitted means "unchanged", never "reset" (tdd SS3.2, ADR 37313 D3, #37313). */
|
|
2530
|
+
workspaceRoots?: string[];
|
|
1956
2531
|
}
|
|
1957
2532
|
|
|
1958
2533
|
/** `turn/start` result (tdd SS3.2). */
|
|
@@ -1987,7 +2562,7 @@ export interface TurnStartedParams {
|
|
|
1987
2562
|
export interface TurnSteerParams {
|
|
1988
2563
|
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
1989
2564
|
commandId: string;
|
|
1990
|
-
/** The turn you believe is running. Closes the race where the turn completes or is replaced between your read and your steer: input meant for turn A can never leak into turn B (tdd SS3.3). */
|
|
2565
|
+
/** The turn you believe is running. Closes the race where the turn completes or is replaced between your read and your steer: input meant for turn A can never leak into turn B (tdd SS3.3). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`; an id that is not the running turn is refused. */
|
|
1991
2566
|
expectedTurnId: string;
|
|
1992
2567
|
/** Same content parts as `turn/start`. */
|
|
1993
2568
|
input: TurnInputPart[];
|
|
@@ -2016,7 +2591,7 @@ export interface TurnUnqueueParams {
|
|
|
2016
2591
|
commandId: string;
|
|
2017
2592
|
/** The target session. */
|
|
2018
2593
|
sessionId: string;
|
|
2019
|
-
/** The queued turn to reclaim, exactly as the queueing `turn/start`'s ack minted it and as snapshot `queuedTurns` lists it. Required, and never "whichever is newest" (tdd SS3.6). */
|
|
2594
|
+
/** The queued turn to reclaim, exactly as the queueing `turn/start`'s ack minted it and as snapshot `queuedTurns` lists it. Required, and never "whichever is newest" (tdd SS3.6). Any syntactically valid UUID: a turn from an older session may carry a v4 or v5 id. A malformed id is `invalidParams`. */
|
|
2020
2595
|
turnId: string;
|
|
2021
2596
|
}
|
|
2022
2597
|
|
|
@@ -2062,6 +2637,9 @@ export interface UnframedViewNotificationParams {
|
|
|
2062
2637
|
viewCursor: string;
|
|
2063
2638
|
}
|
|
2064
2639
|
|
|
2640
|
+
/** The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding. */
|
|
2641
|
+
export type UnknownModelReasoningEffortVariants = "unknown";
|
|
2642
|
+
|
|
2065
2643
|
/** `usage/read` result: `{usage?}` — omitted, never `null`, when the host has observed nothing (ADR 32563 D2: truthful absence, no "nothing observed" error). */
|
|
2066
2644
|
export interface UsageReadResult {
|
|
2067
2645
|
/** The last-observed subscription usage window, when one exists. */
|
|
@@ -2147,6 +2725,36 @@ export interface UserInputClarifyResult {
|
|
|
2147
2725
|
userInputId: string;
|
|
2148
2726
|
}
|
|
2149
2727
|
|
|
2728
|
+
/** `userInput/engaged` params (tdd SS5.10.4, ADR 45450 D2): a fire-and-forget engagement note — the user started interacting with a timed prompt, so the host disarms that prompt's auto-resolution countdown. No result, no errors, no `commandId`, no ledger row. */
|
|
2729
|
+
export interface UserInputEngagedParams {
|
|
2730
|
+
/** The target session. */
|
|
2731
|
+
sessionId: string;
|
|
2732
|
+
/** The prompt being engaged. */
|
|
2733
|
+
userInputId: string;
|
|
2734
|
+
}
|
|
2735
|
+
|
|
2736
|
+
/** `userInput/interrupt` params (tdd SS5.10.2, ADR 45450 D1): interrupt the named prompt carrying confirmed partial answers, then stop the turn. `answers` is optional and, when present, follows exactly the `userInput/answer` shape and limits (same `questionId` + one-of + `note` rules, same -32057 `userInputAnswerInvalid` on mismatch); absent or empty means interrupt with no confirmed answers. */
|
|
2737
|
+
export interface UserInputInterruptParams {
|
|
2738
|
+
/** Confirmed partial answers the named settlement carries. */
|
|
2739
|
+
answers?: UserInputAnswer[];
|
|
2740
|
+
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
2741
|
+
commandId: string;
|
|
2742
|
+
/** The target session. */
|
|
2743
|
+
sessionId: string;
|
|
2744
|
+
/** The prompt being interrupted. */
|
|
2745
|
+
userInputId: string;
|
|
2746
|
+
}
|
|
2747
|
+
|
|
2748
|
+
/** `userInput/interrupt` result (tdd SS5.10.2). */
|
|
2749
|
+
export interface UserInputInterruptResult {
|
|
2750
|
+
/** Echoes the client's id. */
|
|
2751
|
+
commandId: string;
|
|
2752
|
+
/** Admission status. */
|
|
2753
|
+
status: CommandStatus;
|
|
2754
|
+
/** The prompt this interruption settled. */
|
|
2755
|
+
userInputId: string;
|
|
2756
|
+
}
|
|
2757
|
+
|
|
2150
2758
|
export interface UserInputOption {
|
|
2151
2759
|
description?: string;
|
|
2152
2760
|
label: string;
|
|
@@ -2194,6 +2802,8 @@ export type UserInputSelectionMode = "single" | "multiple";
|
|
|
2194
2802
|
export interface UserInputSettledParams {
|
|
2195
2803
|
answers: UserInputAnswer[];
|
|
2196
2804
|
clarification: UserInputClarification | null;
|
|
2805
|
+
/** The decision time as RFC3339, projected from the durable settlement record's own stamp (ADR 45450 D3, ruling 2026-10-01): always present on the wire (schema-required, `null`-able); decoders still tolerate its absence (`default`, never skipped — SS5.10.3 keeps every member present), and current hosts always populate it. */
|
|
2806
|
+
decidedAt: string | null;
|
|
2197
2807
|
decidedByCommandId: string | null;
|
|
2198
2808
|
outcome: UserInputOutcome;
|
|
2199
2809
|
reason: string | null;
|
|
@@ -2312,6 +2922,10 @@ export interface WorkflowChild {
|
|
|
2312
2922
|
childId: string;
|
|
2313
2923
|
/** The child's observed duration, when recorded. */
|
|
2314
2924
|
durationMs?: number;
|
|
2925
|
+
/** The attempt's machine failure class, verbatim when recorded (open, snake_case durable runtime vocabulary — the SS1.6 casing exemption). The attempt's outcome (`terminal`, else `status`) stays authoritative, except that `"completed"` with `failureKind` present means it failed (#17769). */
|
|
2926
|
+
failureKind?: string;
|
|
2927
|
+
/** The attempt's failure reason text, verbatim when recorded except cut to at most 2,048 UTF-8 bytes ending in U+2026 when longer. */
|
|
2928
|
+
failureReason?: string;
|
|
2315
2929
|
/** The child's display label, when recorded. */
|
|
2316
2930
|
label?: string;
|
|
2317
2931
|
/** The child's phase, when recorded. */
|
|
@@ -2345,7 +2959,7 @@ export interface WorkflowChildControlParams {
|
|
|
2345
2959
|
workflowRunId: string;
|
|
2346
2960
|
}
|
|
2347
2961
|
|
|
2348
|
-
/** The shared SS3.19/SS3.20 admission-only ack: deliberately bare `{commandId, status}` — settlement arrives as the workflow item's view events, never through the ack. */
|
|
2962
|
+
/** The shared SS3.19/SS3.20/SS3.32 admission-only ack: deliberately bare `{commandId, status}` — settlement arrives as the workflow item's view events, never through the ack. */
|
|
2349
2963
|
export interface WorkflowControlResult {
|
|
2350
2964
|
/** Echoes the client's id. */
|
|
2351
2965
|
commandId: string;
|
|
@@ -2353,11 +2967,27 @@ export interface WorkflowControlResult {
|
|
|
2353
2967
|
status: CommandStatus;
|
|
2354
2968
|
}
|
|
2355
2969
|
|
|
2970
|
+
/** `workflow/pause` params (tdd SS3.32, ADR 45437 D2): pause a live workflow run, shaped exactly like `workflow/cancel`. */
|
|
2971
|
+
export interface WorkflowPauseParams {
|
|
2972
|
+
/** The SS3.1.1 idempotency handle (UUIDv7). */
|
|
2973
|
+
commandId: string;
|
|
2974
|
+
/** The target session. */
|
|
2975
|
+
sessionId: string;
|
|
2976
|
+
/** The run to pause, exactly as the `workflow` item names it (SS4.5.8); required, non-empty. */
|
|
2977
|
+
workflowRunId: string;
|
|
2978
|
+
}
|
|
2979
|
+
|
|
2980
|
+
/** `workflow`: the run's launch token budget (tdd SS4.5.8, #45449). */
|
|
2981
|
+
export interface WorkflowTokenBudget {
|
|
2982
|
+
/** The effective launch budget in tokens, verbatim from the launch fact. */
|
|
2983
|
+
total: number;
|
|
2984
|
+
}
|
|
2985
|
+
|
|
2356
2986
|
/** Every wire method in this schema (SS1.9 index). */
|
|
2357
|
-
export type MspMethod = "initialize" | "subagent/sendMessage" | "subagent/followupTask" | "subagent/interrupt" | "subagent/stop" | "subagent/resume" | "subagent/reopen" | "subagent/close" | "subagent/readResult" | "session/start" | "session/resume" | "session/fork" | "session/list" | "session/read" | "turn/start" | "turn/steer" | "turn/interrupt" | "turn/cancel" | "turn/unqueue" | "session/compact" | "session/setModel" | "session/rename" | "session/setReasoningEffort" | "session/userShell" | "model/list" | "skill/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "view/subscribe" | "view/unsubscribe" | "view/page" | "item/readOutput" | "approval/decide" | "approval/listPending" | "session/setApprovalMode" | "userInput/answer" | "userInput/cancel" | "userInput/clarify" | "usage/read";
|
|
2987
|
+
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" | "hook/list" | "plugin/list" | "task/background" | "task/stop" | "task/stopAll" | "goal/set" | "goal/edit" | "goal/clear" | "goal/pause" | "goal/resume" | "workflow/cancel" | "workflow/childControl" | "workflow/pause" | "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" | "computerUseSettings/read" | "computerUseSettings/update";
|
|
2358
2988
|
/** Every wire notification in this schema (SS1.9 index). */
|
|
2359
|
-
export type MspNotification = "initialized" | "skill/changed" | "turn/started" | "turn/completed" | "turn/retracted" | "turn/retryScheduled" | "turn/unqueued" | "item/started" | "item/updated" | "item/delta" | "item/completed" | "view/gap" | "approval/requested" | "approval/updated" | "approval/resolved" | "userInput/requested" | "userInput/settled" | "session/modelChanged" | "session/reasoningEffortChanged" | "session/statusChanged" | "session/goalChanged" | "session/todoListChanged" | "session/branchChanged" | "session/tokenUsage" | "session/contextUsage" | "session/approvalModeChanged" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
|
|
2989
|
+
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" | "session/modelRouteUnserved" | "session/nameChanged" | "session/viewHealthChanged" | "session/listChanged" | "usage/changed";
|
|
2360
2990
|
/** Every server-initiated wire request in this schema (SS5.3/SS5.10.1 index). */
|
|
2361
2991
|
export type MspServerRequest = "approval/request" | "userInput/request";
|
|
2362
2992
|
/** Every error `data.kind` in this schema's error table (SS1.6) — each code's primary kind plus its override kinds. */
|
|
2363
|
-
export type MspErrorDataKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "experimentalRequired" | "invalidParams" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";
|
|
2993
|
+
export type MspErrorDataKind = "parseError" | "invalidRequest" | "notInitialized" | "alreadyInitialized" | "methodNotFound" | "experimentalRequired" | "invalidParams" | "internal" | "pageEventTooLarge" | "outputResultTooLarge" | "overloaded" | "inputTooLarge" | "capabilityRequired" | "notFound" | "interrupted" | "cancelled" | "sessionNotFound" | "sessionInUse" | "sessionAmbiguous" | "forkBoundaryInvalid" | "sessionNotLoaded" | "sessionStreamMismatch" | "commandRejected" | "backpressured" | "skillNotFound" | "computerUseUnavailable" | "uploadNotFound" | "viewTruncated" | "outputUnavailable" | "boundaryPruned" | "boundaryUnusable" | "noBoundary" | "approvalNotFound" | "approvalAlreadyResolved" | "approvalChoiceInvalid" | "approvalRequirementStale" | "approvalReviewerUnavailable" | "userInputNotFound" | "userInputAlreadySettled" | "userInputAnswerInvalid";
|