@get-bb/plugin-sdk 0.4.30 → 0.4.35

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.
@@ -44,6 +44,7 @@ interface ProviderNativeRootsInputLike {
44
44
 
45
45
  declare const appSettingsSchema: z$1.ZodObject<{
46
46
  defaultProviderId: z$1.ZodNullable<z$1.ZodString>;
47
+ managedBranchPrefix: z$1.ZodString;
47
48
  providerOrder: z$1.ZodArray<z$1.ZodString>;
48
49
  showKeyboardHints: z$1.ZodBoolean;
49
50
  showUnhandledProviderEvents: z$1.ZodBoolean;
@@ -68,6 +69,7 @@ declare const appKeybindingOverridesSchema: z$1.ZodArray<z$1.ZodObject<{
68
69
  "modelPicker.cycleReasoning": "modelPicker.cycleReasoning";
69
70
  "modelPicker.cycleReasoningBackward": "modelPicker.cycleReasoningBackward";
70
71
  "modelPicker.toggle": "modelPicker.toggle";
72
+ "notifications.open": "notifications.open";
71
73
  "palette.open": "palette.open";
72
74
  "pane.close": "pane.close";
73
75
  "pane.focus.1": "pane.focus.1";
@@ -211,6 +213,7 @@ declare const changedMessageSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
211
213
  active: "active";
212
214
  error: "error";
213
215
  idle: "idle";
216
+ pending: "pending";
214
217
  provisioning: "provisioning";
215
218
  starting: "starting";
216
219
  stopping: "stopping";
@@ -221,6 +224,7 @@ declare const changedMessageSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
221
224
  active: "active";
222
225
  error: "error";
223
226
  idle: "idle";
227
+ pending: "pending";
224
228
  starting: "starting";
225
229
  stopping: "stopping";
226
230
  }>;
@@ -639,6 +643,67 @@ declare const pluginPendingInteractionSchema: z$1.ZodObject<{
639
643
  type PluginPendingInteraction = z$1.infer<typeof pluginPendingInteractionSchema>;
640
644
  type PendingInteraction = ProviderPendingInteraction | PluginPendingInteraction;
641
645
 
646
+ declare const providerErrorInfoSchema: z$1.ZodObject<{
647
+ category: z$1.ZodEnum<{
648
+ "active-turn-not-steerable": "active-turn-not-steerable";
649
+ "bad-request": "bad-request";
650
+ "budget-exceeded": "budget-exceeded";
651
+ "connection-failed": "connection-failed";
652
+ "context-window-exceeded": "context-window-exceeded";
653
+ "max-output-tokens": "max-output-tokens";
654
+ "max-turns": "max-turns";
655
+ "rate-limit": "rate-limit";
656
+ "stream-disconnected": "stream-disconnected";
657
+ "structured-output-retries": "structured-output-retries";
658
+ "thread-rollback-failed": "thread-rollback-failed";
659
+ "too-many-failed-attempts": "too-many-failed-attempts";
660
+ billing: "billing";
661
+ internal: "internal";
662
+ overloaded: "overloaded";
663
+ policy: "policy";
664
+ sandbox: "sandbox";
665
+ unauthorized: "unauthorized";
666
+ unknown: "unknown";
667
+ }>;
668
+ httpStatusCode: z$1.ZodNullable<z$1.ZodNumber>;
669
+ providerCode: z$1.ZodNullable<z$1.ZodString>;
670
+ }, z$1.core.$strip>;
671
+ type ProviderErrorInfo = z$1.infer<typeof providerErrorInfoSchema>;
672
+ declare const providerRateLimitStateSchema: z$1.ZodObject<{
673
+ kind: z$1.ZodEnum<{
674
+ "spend-control": "spend-control";
675
+ "subscription-window": "subscription-window";
676
+ credits: "credits";
677
+ unknown: "unknown";
678
+ }>;
679
+ overageReason: z$1.ZodNullable<z$1.ZodString>;
680
+ overageStatus: z$1.ZodNullable<z$1.ZodEnum<{
681
+ allowed: "allowed";
682
+ rejected: "rejected";
683
+ unavailable: "unavailable";
684
+ warning: "warning";
685
+ }>>;
686
+ providerId: z$1.ZodString;
687
+ reachedReason: z$1.ZodNullable<z$1.ZodString>;
688
+ status: z$1.ZodEnum<{
689
+ allowed: "allowed";
690
+ blocked: "blocked";
691
+ unknown: "unknown";
692
+ warning: "warning";
693
+ }>;
694
+ windows: z$1.ZodArray<z$1.ZodObject<{
695
+ label: z$1.ZodNullable<z$1.ZodString>;
696
+ providerKey: z$1.ZodNullable<z$1.ZodString>;
697
+ resetsAtMs: z$1.ZodNullable<z$1.ZodNumber>;
698
+ status: z$1.ZodEnum<{
699
+ allowed: "allowed";
700
+ blocked: "blocked";
701
+ unknown: "unknown";
702
+ warning: "warning";
703
+ }>;
704
+ }, z$1.core.$strip>>;
705
+ }, z$1.core.$strip>;
706
+ type ProviderRateLimitState = z$1.infer<typeof providerRateLimitStateSchema>;
642
707
  declare const threadEventSchema: z$1.ZodPipe<z$1.ZodUnknown, z$1.ZodUnion<readonly [z$1.ZodIntersection<z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
643
708
  threadId: z$1.ZodString;
644
709
  type: z$1.ZodLiteral<"thread/started">;
@@ -2322,7 +2387,6 @@ declare const threadEventSchema: z$1.ZodPipe<z$1.ZodUnknown, z$1.ZodUnion<readon
2322
2387
  threadId: z$1.ZodString;
2323
2388
  type: z$1.ZodLiteral<"client/thread/start">;
2324
2389
  }, z$1.core.$strip>, z$1.ZodObject<{
2325
- continuationOfRequestId: z$1.ZodOptional<z$1.ZodString>;
2326
2390
  direction: z$1.ZodLiteral<"outbound">;
2327
2391
  execution: z$1.ZodObject<{
2328
2392
  model: z$1.ZodString;
@@ -2529,6 +2593,8 @@ declare const threadEventSchema: z$1.ZodPipe<z$1.ZodUnknown, z$1.ZodUnion<readon
2529
2593
  params: z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>;
2530
2594
  }, z$1.core.$strip>;
2531
2595
  requestId: z$1.ZodString;
2596
+ retryAttempt: z$1.ZodOptional<z$1.ZodNumber>;
2597
+ retryOfRequestId: z$1.ZodOptional<z$1.ZodString>;
2532
2598
  senderThreadId: z$1.ZodNullable<z$1.ZodString>;
2533
2599
  source: z$1.ZodEnum<{
2534
2600
  spawn: "spawn";
@@ -2969,6 +3035,18 @@ declare const threadEventSchema: z$1.ZodPipe<z$1.ZodUnknown, z$1.ZodUnion<readon
2969
3035
  type ThreadEvent = z$1.infer<typeof threadEventSchema>;
2970
3036
  type ThreadEventType = ThreadEvent["type"];
2971
3037
 
3038
+ declare const projectSchema: z$1.ZodObject<{
3039
+ createdAt: z$1.ZodNumber;
3040
+ gitRemoteUrl: z$1.ZodNullable<z$1.ZodString>;
3041
+ id: z$1.ZodString;
3042
+ kind: z$1.ZodEnum<{
3043
+ personal: "personal";
3044
+ standard: "standard";
3045
+ }>;
3046
+ name: z$1.ZodString;
3047
+ updatedAt: z$1.ZodNumber;
3048
+ }, z$1.core.$strip>;
3049
+ type Project = z$1.infer<typeof projectSchema>;
2972
3050
  declare const projectSourceSchema: z$1.ZodObject<{
2973
3051
  createdAt: z$1.ZodNumber;
2974
3052
  hostId: z$1.ZodString;
@@ -3085,6 +3163,11 @@ declare const promptInputSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
3085
3163
  }>>;
3086
3164
  }, z$1.core.$strip>], "type">;
3087
3165
  type PromptInput = z$1.infer<typeof promptInputSchema>;
3166
+ declare const callerExecutionInputSourceSchema: z$1.ZodEnum<{
3167
+ "client-preference": "client-preference";
3168
+ explicit: "explicit";
3169
+ }>;
3170
+ type CallerExecutionInputSource = z$1.infer<typeof callerExecutionInputSourceSchema>;
3088
3171
  declare const resolvedThreadExecutionOptionsSchema: z$1.ZodObject<{
3089
3172
  model: z$1.ZodString;
3090
3173
  permissionMode: z$1.ZodEnum<{
@@ -3139,6 +3222,18 @@ declare const projectExecutionDefaultsSchema: z$1.ZodObject<{
3139
3222
  }, z$1.core.$strip>;
3140
3223
  type ProjectExecutionDefaults = z$1.infer<typeof projectExecutionDefaultsSchema>;
3141
3224
 
3225
+ /**
3226
+ * Who owns a wait, as the denormalized `waitHolder` column stores it.
3227
+ *
3228
+ * This exists only because the orphan sweep and the per-plugin release both
3229
+ * need an indexed equality lookup ("every row this plugin is holding"), which
3230
+ * a JSON `waitingOn` cannot serve. It is written by the same single writer
3231
+ * that writes `waitingOn`, derived from it — never set independently — so the
3232
+ * two cannot drift. Core waits have no holder.
3233
+ */
3234
+ declare const queuedMessageWaitHolderSchema: z$1.ZodTemplateLiteral<`plugin:${string}`>;
3235
+ type QueuedMessageWaitHolder = z$1.infer<typeof queuedMessageWaitHolderSchema>;
3236
+
3142
3237
  declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
3143
3238
  type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
3144
3239
 
@@ -3261,6 +3356,7 @@ declare const threadStatusSchema: z$1.ZodEnum<{
3261
3356
  active: "active";
3262
3357
  error: "error";
3263
3358
  idle: "idle";
3359
+ pending: "pending";
3264
3360
  starting: "starting";
3265
3361
  stopping: "stopping";
3266
3362
  }>;
@@ -3364,9 +3460,19 @@ declare const threadQueuedMessageSchema: z$1.ZodObject<{
3364
3460
  }>>;
3365
3461
  }, z$1.core.$strip>], "type">>;
3366
3462
  createdAt: z$1.ZodNumber;
3463
+ editable: z$1.ZodBoolean;
3464
+ failureReason: z$1.ZodNullable<z$1.ZodString>;
3367
3465
  groupWithNext: z$1.ZodBoolean;
3368
3466
  id: z$1.ZodString;
3369
3467
  model: z$1.ZodString;
3468
+ payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
3469
+ kind: z$1.ZodLiteral<"inline">;
3470
+ }, z$1.core.$strip>, z$1.ZodObject<{
3471
+ attempt: z$1.ZodNumber;
3472
+ kind: z$1.ZodLiteral<"retry">;
3473
+ reason: z$1.ZodString;
3474
+ retryOfTurnRequestId: z$1.ZodString;
3475
+ }, z$1.core.$strip>], "kind">;
3370
3476
  permissionMode: z$1.ZodEnum<{
3371
3477
  "accept-edits": "accept-edits";
3372
3478
  auto: "auto";
@@ -3382,11 +3488,31 @@ declare const threadQueuedMessageSchema: z$1.ZodObject<{
3382
3488
  ultracode: "ultracode";
3383
3489
  xhigh: "xhigh";
3384
3490
  }>;
3491
+ sendAt: z$1.ZodNullable<z$1.ZodNumber>;
3385
3492
  serviceTier: z$1.ZodEnum<{
3386
3493
  default: "default";
3387
3494
  fast: "fast";
3388
3495
  }>;
3496
+ threadId: z$1.ZodString;
3389
3497
  updatedAt: z$1.ZodNumber;
3498
+ waitingOn: z$1.ZodNullable<z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
3499
+ kind: z$1.ZodLiteral<"time">;
3500
+ }, z$1.core.$strip>, z$1.ZodObject<{
3501
+ kind: z$1.ZodLiteral<"thread-busy">;
3502
+ }, z$1.core.$strip>, z$1.ZodObject<{
3503
+ kind: z$1.ZodLiteral<"turn-starting">;
3504
+ }, z$1.core.$strip>, z$1.ZodObject<{
3505
+ kind: z$1.ZodLiteral<"provisioning">;
3506
+ }, z$1.core.$strip>, z$1.ZodObject<{
3507
+ hostName: z$1.ZodString;
3508
+ kind: z$1.ZodLiteral<"host-offline">;
3509
+ }, z$1.core.$strip>, z$1.ZodObject<{
3510
+ kind: z$1.ZodLiteral<"interaction">;
3511
+ }, z$1.core.$strip>, z$1.ZodObject<{
3512
+ kind: z$1.ZodLiteral<"plugin">;
3513
+ pluginId: z$1.ZodString;
3514
+ reason: z$1.ZodString;
3515
+ }, z$1.core.$strip>], "kind">>;
3390
3516
  }, z$1.core.$strip>;
3391
3517
  type ThreadQueuedMessage = z$1.infer<typeof threadQueuedMessageSchema>;
3392
3518
 
@@ -3851,6 +3977,11 @@ declare const projectWithThreadsResponseSchema: z$1.ZodObject<{
3851
3977
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
3852
3978
  projectId: z$1.ZodString;
3853
3979
  providerId: z$1.ZodString;
3980
+ queuedWork: z$1.ZodEnum<{
3981
+ failed: "failed";
3982
+ none: "none";
3983
+ waiting: "waiting";
3984
+ }>;
3854
3985
  runtime: z$1.ZodObject<{
3855
3986
  displayStatus: z$1.ZodEnum<{
3856
3987
  "host-reconnecting": "host-reconnecting";
@@ -3858,6 +3989,7 @@ declare const projectWithThreadsResponseSchema: z$1.ZodObject<{
3858
3989
  active: "active";
3859
3990
  error: "error";
3860
3991
  idle: "idle";
3992
+ pending: "pending";
3861
3993
  provisioning: "provisioning";
3862
3994
  starting: "starting";
3863
3995
  stopping: "stopping";
@@ -3870,6 +4002,7 @@ declare const projectWithThreadsResponseSchema: z$1.ZodObject<{
3870
4002
  active: "active";
3871
4003
  error: "error";
3872
4004
  idle: "idle";
4005
+ pending: "pending";
3873
4006
  starting: "starting";
3874
4007
  stopping: "stopping";
3875
4008
  }>;
@@ -3960,6 +4093,11 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
3960
4093
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
3961
4094
  projectId: z$1.ZodString;
3962
4095
  providerId: z$1.ZodString;
4096
+ queuedWork: z$1.ZodEnum<{
4097
+ failed: "failed";
4098
+ none: "none";
4099
+ waiting: "waiting";
4100
+ }>;
3963
4101
  runtime: z$1.ZodObject<{
3964
4102
  displayStatus: z$1.ZodEnum<{
3965
4103
  "host-reconnecting": "host-reconnecting";
@@ -3967,6 +4105,7 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
3967
4105
  active: "active";
3968
4106
  error: "error";
3969
4107
  idle: "idle";
4108
+ pending: "pending";
3970
4109
  provisioning: "provisioning";
3971
4110
  starting: "starting";
3972
4111
  stopping: "stopping";
@@ -3979,6 +4118,7 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
3979
4118
  active: "active";
3980
4119
  error: "error";
3981
4120
  idle: "idle";
4121
+ pending: "pending";
3982
4122
  starting: "starting";
3983
4123
  stopping: "stopping";
3984
4124
  }>;
@@ -4067,6 +4207,11 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
4067
4207
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
4068
4208
  projectId: z$1.ZodString;
4069
4209
  providerId: z$1.ZodString;
4210
+ queuedWork: z$1.ZodEnum<{
4211
+ failed: "failed";
4212
+ none: "none";
4213
+ waiting: "waiting";
4214
+ }>;
4070
4215
  runtime: z$1.ZodObject<{
4071
4216
  displayStatus: z$1.ZodEnum<{
4072
4217
  "host-reconnecting": "host-reconnecting";
@@ -4074,6 +4219,7 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
4074
4219
  active: "active";
4075
4220
  error: "error";
4076
4221
  idle: "idle";
4222
+ pending: "pending";
4077
4223
  provisioning: "provisioning";
4078
4224
  starting: "starting";
4079
4225
  stopping: "stopping";
@@ -4086,6 +4232,7 @@ declare const sidebarBootstrapResponseSchema: z$1.ZodObject<{
4086
4232
  active: "active";
4087
4233
  error: "error";
4088
4234
  idle: "idle";
4235
+ pending: "pending";
4089
4236
  starting: "starting";
4090
4237
  stopping: "stopping";
4091
4238
  }>;
@@ -8179,6 +8326,7 @@ declare const systemConfigResponseSchema: z$1.ZodObject<{
8179
8326
  "modelPicker.cycleReasoning": "modelPicker.cycleReasoning";
8180
8327
  "modelPicker.cycleReasoningBackward": "modelPicker.cycleReasoningBackward";
8181
8328
  "modelPicker.toggle": "modelPicker.toggle";
8329
+ "notifications.open": "notifications.open";
8182
8330
  "palette.open": "palette.open";
8183
8331
  "pane.close": "pane.close";
8184
8332
  "pane.focus.1": "pane.focus.1";
@@ -8277,6 +8425,7 @@ declare const systemConfigResponseSchema: z$1.ZodObject<{
8277
8425
  }, z$1.core.$strip>;
8278
8426
  generalSettings: z$1.ZodObject<{
8279
8427
  defaultProviderId: z$1.ZodNullable<z$1.ZodString>;
8428
+ managedBranchPrefix: z$1.ZodString;
8280
8429
  providerOrder: z$1.ZodArray<z$1.ZodString>;
8281
8430
  showKeyboardHints: z$1.ZodBoolean;
8282
8431
  showUnhandledProviderEvents: z$1.ZodBoolean;
@@ -8300,6 +8449,7 @@ declare const systemConfigResponseSchema: z$1.ZodObject<{
8300
8449
  "modelPicker.cycleReasoning": "modelPicker.cycleReasoning";
8301
8450
  "modelPicker.cycleReasoningBackward": "modelPicker.cycleReasoningBackward";
8302
8451
  "modelPicker.toggle": "modelPicker.toggle";
8452
+ "notifications.open": "notifications.open";
8303
8453
  "palette.open": "palette.open";
8304
8454
  "pane.close": "pane.close";
8305
8455
  "pane.focus.1": "pane.focus.1";
@@ -8373,6 +8523,7 @@ declare const systemConfigResponseSchema: z$1.ZodObject<{
8373
8523
  "modelPicker.cycleReasoning": "modelPicker.cycleReasoning";
8374
8524
  "modelPicker.cycleReasoningBackward": "modelPicker.cycleReasoningBackward";
8375
8525
  "modelPicker.toggle": "modelPicker.toggle";
8526
+ "notifications.open": "notifications.open";
8376
8527
  "palette.open": "palette.open";
8377
8528
  "pane.close": "pane.close";
8378
8529
  "pane.focus.1": "pane.focus.1";
@@ -9573,6 +9724,14 @@ interface TimelineTurnRow extends TimelineRowBase {
9573
9724
  type TimelineSourceRow = TimelineConversationRow | TimelineWorkRow | TimelineSystemRow;
9574
9725
  type TimelineRow = TimelineSourceRow | TimelineTurnRow;
9575
9726
 
9727
+ declare const threadCreateOriginSchema: z$1.ZodEnum<{
9728
+ app: "app";
9729
+ cli: "cli";
9730
+ plugin: "plugin";
9731
+ sdk: "sdk";
9732
+ }>;
9733
+ type ThreadCreateOrigin = z$1.infer<typeof threadCreateOriginSchema>;
9734
+ type ExecutionInputFieldSource = CallerExecutionInputSource;
9576
9735
  declare const createExecutionInputSourcesSchema: z$1.ZodObject<{
9577
9736
  model: z$1.ZodOptional<z$1.ZodEnum<{
9578
9737
  "client-preference": "client-preference";
@@ -9596,6 +9755,14 @@ declare const createExecutionInputSourcesSchema: z$1.ZodObject<{
9596
9755
  }>>;
9597
9756
  }, z$1.core.$strict>;
9598
9757
  type CreateExecutionInputSources = z$1.infer<typeof createExecutionInputSourcesSchema>;
9758
+ declare const startedOnBehalfOfSchema: z$1.ZodObject<{
9759
+ initiator: z$1.ZodEnum<{
9760
+ agent: "agent";
9761
+ system: "system";
9762
+ }>;
9763
+ senderThreadId: z$1.ZodString;
9764
+ }, z$1.core.$strip>;
9765
+ type StartedOnBehalfOf = z$1.infer<typeof startedOnBehalfOfSchema>;
9599
9766
  declare const createThreadRequestSchema: z$1.ZodObject<{
9600
9767
  environment: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
9601
9768
  environmentId: z$1.ZodString;
@@ -9760,6 +9927,7 @@ declare const createThreadRequestSchema: z$1.ZodObject<{
9760
9927
  xhigh: "xhigh";
9761
9928
  }>>;
9762
9929
  sectionId: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
9930
+ sendAt: z$1.ZodOptional<z$1.ZodNumber>;
9763
9931
  serviceTier: z$1.ZodOptional<z$1.ZodEnum<{
9764
9932
  default: "default";
9765
9933
  fast: "fast";
@@ -10093,6 +10261,7 @@ declare const sendMessageRequestSchema: z$1.ZodObject<{
10093
10261
  ultracode: "ultracode";
10094
10262
  xhigh: "xhigh";
10095
10263
  }>>;
10264
+ sendAt: z$1.ZodOptional<z$1.ZodNumber>;
10096
10265
  senderThreadId: z$1.ZodOptional<z$1.ZodString>;
10097
10266
  serviceTier: z$1.ZodOptional<z$1.ZodEnum<{
10098
10267
  default: "default";
@@ -10100,14 +10269,38 @@ declare const sendMessageRequestSchema: z$1.ZodObject<{
10100
10269
  }>>;
10101
10270
  }, z$1.core.$strip>;
10102
10271
  type SendMessageRequest = z$1.infer<typeof sendMessageRequestSchema>;
10103
- declare const sendMessageResponseSchema: z$1.ZodObject<{
10104
- delivery: z$1.ZodEnum<{
10105
- deferred: "deferred";
10106
- queued: "queued";
10107
- sent: "sent";
10108
- }>;
10272
+ /**
10273
+ * A discriminated union rather than a flat record with nullable extras: a
10274
+ * `sent` message has no queued row and no wait, and modelling those as "null
10275
+ * for now" would invite every caller to check fields that cannot exist.
10276
+ */
10277
+ declare const sendMessageResponseSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10278
+ delivery: z$1.ZodLiteral<"sent">;
10109
10279
  ok: z$1.ZodLiteral<true>;
10110
- }, z$1.core.$strip>;
10280
+ }, z$1.core.$strip>, z$1.ZodObject<{
10281
+ delivery: z$1.ZodLiteral<"queued">;
10282
+ ok: z$1.ZodLiteral<true>;
10283
+ queuedMessageId: z$1.ZodString;
10284
+ sendAt: z$1.ZodNullable<z$1.ZodNumber>;
10285
+ waitingOn: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10286
+ kind: z$1.ZodLiteral<"time">;
10287
+ }, z$1.core.$strip>, z$1.ZodObject<{
10288
+ kind: z$1.ZodLiteral<"thread-busy">;
10289
+ }, z$1.core.$strip>, z$1.ZodObject<{
10290
+ kind: z$1.ZodLiteral<"turn-starting">;
10291
+ }, z$1.core.$strip>, z$1.ZodObject<{
10292
+ kind: z$1.ZodLiteral<"provisioning">;
10293
+ }, z$1.core.$strip>, z$1.ZodObject<{
10294
+ hostName: z$1.ZodString;
10295
+ kind: z$1.ZodLiteral<"host-offline">;
10296
+ }, z$1.core.$strip>, z$1.ZodObject<{
10297
+ kind: z$1.ZodLiteral<"interaction">;
10298
+ }, z$1.core.$strip>, z$1.ZodObject<{
10299
+ kind: z$1.ZodLiteral<"plugin">;
10300
+ pluginId: z$1.ZodString;
10301
+ reason: z$1.ZodString;
10302
+ }, z$1.core.$strip>], "kind">;
10303
+ }, z$1.core.$strip>], "delivery">;
10111
10304
  type SendMessageResponse = z$1.infer<typeof sendMessageResponseSchema>;
10112
10305
  declare const editMessageRequestSchema: z$1.ZodObject<{
10113
10306
  executionInputSources: z$1.ZodOptional<z$1.ZodObject<{
@@ -10240,6 +10433,45 @@ declare const editMessageResponseSchema: z$1.ZodObject<{
10240
10433
  requestSequence: z$1.ZodNumber;
10241
10434
  }, z$1.core.$strict>;
10242
10435
  type EditMessageResponse = z$1.infer<typeof editMessageResponseSchema>;
10436
+ /**
10437
+ * What a retry did, mirroring `sendMessageResponseSchema`: a retry is a
10438
+ * dispatch of a turn that already exists, so it is delivered or queued on
10439
+ * exactly the same terms as a send. The two retry-specific facts ride along,
10440
+ * because a caller that let the server pick the turn has no other way to learn
10441
+ * which one it picked.
10442
+ */
10443
+ declare const retryTurnResponseSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10444
+ attempt: z$1.ZodNumber;
10445
+ delivery: z$1.ZodLiteral<"sent">;
10446
+ ok: z$1.ZodLiteral<true>;
10447
+ turnRequestId: z$1.ZodString;
10448
+ }, z$1.core.$strip>, z$1.ZodObject<{
10449
+ attempt: z$1.ZodNumber;
10450
+ delivery: z$1.ZodLiteral<"queued">;
10451
+ ok: z$1.ZodLiteral<true>;
10452
+ queuedMessageId: z$1.ZodString;
10453
+ sendAt: z$1.ZodNullable<z$1.ZodNumber>;
10454
+ turnRequestId: z$1.ZodString;
10455
+ waitingOn: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10456
+ kind: z$1.ZodLiteral<"time">;
10457
+ }, z$1.core.$strip>, z$1.ZodObject<{
10458
+ kind: z$1.ZodLiteral<"thread-busy">;
10459
+ }, z$1.core.$strip>, z$1.ZodObject<{
10460
+ kind: z$1.ZodLiteral<"turn-starting">;
10461
+ }, z$1.core.$strip>, z$1.ZodObject<{
10462
+ kind: z$1.ZodLiteral<"provisioning">;
10463
+ }, z$1.core.$strip>, z$1.ZodObject<{
10464
+ hostName: z$1.ZodString;
10465
+ kind: z$1.ZodLiteral<"host-offline">;
10466
+ }, z$1.core.$strip>, z$1.ZodObject<{
10467
+ kind: z$1.ZodLiteral<"interaction">;
10468
+ }, z$1.core.$strip>, z$1.ZodObject<{
10469
+ kind: z$1.ZodLiteral<"plugin">;
10470
+ pluginId: z$1.ZodString;
10471
+ reason: z$1.ZodString;
10472
+ }, z$1.core.$strip>], "kind">;
10473
+ }, z$1.core.$strip>], "delivery">;
10474
+ type RetryTurnResponse = z$1.infer<typeof retryTurnResponseSchema>;
10243
10475
  declare const createQueuedMessageRequestSchema: z$1.ZodObject<{
10244
10476
  executionInputSources: z$1.ZodOptional<z$1.ZodObject<{
10245
10477
  model: z$1.ZodOptional<z$1.ZodEnum<{
@@ -10551,9 +10783,19 @@ declare const sendQueuedMessageResponseSchema: z$1.ZodObject<{
10551
10783
  }>>;
10552
10784
  }, z$1.core.$strip>], "type">>;
10553
10785
  createdAt: z$1.ZodNumber;
10786
+ editable: z$1.ZodBoolean;
10787
+ failureReason: z$1.ZodNullable<z$1.ZodString>;
10554
10788
  groupWithNext: z$1.ZodBoolean;
10555
10789
  id: z$1.ZodString;
10556
10790
  model: z$1.ZodString;
10791
+ payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10792
+ kind: z$1.ZodLiteral<"inline">;
10793
+ }, z$1.core.$strip>, z$1.ZodObject<{
10794
+ attempt: z$1.ZodNumber;
10795
+ kind: z$1.ZodLiteral<"retry">;
10796
+ reason: z$1.ZodString;
10797
+ retryOfTurnRequestId: z$1.ZodString;
10798
+ }, z$1.core.$strip>], "kind">;
10557
10799
  permissionMode: z$1.ZodEnum<{
10558
10800
  "accept-edits": "accept-edits";
10559
10801
  auto: "auto";
@@ -10569,11 +10811,31 @@ declare const sendQueuedMessageResponseSchema: z$1.ZodObject<{
10569
10811
  ultracode: "ultracode";
10570
10812
  xhigh: "xhigh";
10571
10813
  }>;
10814
+ sendAt: z$1.ZodNullable<z$1.ZodNumber>;
10572
10815
  serviceTier: z$1.ZodEnum<{
10573
10816
  default: "default";
10574
10817
  fast: "fast";
10575
10818
  }>;
10819
+ threadId: z$1.ZodString;
10576
10820
  updatedAt: z$1.ZodNumber;
10821
+ waitingOn: z$1.ZodNullable<z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
10822
+ kind: z$1.ZodLiteral<"time">;
10823
+ }, z$1.core.$strip>, z$1.ZodObject<{
10824
+ kind: z$1.ZodLiteral<"thread-busy">;
10825
+ }, z$1.core.$strip>, z$1.ZodObject<{
10826
+ kind: z$1.ZodLiteral<"turn-starting">;
10827
+ }, z$1.core.$strip>, z$1.ZodObject<{
10828
+ kind: z$1.ZodLiteral<"provisioning">;
10829
+ }, z$1.core.$strip>, z$1.ZodObject<{
10830
+ hostName: z$1.ZodString;
10831
+ kind: z$1.ZodLiteral<"host-offline">;
10832
+ }, z$1.core.$strip>, z$1.ZodObject<{
10833
+ kind: z$1.ZodLiteral<"interaction">;
10834
+ }, z$1.core.$strip>, z$1.ZodObject<{
10835
+ kind: z$1.ZodLiteral<"plugin">;
10836
+ pluginId: z$1.ZodString;
10837
+ reason: z$1.ZodString;
10838
+ }, z$1.core.$strip>], "kind">>;
10577
10839
  }, z$1.core.$strip>;
10578
10840
  }, z$1.core.$strip>;
10579
10841
  type SendQueuedMessageResponse = z$1.infer<typeof sendQueuedMessageResponseSchema>;
@@ -10610,6 +10872,11 @@ declare const threadListResponseSchema: z$1.ZodArray<z$1.ZodObject<{
10610
10872
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
10611
10873
  projectId: z$1.ZodString;
10612
10874
  providerId: z$1.ZodString;
10875
+ queuedWork: z$1.ZodEnum<{
10876
+ failed: "failed";
10877
+ none: "none";
10878
+ waiting: "waiting";
10879
+ }>;
10613
10880
  runtime: z$1.ZodObject<{
10614
10881
  displayStatus: z$1.ZodEnum<{
10615
10882
  "host-reconnecting": "host-reconnecting";
@@ -10617,6 +10884,7 @@ declare const threadListResponseSchema: z$1.ZodArray<z$1.ZodObject<{
10617
10884
  active: "active";
10618
10885
  error: "error";
10619
10886
  idle: "idle";
10887
+ pending: "pending";
10620
10888
  provisioning: "provisioning";
10621
10889
  starting: "starting";
10622
10890
  stopping: "stopping";
@@ -10629,6 +10897,7 @@ declare const threadListResponseSchema: z$1.ZodArray<z$1.ZodObject<{
10629
10897
  active: "active";
10630
10898
  error: "error";
10631
10899
  idle: "idle";
10900
+ pending: "pending";
10632
10901
  starting: "starting";
10633
10902
  stopping: "stopping";
10634
10903
  }>;
@@ -10702,6 +10971,11 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10702
10971
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
10703
10972
  projectId: z$1.ZodString;
10704
10973
  providerId: z$1.ZodString;
10974
+ queuedWork: z$1.ZodEnum<{
10975
+ failed: "failed";
10976
+ none: "none";
10977
+ waiting: "waiting";
10978
+ }>;
10705
10979
  runtime: z$1.ZodObject<{
10706
10980
  displayStatus: z$1.ZodEnum<{
10707
10981
  "host-reconnecting": "host-reconnecting";
@@ -10709,6 +10983,7 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10709
10983
  active: "active";
10710
10984
  error: "error";
10711
10985
  idle: "idle";
10986
+ pending: "pending";
10712
10987
  provisioning: "provisioning";
10713
10988
  starting: "starting";
10714
10989
  stopping: "stopping";
@@ -10721,6 +10996,7 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10721
10996
  active: "active";
10722
10997
  error: "error";
10723
10998
  idle: "idle";
10999
+ pending: "pending";
10724
11000
  starting: "starting";
10725
11001
  stopping: "stopping";
10726
11002
  }>;
@@ -10785,6 +11061,11 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10785
11061
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
10786
11062
  projectId: z$1.ZodString;
10787
11063
  providerId: z$1.ZodString;
11064
+ queuedWork: z$1.ZodEnum<{
11065
+ failed: "failed";
11066
+ none: "none";
11067
+ waiting: "waiting";
11068
+ }>;
10788
11069
  runtime: z$1.ZodObject<{
10789
11070
  displayStatus: z$1.ZodEnum<{
10790
11071
  "host-reconnecting": "host-reconnecting";
@@ -10792,6 +11073,7 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10792
11073
  active: "active";
10793
11074
  error: "error";
10794
11075
  idle: "idle";
11076
+ pending: "pending";
10795
11077
  provisioning: "provisioning";
10796
11078
  starting: "starting";
10797
11079
  stopping: "stopping";
@@ -10804,6 +11086,7 @@ declare const threadSearchResponseSchema: z$1.ZodObject<{
10804
11086
  active: "active";
10805
11087
  error: "error";
10806
11088
  idle: "idle";
11089
+ pending: "pending";
10807
11090
  starting: "starting";
10808
11091
  stopping: "stopping";
10809
11092
  }>;
@@ -10838,6 +11121,7 @@ declare const threadResponseSchema: z$1.ZodObject<{
10838
11121
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
10839
11122
  projectId: z$1.ZodString;
10840
11123
  providerId: z$1.ZodString;
11124
+ queuedMessageCount: z$1.ZodNumber;
10841
11125
  runtime: z$1.ZodObject<{
10842
11126
  displayStatus: z$1.ZodEnum<{
10843
11127
  "host-reconnecting": "host-reconnecting";
@@ -10845,6 +11129,7 @@ declare const threadResponseSchema: z$1.ZodObject<{
10845
11129
  active: "active";
10846
11130
  error: "error";
10847
11131
  idle: "idle";
11132
+ pending: "pending";
10848
11133
  provisioning: "provisioning";
10849
11134
  starting: "starting";
10850
11135
  stopping: "stopping";
@@ -10857,6 +11142,7 @@ declare const threadResponseSchema: z$1.ZodObject<{
10857
11142
  active: "active";
10858
11143
  error: "error";
10859
11144
  idle: "idle";
11145
+ pending: "pending";
10860
11146
  starting: "starting";
10861
11147
  stopping: "stopping";
10862
11148
  }>;
@@ -10940,6 +11226,7 @@ declare const threadWithIncludesResponseSchema: z$1.ZodObject<{
10940
11226
  pinnedAt: z$1.ZodNullable<z$1.ZodNumber>;
10941
11227
  projectId: z$1.ZodString;
10942
11228
  providerId: z$1.ZodString;
11229
+ queuedMessageCount: z$1.ZodNumber;
10943
11230
  runtime: z$1.ZodObject<{
10944
11231
  displayStatus: z$1.ZodEnum<{
10945
11232
  "host-reconnecting": "host-reconnecting";
@@ -10947,6 +11234,7 @@ declare const threadWithIncludesResponseSchema: z$1.ZodObject<{
10947
11234
  active: "active";
10948
11235
  error: "error";
10949
11236
  idle: "idle";
11237
+ pending: "pending";
10950
11238
  provisioning: "provisioning";
10951
11239
  starting: "starting";
10952
11240
  stopping: "stopping";
@@ -10959,6 +11247,7 @@ declare const threadWithIncludesResponseSchema: z$1.ZodObject<{
10959
11247
  active: "active";
10960
11248
  error: "error";
10961
11249
  idle: "idle";
11250
+ pending: "pending";
10962
11251
  starting: "starting";
10963
11252
  stopping: "stopping";
10964
11253
  }>;
@@ -11301,9 +11590,19 @@ declare const threadQueuedMessageListResponseSchema: z$1.ZodArray<z$1.ZodObject<
11301
11590
  }>>;
11302
11591
  }, z$1.core.$strip>], "type">>;
11303
11592
  createdAt: z$1.ZodNumber;
11593
+ editable: z$1.ZodBoolean;
11594
+ failureReason: z$1.ZodNullable<z$1.ZodString>;
11304
11595
  groupWithNext: z$1.ZodBoolean;
11305
11596
  id: z$1.ZodString;
11306
11597
  model: z$1.ZodString;
11598
+ payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
11599
+ kind: z$1.ZodLiteral<"inline">;
11600
+ }, z$1.core.$strip>, z$1.ZodObject<{
11601
+ attempt: z$1.ZodNumber;
11602
+ kind: z$1.ZodLiteral<"retry">;
11603
+ reason: z$1.ZodString;
11604
+ retryOfTurnRequestId: z$1.ZodString;
11605
+ }, z$1.core.$strip>], "kind">;
11307
11606
  permissionMode: z$1.ZodEnum<{
11308
11607
  "accept-edits": "accept-edits";
11309
11608
  auto: "auto";
@@ -11319,11 +11618,31 @@ declare const threadQueuedMessageListResponseSchema: z$1.ZodArray<z$1.ZodObject<
11319
11618
  ultracode: "ultracode";
11320
11619
  xhigh: "xhigh";
11321
11620
  }>;
11621
+ sendAt: z$1.ZodNullable<z$1.ZodNumber>;
11322
11622
  serviceTier: z$1.ZodEnum<{
11323
11623
  default: "default";
11324
11624
  fast: "fast";
11325
11625
  }>;
11626
+ threadId: z$1.ZodString;
11326
11627
  updatedAt: z$1.ZodNumber;
11628
+ waitingOn: z$1.ZodNullable<z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
11629
+ kind: z$1.ZodLiteral<"time">;
11630
+ }, z$1.core.$strip>, z$1.ZodObject<{
11631
+ kind: z$1.ZodLiteral<"thread-busy">;
11632
+ }, z$1.core.$strip>, z$1.ZodObject<{
11633
+ kind: z$1.ZodLiteral<"turn-starting">;
11634
+ }, z$1.core.$strip>, z$1.ZodObject<{
11635
+ kind: z$1.ZodLiteral<"provisioning">;
11636
+ }, z$1.core.$strip>, z$1.ZodObject<{
11637
+ hostName: z$1.ZodString;
11638
+ kind: z$1.ZodLiteral<"host-offline">;
11639
+ }, z$1.core.$strip>, z$1.ZodObject<{
11640
+ kind: z$1.ZodLiteral<"interaction">;
11641
+ }, z$1.core.$strip>, z$1.ZodObject<{
11642
+ kind: z$1.ZodLiteral<"plugin">;
11643
+ pluginId: z$1.ZodString;
11644
+ reason: z$1.ZodString;
11645
+ }, z$1.core.$strip>], "kind">>;
11327
11646
  }, z$1.core.$strip>>;
11328
11647
  type ThreadQueuedMessageListResponse = z$1.infer<typeof threadQueuedMessageListResponseSchema>;
11329
11648
  declare const threadChildSummaryResponseSchema: z$1.ZodObject<{
@@ -11427,6 +11746,35 @@ declare const threadListQuerySchema: z$1.ZodObject<{
11427
11746
  }>>;
11428
11747
  }, z$1.core.$strip>;
11429
11748
  type ThreadListQuery = z$1.infer<typeof threadListQuerySchema>;
11749
+ /**
11750
+ * Grouping for `GET /threads/count`. Omitted, the route answers one total.
11751
+ * `host` groups by the host the thread's environment lives on; a thread with
11752
+ * no environment yet counts under the `null` key.
11753
+ */
11754
+ declare const threadCountGroupBySchema: z$1.ZodEnum<{
11755
+ host: "host";
11756
+ project: "project";
11757
+ provider: "provider";
11758
+ }>;
11759
+ type ThreadCountGroupBy = z$1.infer<typeof threadCountGroupBySchema>;
11760
+ /**
11761
+ * `total` is always the count of every matching thread. `groups` is present
11762
+ * exactly when `groupBy` was requested — an ungrouped count has no group list,
11763
+ * rather than one anonymous group.
11764
+ */
11765
+ declare const threadCountResponseSchema: z$1.ZodObject<{
11766
+ groups: z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
11767
+ count: z$1.ZodNumber;
11768
+ key: z$1.ZodNullable<z$1.ZodString>;
11769
+ }, z$1.core.$strip>>>;
11770
+ total: z$1.ZodNumber;
11771
+ }, z$1.core.$strip>;
11772
+ type ThreadCountResponse = z$1.infer<typeof threadCountResponseSchema>;
11773
+ declare const threadRunningResponseSchema: z$1.ZodArray<z$1.ZodObject<{
11774
+ hostId: z$1.ZodNullable<z$1.ZodString>;
11775
+ id: z$1.ZodString;
11776
+ }, z$1.core.$strip>>;
11777
+ type ThreadRunningResponse = z$1.infer<typeof threadRunningResponseSchema>;
11430
11778
  declare const threadSearchQuerySchema: z$1.ZodObject<{
11431
11779
  limitPerGroup: z$1.ZodOptional<z$1.ZodString>;
11432
11780
  query: z$1.ZodString;
@@ -12076,7 +12424,7 @@ interface PluginRpcError {
12076
12424
  issues?: PluginRpcValidationIssue[];
12077
12425
  }
12078
12426
  /**
12079
- * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
12427
+ * The validator-neutral subset of Standard Schema v1 used by plugin contracts.
12080
12428
  * Zod 4 schemas implement this interface directly; other validators can do
12081
12429
  * the same without becoming part of BB's public protocol.
12082
12430
  */
@@ -12196,6 +12544,56 @@ interface PluginPendingInteractionProps {
12196
12544
  */
12197
12545
  interface PluginSidebarFooterActionProps {
12198
12546
  }
12547
+ /** Display and accessibility metadata for a host-owned sidebar shortcut. */
12548
+ interface ExperimentalSidebarNavigationShortcut {
12549
+ label: string;
12550
+ ariaKeyShortcuts: string;
12551
+ }
12552
+ /** Host-owned behavior represented by one sidebar navigation item. */
12553
+ type ExperimentalSidebarNavigationAction = {
12554
+ kind: "new-thread";
12555
+ } | {
12556
+ kind: "search-threads";
12557
+ } | {
12558
+ kind: "open-extensions";
12559
+ } | {
12560
+ kind: "open-plugin-panel";
12561
+ pluginId: string;
12562
+ panelId: string;
12563
+ };
12564
+ /** Semantic icon identity for one sidebar navigation item. */
12565
+ type ExperimentalSidebarNavigationIcon = {
12566
+ kind: "host";
12567
+ name: "extensions" | "new-thread" | "search";
12568
+ } | {
12569
+ kind: "plugin";
12570
+ pluginId: string;
12571
+ icon: string | null;
12572
+ };
12573
+ /** One host-owned destination or action a plugin may arrange. */
12574
+ interface ExperimentalSidebarNavigationItem {
12575
+ id: string;
12576
+ label: string;
12577
+ icon: ExperimentalSidebarNavigationIcon;
12578
+ action: ExperimentalSidebarNavigationAction;
12579
+ isDisabled: boolean;
12580
+ shortcut: ExperimentalSidebarNavigationShortcut | null;
12581
+ experimental_splitProps: {
12582
+ onPointerDown?: (event: react.PointerEvent<HTMLElement>) => void;
12583
+ };
12584
+ }
12585
+ /** How the host should activate a sidebar navigation item. */
12586
+ interface ExperimentalSidebarNavigationActivationOptions {
12587
+ openInSplit: boolean;
12588
+ }
12589
+ /** Props passed to an `experimental_sidebarNavigation` component. */
12590
+ interface ExperimentalSidebarNavigationProps {
12591
+ items: readonly ExperimentalSidebarNavigationItem[];
12592
+ activeItemId: string | null;
12593
+ isCompactViewport: boolean;
12594
+ experimental_activate(itemId: string, options: ExperimentalSidebarNavigationActivationOptions): void;
12595
+ experimental_Original: ComponentType;
12596
+ }
12199
12597
  /**
12200
12598
  * Props passed to an `experimental_threadList` component — the sidebar's
12201
12599
  * scrolling thread area, replaced wholesale by one plugin.
@@ -12973,6 +13371,16 @@ interface PluginThreadListRegistration {
12973
13371
  description?: string;
12974
13372
  component: ComponentType<PluginThreadListProps>;
12975
13373
  }
13374
+ /** Replace the bounded navigation controls above the sidebar thread list. */
13375
+ interface ExperimentalSidebarNavigationRegistration {
13376
+ /** Unique within the plugin; letters, digits, `-`, `_`. */
13377
+ id: string;
13378
+ /** Label shown in Settings → Appearance and capability details. */
13379
+ title: string;
13380
+ /** Optional one-line description shown with the provider choice. */
13381
+ description?: string;
13382
+ component: ComponentType<ExperimentalSidebarNavigationProps>;
13383
+ }
12976
13384
  /**
12977
13385
  * Register this plugin as a viewer/editor for file extensions. By default,
12978
13386
  * matching files render the first applicable opener in deterministic slot
@@ -13274,6 +13682,8 @@ interface PluginAppSlots {
13274
13682
  experimental_newThreadPanelAction(registration: PluginNewThreadPanelActionRegistration): void;
13275
13683
  pendingInteraction(registration: PluginPendingInteractionRegistration): void;
13276
13684
  sidebarFooterAction(registration: PluginSidebarFooterActionRegistration): void;
13685
+ /** Replace the bounded sidebar navigation controls. */
13686
+ experimental_sidebarNavigation(registration: ExperimentalSidebarNavigationRegistration): void;
13277
13687
  /**
13278
13688
  * Replace the sidebar's thread list (see
13279
13689
  * {@link PluginThreadListRegistration}). Experimental: see
@@ -13570,6 +13980,51 @@ interface PluginComposerApi {
13570
13980
  insertMention(mention: PluginComposerMention): void;
13571
13981
  /** Focus the composer caret at the end of the draft. */
13572
13982
  focus(): void;
13983
+ /**
13984
+ * Submit this composer's draft through the composer's OWN submit pipeline,
13985
+ * queued until `sendAt` instead of dispatched now.
13986
+ *
13987
+ * This is a real submission, not a plugin-issued send: the host builds the
13988
+ * request exactly as pressing Enter would, so the draft's attachments and
13989
+ * @-mentions, and — in the new-thread composer — the provider, model,
13990
+ * reasoning level, service tier, permission mode and environment the user
13991
+ * has selected on screen, all travel with it. A plugin cannot assemble that
13992
+ * tuple itself, which is why sending from the backend instead would silently
13993
+ * run the message with different settings than the ones in front of the user.
13994
+ *
13995
+ * In a thread composer the message is queued as a row instead of being
13996
+ * sent or queued for the next idle moment. In the new-thread composer the
13997
+ * thread is created `pending` and its first message becomes the queued row.
13998
+ * Either way the resulting row is core's: the queued card above the
13999
+ * composer, the countdown, Send now and Delete all work with no further
14000
+ * plugin involvement.
14001
+ *
14002
+ * Resolves once the host has accepted the submission and cleared the draft.
14003
+ * Rejects when the composer refused to submit — a scope with no submit
14004
+ * pipeline (a queued-message editor, a side chat), an empty draft, or a
14005
+ * composer that is not ready (still loading its execution defaults, missing
14006
+ * an environment). The rejection's message is safe to show to the user.
14007
+ * Failures of the underlying request are reported by bb's own submit error
14008
+ * handling and restore the draft, exactly as an interactive failure does.
14009
+ *
14010
+ * Experimental: see docs/api_to_audit.md.
14011
+ */
14012
+ experimental_submit(options: ExperimentalComposerSubmitOptions): Promise<void>;
14013
+ }
14014
+ /**
14015
+ * What `experimental_submit` does differently from pressing Enter.
14016
+ *
14017
+ * There is deliberately no zero-argument overload and no "submit now" arm: a
14018
+ * plugin that wants a draft sent immediately is asking for the affordance the
14019
+ * user already has, and handing plugins an unconditional "send this draft"
14020
+ * button is a much larger surface than scheduling needs.
14021
+ */
14022
+ interface ExperimentalComposerSubmitOptions {
14023
+ /**
14024
+ * Epoch ms the submission should dispatch at. Must be in the future; the
14025
+ * host does not second-guess how far ahead it is.
14026
+ */
14027
+ sendAt: number;
13573
14028
  }
13574
14029
  /**
13575
14030
  * A consumer-supplied action on the messages of one `ThreadChat` instance,
@@ -13637,7 +14092,13 @@ interface ThreadChatProps {
13637
14092
  */
13638
14093
  messageActions?: readonly ThreadChatMessageAction[];
13639
14094
  }
13640
- /** The controlled execution selection resolved by the picker. */
14095
+ /**
14096
+ * The controlled execution selection resolved by the picker.
14097
+ *
14098
+ * Deliberately a single concrete shape, not a union: this value exists to be
14099
+ * forwarded verbatim to `bb.sdk.threads.spawn`, so it must name a real
14100
+ * provider and model.
14101
+ */
13641
14102
  interface ExperimentalProviderModelPickerValue {
13642
14103
  providerId: string;
13643
14104
  model: string;
@@ -13724,6 +14185,14 @@ interface NewThreadRequest {
13724
14185
  executionInputSources: CreateExecutionInputSources;
13725
14186
  environment: CreateThreadEnvironmentArgs;
13726
14187
  input: PromptInput[];
14188
+ /**
14189
+ * Epoch ms the first turn should dispatch at. Present only when the
14190
+ * submission came from `useComposer().experimental_submit` — a scheduled
14191
+ * create — and absent otherwise, which is what makes an ordinary submission
14192
+ * start work at once. Forward it to `threads.spawn` unchanged: the thread is
14193
+ * created `pending` and its first message is queued as a row until then.
14194
+ */
14195
+ sendAt?: number;
13727
14196
  }
13728
14197
  /**
13729
14198
  * Props of the host-owned `experimental_NewThreadComposer` component — bb's
@@ -14974,6 +15443,26 @@ interface ThreadListArgs {
14974
15443
  interface ThreadSearchArgs extends ThreadSearchQuery {
14975
15444
  signal?: AbortSignal;
14976
15445
  }
15446
+ /**
15447
+ * Counting is a server-side `SELECT count(*)`: a caller that only needs "how
15448
+ * many threads are running on this host" must never page rows through
15449
+ * `threads.list`, which would both cost memory and miscount past its limit.
15450
+ *
15451
+ * Every filter is genuinely absent by default. `parentThreadId` is
15452
+ * three-valued: omitted does not filter on parentage at all, the
15453
+ * `THREAD_COUNT_ROOT_PARENT` sentinel (`"none"`) counts root threads only, and
15454
+ * any other value counts that parent's children. Archived and deleted threads
15455
+ * are excluded by the route.
15456
+ */
15457
+ interface ThreadCountArgs {
15458
+ groupBy?: ThreadCountGroupBy;
15459
+ hostId?: string;
15460
+ parentThreadId?: string;
15461
+ projectId?: string;
15462
+ providerId?: string;
15463
+ signal?: AbortSignal;
15464
+ status?: ThreadStatus;
15465
+ }
14977
15466
  interface ThreadResolveMentionsArgs extends ResolveThreadMentionsRequest {
14978
15467
  signal?: AbortSignal;
14979
15468
  }
@@ -14983,6 +15472,30 @@ interface ThreadGetArgs {
14983
15472
  threadId: string;
14984
15473
  }
14985
15474
  type ThreadGetResult = ThreadResponse | ThreadWithIncludesResponse;
15475
+ type ThreadCountResult = ThreadCountResponse;
15476
+ /**
15477
+ * The threads occupying capacity right now — canonical status `starting` or
15478
+ * `active`, archived and deleted excluded, hidden included (a hidden thread
15479
+ * burns a real slot). Each row is just `id` and `hostId` — the machine whose
15480
+ * pool the thread occupies, from its environment or, before one is attached,
15481
+ * from the start intent it was admitted with; null only when neither names
15482
+ * one. Anything else a policy needs it fetches by id.
15483
+ *
15484
+ * **Exact inside the `message.dispatch` hook, a snapshot everywhere else.**
15485
+ * Hook passes are serialized under one server-wide lock and a cleared first
15486
+ * attempt commits its `pending -> starting` flip before that lock releases, so
15487
+ * a handler reading this sees every admission granted ahead of it in the same
15488
+ * burst — which is what makes "five quick creates against a limit of two" hold
15489
+ * three of them instead of admitting all five. Read from a background service,
15490
+ * a timer or a `turn.failed` listener it is an ordinary query racing with every
15491
+ * concurrent dispatch, exactly like {@link ThreadsArea.count}.
15492
+ *
15493
+ * One boundary: a warm follow-up admitted on an already-live `idle` thread
15494
+ * flips `idle -> active` inside the send transaction, just AFTER the lock
15495
+ * releases. First-dispatch admissions are exact; a burst of follow-ups to
15496
+ * distinct idle threads can momentarily under-report.
15497
+ */
15498
+ type ThreadRunningResult = ThreadRunningResponse;
14986
15499
  type ThreadListResult = ThreadListResponse;
14987
15500
  type ThreadSearchResult = ThreadSearchResponse;
14988
15501
  type ThreadResolveMentionsResult = ResolveThreadMentionsResponse;
@@ -15007,6 +15520,7 @@ type ThreadDeleteResult = {
15007
15520
  ok: true;
15008
15521
  };
15009
15522
  type ThreadSendResult = SendMessageResponse;
15523
+ type ThreadRetryResult = RetryTurnResponse;
15010
15524
  type ThreadEditMessageResult = EditMessageResponse;
15011
15525
  type ThreadStopResult = {
15012
15526
  ok: true;
@@ -15033,6 +15547,7 @@ type ThreadQueuedMessageDeleteResult = {
15033
15547
  type ThreadQueuedMessageReorderResult = ThreadQueuedMessageListResponse;
15034
15548
  type ThreadQueuedMessageSendResult = SendQueuedMessageResponse;
15035
15549
  type ThreadQueuedMessageGroupBoundaryResult = ThreadQueuedMessageListResponse;
15550
+ type ThreadQueueListResult = ThreadQueuedMessageListResponse;
15036
15551
  type ThreadTabsResult = ThreadTabsResponse;
15037
15552
  type ThreadTabsUpdateResult = ThreadTabsResponse;
15038
15553
  type ThreadStorageFilesResult = ThreadStorageFileListResponse;
@@ -15071,6 +15586,22 @@ interface ThreadSendArgs extends SendMessageRequest {
15071
15586
  interface ThreadEditMessageArgs extends EditMessageRequest {
15072
15587
  threadId: string;
15073
15588
  }
15589
+ interface ThreadRetryArgs {
15590
+ threadId: string;
15591
+ /**
15592
+ * The failed turn to re-submit. Omitted means the thread's most recent turn,
15593
+ * which is the one whose failure put it in `error`; naming one asserts which
15594
+ * failure you decided on and fails if the thread has moved on since.
15595
+ */
15596
+ turnRequestId?: string;
15597
+ /**
15598
+ * Epoch ms to retry at. Omitted attempts the retry now — it may still queue
15599
+ * behind a busy thread or a plugin wait, like any other dispatch.
15600
+ */
15601
+ sendAt?: number;
15602
+ /** Why the turn is being retried, shown verbatim on the queued row. */
15603
+ reason?: string;
15604
+ }
15074
15605
  interface ThreadActionArgs {
15075
15606
  threadId: string;
15076
15607
  }
@@ -15104,6 +15635,17 @@ interface ThreadQueuedMessageReorderArgs extends ThreadQueuedMessageTargetArgs,
15104
15635
  interface ThreadQueuedMessageGroupBoundaryArgs extends SetQueuedMessageGroupBoundaryRequest {
15105
15636
  threadId: string;
15106
15637
  }
15638
+ /**
15639
+ * Both filters are genuinely absent by default: no filter lists every live
15640
+ * queued row in the workspace, which is what `bb thread queue list` with no
15641
+ * thread and a limiter plugin's own bookkeeping ask for.
15642
+ */
15643
+ interface ThreadQueueListArgs {
15644
+ /** `plugin:<id>` — every row that plugin is holding the wait on. */
15645
+ waitHolder?: QueuedMessageWaitHolder;
15646
+ signal?: AbortSignal;
15647
+ threadId?: string;
15648
+ }
15107
15649
  interface ThreadStorageFilesArgs extends ThreadStorageFilesQuery {
15108
15650
  signal?: AbortSignal;
15109
15651
  threadId: string;
@@ -15223,6 +15765,18 @@ interface ThreadTabsArea {
15223
15765
  get(args: ThreadStatusArgs): Promise<ThreadTabsResult>;
15224
15766
  update(args: ThreadTabsUpdateArgs): Promise<ThreadTabsUpdateResult>;
15225
15767
  }
15768
+ /**
15769
+ * Queued rows across every thread.
15770
+ *
15771
+ * The per-thread list, send-now, edit, reorder and delete all live on
15772
+ * `queuedMessages`, which is where a row's own operations belong. This area
15773
+ * exists for the one question a thread-scoped list cannot answer: "what is
15774
+ * queued right now, anywhere" — a workspace-wide pending view, or a plugin
15775
+ * recovering the rows it is holding after a restart.
15776
+ */
15777
+ interface ThreadQueueArea {
15778
+ list(args?: ThreadQueueListArgs): Promise<ThreadQueueListResult>;
15779
+ }
15226
15780
  interface ThreadsArea {
15227
15781
  archive(args: ThreadActionArgs): Promise<ThreadArchiveResult>;
15228
15782
  archiveAll(args: ThreadActionArgs): Promise<ThreadArchiveAllResult>;
@@ -15231,14 +15785,19 @@ interface ThreadsArea {
15231
15785
  cancelPlan(args: ThreadActionArgs): Promise<ThreadBannerActionResult>;
15232
15786
  clearGoal(args: ThreadActionArgs): Promise<ThreadBannerActionResult>;
15233
15787
  conversationOutline(args: ThreadStatusArgs): Promise<ThreadConversationOutlineResult>;
15788
+ count(args?: ThreadCountArgs): Promise<ThreadCountResult>;
15234
15789
  defaultExecutionOptions(args: ThreadStatusArgs): Promise<ThreadDefaultExecutionOptionsResult>;
15235
15790
  delete(args: ThreadDeleteArgs): Promise<ThreadDeleteResult>;
15236
15791
  editMessage(args: ThreadEditMessageArgs): Promise<ThreadEditMessageResult>;
15237
15792
  events: ThreadEventsArea;
15238
15793
  fork(args: ThreadForkArgs): Promise<ThreadForkResult>;
15239
15794
  get(args: ThreadGetArgs): Promise<ThreadGetResult>;
15795
+ queue: ThreadQueueArea;
15240
15796
  interactions: ThreadInteractionsArea;
15241
15797
  list(args?: ThreadListArgs): Promise<ThreadListResult>;
15798
+ listRunning(args?: {
15799
+ signal?: AbortSignal;
15800
+ }): Promise<ThreadRunningResult>;
15242
15801
  markRead(args: ThreadActionArgs): Promise<ThreadReadStateResult>;
15243
15802
  markUnread(args: ThreadActionArgs): Promise<ThreadReadStateResult>;
15244
15803
  open(args: ThreadOpenArgs): Promise<ThreadOpenResult>;
@@ -15249,6 +15808,12 @@ interface ThreadsArea {
15249
15808
  queuedMessages: ThreadQueuedMessagesArea;
15250
15809
  reorderPinned(args: ThreadPinOrderArgs): Promise<ThreadPinOrderResult>;
15251
15810
  resolveMentions(args: ThreadResolveMentionsArgs): Promise<ThreadResolveMentionsResult>;
15811
+ /**
15812
+ * Re-submit a failed turn. The retry is an ordinary dispatch attempt, so a
15813
+ * `sendAt` in the future queues it on the clock and a `message.dispatch` hook
15814
+ * can still hold it; the response says which of the two happened.
15815
+ */
15816
+ retry(args: ThreadRetryArgs): Promise<ThreadRetryResult>;
15252
15817
  search(args: ThreadSearchArgs): Promise<ThreadSearchResult>;
15253
15818
  send(args: ThreadSendArgs): Promise<ThreadSendResult>;
15254
15819
  spawn(args: ThreadSpawnArgs): Promise<ThreadSpawnResult>;
@@ -15418,11 +15983,6 @@ interface PluginLogger {
15418
15983
  warn(message: string): void;
15419
15984
  error(message: string): void;
15420
15985
  }
15421
- /**
15422
- * Declarative settings descriptors (`bb.settings.define`). Deliberately plain
15423
- * data — not zod — so the host can render settings forms and the CLI can
15424
- * parse values without executing plugin code.
15425
- */
15426
15986
  type PluginSettingDescriptor = {
15427
15987
  type: "string";
15428
15988
  label: string;
@@ -15434,22 +15994,30 @@ type PluginSettingDescriptor = {
15434
15994
  * be multi-line.
15435
15995
  */
15436
15996
  experimental_multiline?: boolean;
15997
+ /** Synchronously validate without transforming a proposed value. */
15998
+ experimental_schema?: StandardSchemaV1<string, string>;
15437
15999
  default?: string;
15438
16000
  } | {
15439
16001
  type: "boolean";
15440
16002
  label: string;
15441
16003
  description?: string;
16004
+ /** Synchronously validate without transforming a proposed value. */
16005
+ experimental_schema?: StandardSchemaV1<boolean, boolean>;
15442
16006
  default?: boolean;
15443
16007
  } | {
15444
16008
  type: "select";
15445
16009
  label: string;
15446
16010
  description?: string;
15447
16011
  options: string[];
16012
+ /** Synchronously validate without transforming a proposed value. */
16013
+ experimental_schema?: StandardSchemaV1<string, string>;
15448
16014
  default?: string;
15449
16015
  } | {
15450
16016
  type: "project";
15451
16017
  label: string;
15452
16018
  description?: string;
16019
+ /** Synchronously validate without transforming a proposed value. */
16020
+ experimental_schema?: StandardSchemaV1<string, string>;
15453
16021
  default?: string;
15454
16022
  };
15455
16023
  type PluginSettingDescriptors = Record<string, PluginSettingDescriptor>;
@@ -15466,7 +16034,11 @@ type PluginSettingValueOf<D extends PluginSettingDescriptor> = D extends {
15466
16034
  interface PluginSettingsHandle<Ds extends Record<string, PluginSettingDescriptor>> {
15467
16035
  /** Load-safe: callable inside the factory. */
15468
16036
  get(): Promise<PluginSettingsValues<Ds>>;
15469
- /** Fires after values change through the settings route/CLI. */
16037
+ /** Validate and persist this handle's fields; `null` unsets a stored value. */
16038
+ experimental_set(values: Partial<{
16039
+ [K in keyof Ds]: PluginSettingValueOf<Ds[K]> | null;
16040
+ }>): Promise<PluginSettingsValues<Ds>>;
16041
+ /** Fires after effective values change through any settings write. */
15470
16042
  onChange(listener: (next: PluginSettingsValues<Ds>, prev: PluginSettingsValues<Ds>) => void): void;
15471
16043
  }
15472
16044
  interface PluginSettings {
@@ -15499,9 +16071,66 @@ interface PluginStorage {
15499
16071
  migrate(db: Database.Database, statements: string[]): void;
15500
16072
  }
15501
16073
  /**
15502
- * Thread lifecycle events a plugin can observe (design §4.5). Observe-only:
15503
- * handlers run fire-and-forget after the transition is applied and can never
15504
- * block or veto it. `thread` is the same public DTO GET /threads/:id serves.
16074
+ * Why a turn failed, assembled by core from the failed turn's own records so a
16075
+ * listener never has to replay the event log to find out.
16076
+ *
16077
+ * Ids and failure facts only. There is no thread DTO and no copy of the
16078
+ * message that failed: a retry re-submits the turn BY REFERENCE
16079
+ * (`bb.sdk.threads.retry`), so the id is the whole of what a policy needs, and
16080
+ * anything else about the thread is one `bb.sdk.threads.get` away and fresher
16081
+ * for being read when it is used.
16082
+ */
16083
+ interface PluginTurnFailedEvent {
16084
+ /** The thread the failed turn ran on. */
16085
+ threadId: string;
16086
+ /**
16087
+ * The failed turn's `client/turn/requested` id — what
16088
+ * `bb.sdk.threads.retry` takes as `turnRequestId`. On a retry's failure this
16089
+ * is the RETRY's id; core walks back to the request the chain started from
16090
+ * when it queues the next attempt.
16091
+ */
16092
+ requestId: string;
16093
+ /** The provider turn, when the failure happened inside one. */
16094
+ turnId: string | null;
16095
+ /**
16096
+ * The failure's structured classification: the provider's own report when
16097
+ * the failure happened inside a turn, or the typed rejection code (a rate
16098
+ * limit, an auth failure) when the provider refused the request at the
16099
+ * door. Null when neither carried one, so a retry policy must handle null
16100
+ * rather than assume.
16101
+ */
16102
+ errorInfo: ProviderErrorInfo | null;
16103
+ /**
16104
+ * Whether the provider accepted the turn's input before failing. True is a
16105
+ * mid-stream failure — the input is already part of the provider's
16106
+ * conversation, so core's retry continues it instead of re-sending the
16107
+ * blocks. False is a request the provider never took, which a retry
16108
+ * re-sends verbatim.
16109
+ */
16110
+ inputAccepted: boolean;
16111
+ /**
16112
+ * The most recent rate-limit snapshot this thread's provider reported, or
16113
+ * null when the provider reports no windows.
16114
+ */
16115
+ rateLimits: ProviderRateLimitState | null;
16116
+ /**
16117
+ * Which attempt just failed: 1 is the original dispatch, 2 the first retry.
16118
+ * A policy caps its own retries by comparing against this.
16119
+ */
16120
+ attemptNumber: number;
16121
+ }
16122
+ /**
16123
+ * Lifecycle events a plugin can observe with `bb.events.on` (design §4.5).
16124
+ *
16125
+ * **Events are announcements core makes.** Something already happened; a
16126
+ * handler is told about it and whatever it returns is IGNORED. Handlers run
16127
+ * fire-and-forget after the change is applied and can never block or veto it.
16128
+ * The surface that *can* is `bb.experimental_hooks`, where core asks a
16129
+ * question and acts on the answer — the same split git draws between its
16130
+ * post-commit and pre-commit hooks.
16131
+ *
16132
+ * `thread` is the same public DTO GET /threads/:id serves and `entry` is the
16133
+ * queued row GET /threads/:id/queued-messages serves.
15505
16134
  */
15506
16135
  interface PluginThreadEventPayloads {
15507
16136
  /** Fired after a thread row is created. */
@@ -15532,9 +16161,252 @@ interface PluginThreadEventPayloads {
15532
16161
  "thread.deleted": {
15533
16162
  thread: ThreadResponse;
15534
16163
  };
16164
+ /**
16165
+ * Fired after a dispatch attempt is queued as a row — by a `message.dispatch`
16166
+ * hook's `wait` decision, by a `sendAt` in the future, or by a core wait (the
16167
+ * thread is busy, its turn is still starting, provisioning, or awaiting an
16168
+ * interaction).
16169
+ *
16170
+ * Every listener sees every queued row, not just the ones it is holding: an
16171
+ * observer that only wants its own filters on
16172
+ * `entry.waitingOn?.kind === "plugin" && entry.waitingOn.pluginId === bb.pluginId`.
16173
+ *
16174
+ * A re-queue fires this again with the new wait, because a row that moved
16175
+ * from one wait to another is news to whoever was waiting on the old one.
16176
+ */
16177
+ "message.queued": {
16178
+ entry: ThreadQueuedMessage;
16179
+ };
16180
+ /**
16181
+ * Fired after a queued row's waits all cleared and it dispatched. The turn
16182
+ * it carried runs after this, so a handler must not assume it has started.
16183
+ */
16184
+ "message.dispatched": {
16185
+ entry: ThreadQueuedMessage;
16186
+ };
16187
+ /**
16188
+ * Fired after a turn failed and the thread has already landed in `error`.
16189
+ *
16190
+ * An announcement, not a question: the failure stands exactly as core
16191
+ * applied it, and a listener that wants another attempt asks for one with
16192
+ * `bb.sdk.threads.retry({ threadId, turnRequestId, sendAt })`. That retry is
16193
+ * an ordinary dispatch attempt, so it still passes the `message.dispatch`
16194
+ * hook — a retry coming back after a rate-limit window respects a limiter
16195
+ * that is at capacity instead of jumping the queue.
16196
+ */
16197
+ "turn.failed": PluginTurnFailedEvent;
15535
16198
  }
15536
16199
  type PluginThreadEventName = keyof PluginThreadEventPayloads;
15537
16200
  type PluginThreadEventHandler<E extends PluginThreadEventName> = (payload: PluginThreadEventPayloads[E]) => void | Promise<void>;
16201
+ /**
16202
+ * What a `message.dispatch` hook answers.
16203
+ *
16204
+ * `proceed` lets the attempt continue. `wait` QUEUES the message as a row
16205
+ * whose `waitingOn` names this plugin and carries `reason` verbatim; the
16206
+ * row stays queued until `sendAt` comes due, capacity frees, the user sends
16207
+ * it now, or the orphan sweep clears it because this plugin is no longer
16208
+ * running. `sendAt` (epoch ms) sets the row's own `sendAt`, so core's due sweep
16209
+ * re-attempts at that instant without the plugin holding a timer of its own —
16210
+ * which is what a rate-limit window wants. `reject` refuses the attempt
16211
+ * outright: `message` is shown to the user verbatim.
16212
+ *
16213
+ * There is deliberately no "handled it myself" answer and no amendment arm —
16214
+ * a hook is a decision, never an owner or an author of the work.
16215
+ */
16216
+ type MessageDispatchHookDecision = {
16217
+ action: "proceed";
16218
+ } | {
16219
+ action: "wait";
16220
+ reason: string;
16221
+ sendAt?: number | null;
16222
+ } | {
16223
+ action: "reject";
16224
+ message: string;
16225
+ };
16226
+ /**
16227
+ * The execution tuple as core resolved it before this hook ran. `model` and
16228
+ * the three option fields are null only when no default has been resolved for
16229
+ * them yet; `providerId` is always resolved.
16230
+ */
16231
+ interface PluginDispatchExecution {
16232
+ providerId: string;
16233
+ model: string | null;
16234
+ reasoningLevel: ReasoningLevel | null;
16235
+ serviceTier: ServiceTier | null;
16236
+ permissionMode: PermissionMode | null;
16237
+ }
16238
+ /**
16239
+ * Where each execution value came from. `explicit` is a user choice,
16240
+ * `client-preference` a remembered client default, and null means core
16241
+ * resolved it from project/provider defaults. A hook that must not act against
16242
+ * a deliberate choice checks for `explicit` here.
16243
+ */
16244
+ interface PluginDispatchExecutionSources {
16245
+ providerId: ExecutionInputFieldSource | null;
16246
+ model: ExecutionInputFieldSource | null;
16247
+ reasoningLevel: ExecutionInputFieldSource | null;
16248
+ serviceTier: ExecutionInputFieldSource | null;
16249
+ permissionMode: ExecutionInputFieldSource | null;
16250
+ }
16251
+ /**
16252
+ * The prompt this dispatch carries. `blocks` is the message itself; `text` is
16253
+ * the concatenated text of its text blocks, which is what a rules-based hook
16254
+ * actually wants to match on.
16255
+ */
16256
+ interface PluginDispatchInput {
16257
+ blocks: readonly PromptInput[];
16258
+ text: string;
16259
+ }
16260
+ /**
16261
+ * How this attempt would reach the provider.
16262
+ *
16263
+ * `start-turn` is a dispatch that begins a turn: a thread's first message, a
16264
+ * plain send to an idle or `pending` thread, or a steer-mode message that
16265
+ * found no running turn to join. `join-turn` is an injection into a turn that
16266
+ * is already executing.
16267
+ *
16268
+ * Decision powers are identical for both — a steer is hooked exactly like a
16269
+ * send, uniformly. A hook that limits concurrency proceeds on `join-turn`: the
16270
+ * thread already holds its slot, so joining it asks for nothing new.
16271
+ */
16272
+ type PluginDispatchAttemptKind = "join-turn" | "start-turn";
16273
+ /**
16274
+ * What core hands a `message.dispatch` hook: the one checkpoint, run before a
16275
+ * message reaches a provider. The exception is a user's explicit Send-now on a
16276
+ * queued row, which bypasses the pass by design — it is the user overriding
16277
+ * policy, and a policy that could veto its own override would not be one.
16278
+ *
16279
+ * It runs identically whether the attempt is inline (someone just sent) or
16280
+ * from a drain (a queued row became eligible again), and whether the message
16281
+ * is a thread's first, a follow-up, a steer, or a retry of a failed turn. A
16282
+ * handler must therefore be idempotent for one logical dispatch: passes re-run
16283
+ * on every drain, on restart, and on retry.
16284
+ */
16285
+ interface MessageDispatchHookContext {
16286
+ /**
16287
+ * The target thread. Never null: thread creation is unhooked — it is a cheap
16288
+ * row — so by the time the first message is decided about, the thread exists
16289
+ * in `pending`, with its provider resolved and nothing provisioned.
16290
+ */
16291
+ thread: ThreadResponse;
16292
+ project: Project;
16293
+ /** Null until an environment is chosen (a queued or not-yet-provisioned thread). */
16294
+ environment: Environment | null;
16295
+ /**
16296
+ * The machine the work will run on. Resolved from the environment when one
16297
+ * is attached, and before that from the start intent the thread was created
16298
+ * with — so a per-host policy counts a cold start against the pool it is
16299
+ * about to occupy. Null only when neither names a machine.
16300
+ */
16301
+ host: Host | null;
16302
+ input: PluginDispatchInput;
16303
+ requestedExecution: PluginDispatchExecution;
16304
+ /** Where each execution value came from. */
16305
+ executionSources: PluginDispatchExecutionSources;
16306
+ /** Whether this attempt starts a turn or joins a running one. */
16307
+ attempt: PluginDispatchAttemptKind;
16308
+ /**
16309
+ * The queued row this attempt is re-trying, or null when the attempt is
16310
+ * inline and no row has ever existed for it.
16311
+ *
16312
+ * This is how a hook tells a fresh send from a re-attempt of something it
16313
+ * already decided about — the replacement for the old
16314
+ * `isReleaseReevaluation`/`hold` pair. A hook that counts in-flight work
16315
+ * should treat the two identically; a hook that logs should not
16316
+ * double-count.
16317
+ */
16318
+ queuedMessage: ThreadQueuedMessage | null;
16319
+ /** How the dispatch was requested; null for internal/core-driven sends. */
16320
+ origin: ThreadCreateOrigin | null;
16321
+ originPluginId: string | null;
16322
+ startedOnBehalfOf: StartedOnBehalfOf | null;
16323
+ parentThreadId: string | null;
16324
+ }
16325
+ /**
16326
+ * The hooks a plugin can answer, each mapping its key to the context core
16327
+ * hands the handler and the decision core acts on. `on()` and the handler type
16328
+ * derive from this map — and so does the server's hook registry — so a
16329
+ * half-added hook does not compile.
16330
+ *
16331
+ * One hook today: `message.dispatch`, THE admission checkpoint, run identically
16332
+ * for a thread's first message, a follow-up, a steer, a retry, and every
16333
+ * re-attempt a drain makes. It replaced the earlier `thread.create` +
16334
+ * `turn.submit` pair, whose split was an accident of where the code happened to
16335
+ * branch rather than a difference a plugin needed to see — the attempt's own
16336
+ * `attempt` kind carries what actually differs.
16337
+ */
16338
+ interface PluginHookSignatures {
16339
+ "message.dispatch": {
16340
+ context: MessageDispatchHookContext;
16341
+ decision: MessageDispatchHookDecision;
16342
+ };
16343
+ }
16344
+ type PluginHookName = keyof PluginHookSignatures;
16345
+ type PluginHookHandler<K extends PluginHookName> = (context: PluginHookSignatures[K]["context"]) => PluginHookSignatures[K]["decision"] | Promise<PluginHookSignatures[K]["decision"]>;
16346
+ interface PluginHooks {
16347
+ /**
16348
+ * Answer a hook.
16349
+ *
16350
+ * **Hooks are questions core asks.** Core stops at a checkpoint, hands the
16351
+ * handler a context, and ACTS ON what it returns — the opposite of
16352
+ * `bb.events`, whose handlers are told what already happened and whose
16353
+ * return value is ignored. It is the same split git draws between its
16354
+ * pre-commit and post-commit hooks, and the reason the two live in separate
16355
+ * namespaces rather than behind one `on`.
16356
+ *
16357
+ * Handlers for a hook run as a deterministic chain in plugin install order,
16358
+ * a `reject` short-circuits the pass, and `wait` decisions are COLLECTED
16359
+ * across the whole pass rather than short-circuiting. The attempt proceeds
16360
+ * only when a pass yields no waits. When several plugins wait, the FIRST owns
16361
+ * the row's `waitingOn` and the rest have their reasons appended to it, so
16362
+ * one decision produces one card rather than one per plugin; each of them
16363
+ * answers again on the next attempt, so nothing is lost by not owning the
16364
+ * row.
16365
+ *
16366
+ * Fail-closed: a handler that throws or exceeds the 10 second decision box
16367
+ * FAILS THE ATTEMPT with this plugin named. Decide in milliseconds — if the
16368
+ * answer needs real work, return `wait` with a `sendAt` and answer again on
16369
+ * the re-attempt.
16370
+ *
16371
+ * The whole pass runs under one server-wide lock, so a counting handler never
16372
+ * races another attempt. It also means a handler that blocks delays every
16373
+ * other attempt, up to the box.
16374
+ *
16375
+ * Passes re-run on every drain, on restart and on retry. A handler must be
16376
+ * idempotent for one logical dispatch.
16377
+ *
16378
+ * At most one handler per hook per plugin; registering a second replaces
16379
+ * nothing and throws.
16380
+ */
16381
+ on<K extends PluginHookName>(hook: K, handler: PluginHookHandler<K>): void;
16382
+ /**
16383
+ * Ask core to re-attempt the messages queued behind plugin waits.
16384
+ *
16385
+ * **The pair to `on`.** `on` answers the question core asks; `recheck`
16386
+ * asks core to ask it again. Core owns the re-draining and the clock — the
16387
+ * `sendAt` due sweep is still core's — and a plugin owns every other
16388
+ * condition its own waits depend on. When that condition changes, say so
16389
+ * here and answer the hook again on the re-attempt; there is no way to
16390
+ * release a specific row, and there does not need to be.
16391
+ *
16392
+ * The walk re-attempts every plugin-queued row IN QUEUE ORDER, each one
16393
+ * claimed exactly once, running the full `message.dispatch` pass over it —
16394
+ * every plugin's handler, not just the caller's. A row that is still blocked
16395
+ * simply re-queues, which is what makes an unwarranted request safe: nobody
16396
+ * has to work out whether their own condition was the last one the message
16397
+ * was waiting on. The existing per-thread re-queue pacing bounds the churn,
16398
+ * so a plugin that stays full is not re-asked in a loop.
16399
+ *
16400
+ * Bursts coalesce: several calls before the walk starts produce one walk.
16401
+ *
16402
+ * **Resolves when the walk is SCHEDULED, not when it finishes.** The walk is
16403
+ * a background pass with no caller to report to — its failures land on the
16404
+ * rows, exactly as the due sweep's do. Awaiting completion would also mean
16405
+ * awaiting a full hook pass from inside whatever called this, which for a
16406
+ * handler holding the evaluation lock could not complete. Fire and forget.
16407
+ */
16408
+ recheck(hook: PluginHookName): Promise<void>;
16409
+ }
15538
16410
  type PluginHttpAuthMode = "local" | "none" | "token";
15539
16411
  type PluginHttpHandler = (context: Context) => Response | Promise<Response>;
15540
16412
  interface PluginHttp {
@@ -16438,8 +17310,18 @@ interface BbPluginApi {
16438
17310
  readonly providers: PluginProviders;
16439
17311
  /** Host-rendered UI contributions (design §4.9). */
16440
17312
  readonly ui: PluginUi;
16441
- /** Additive plugin lifecycle listeners (design §4.5). */
17313
+ /**
17314
+ * Additive plugin lifecycle listeners (design §4.5). Announcements core
17315
+ * makes: a handler's return value is ignored.
17316
+ */
16442
17317
  readonly events: PluginEvents;
17318
+ /**
17319
+ * Questions core asks and acts on the answer to. Today: the dispatch
17320
+ * checkpoint messages pass through on their way to a provider (a user's
17321
+ * Send-now bypasses it by design), which a handler may let go, queue with a
17322
+ * reason, or refuse.
17323
+ */
17324
+ readonly experimental_hooks: PluginHooks;
16443
17325
  /** Plugin-reported status (needs-configuration). */
16444
17326
  readonly status: PluginStatusApi;
16445
17327
  /** Read-only facts about the running server (loopback base URL). */
@@ -16469,4 +17351,4 @@ interface BbPluginApi {
16469
17351
  }
16470
17352
 
16471
17353
  export { PLUGIN_CLI_OUTPUT_MAX_BYTES, defineRpcContract, experimental_defineHostEntry };
16472
- export type { BbContext, BbNavigate, BbPluginApi, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalHostCallOptions, ExperimentalHostClient, ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignalEvent, ExperimentalHostSignals, ExperimentalHostWatchChange, ExperimentalHostWatchChangeType, ExperimentalHostWatchEvent, ExperimentalHostWatchListener, ExperimentalHostWatchOptions, ExperimentalHostWatchSubscription, ExperimentalHostWorkerLease, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPermissionModePickerProps, ExperimentalPluginFixedTabReference, ExperimentalProviderModelPickerProps, ExperimentalProviderModelPickerRouting, ExperimentalProviderModelPickerValue, JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAgentConfiguration, PluginAgentConfigurationContext, PluginAgentToolContentPart, PluginAgentToolContext, PluginAgentToolLabels, PluginAgentToolPresentation, PluginAgentToolRegistrationBase, PluginAgentToolResult, PluginAgentToolSelection, PluginAgents, PluginAiServiceDeclaration, PluginAiServiceKind, PluginAiServices, PluginAppBuilder, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginBackground, PluginCli, PluginCliCommandInfo, PluginCliContext, PluginCliExecutionResult, PluginCliOutputLimitError, PluginCliRegistration, PluginCliResult, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginEvents, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginFixedTabDeclaration, PluginFixedTabRegistration, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginHosts, PluginHttp, PluginHttpAuthMode, PluginHttpHandler, PluginInteractionCancelReason, PluginInteractionRequest, PluginInteractionResult, PluginKvStorage, PluginLogger, PluginMentionItem, PluginMentionProviderRegistration, PluginMentionSearchContext, PluginMentionTrigger, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPanelActionOpenOptions, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginProviderCapabilities, PluginProviderComposerAction, PluginProviderDeclaration, PluginProviderExtensionKindDeclaration, PluginProviderFallbackModel, PluginProviderIconRegistration, PluginProviderMaintenance, PluginProviderModelCatalogScope, PluginProviderNativeRootEntry, PluginProviderNativeRoots, PluginProviderOptionDescriptor, PluginProviderOptionsContext, PluginProviderPermissionMode, PluginProviderReasoningLevel, PluginProviderStrings, PluginProviders, PluginProvidersState, PluginRealtime, PluginRealtimeConnectionState, PluginRpc, PluginRpcCallArgs, PluginRpcClient, PluginRpcContract, PluginRpcError, PluginRpcErrorCode, PluginRpcHandlers, PluginRpcIssuePathSegment, PluginRpcMethodContract, PluginRpcResult, PluginRpcValidationIssue, PluginSdkApp, PluginServerApi, PluginSettingDescriptor, PluginSettingDescriptors, PluginSettingValue, PluginSettings, PluginSettingsHandle, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsState, PluginSettingsValues, PluginSharedPortTunnelIdentity, PluginSidebarFooterActionContext, PluginSidebarFooterActionProps, PluginSidebarFooterActionRegistration, PluginSidebarProject, PluginSidebarPullRequest, PluginSidebarSplitPane, PluginSidebarThread, PluginSidebarThreadActions, PluginSidebarThreadActivity, PluginSidebarThreadIndicator, PluginSidebarThreadPullRequestState, PluginSidebarThreadSplit, PluginSidebarThreadsState, PluginSidebarWorkspaceKind, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginStatusApi, PluginStorage, PluginTargetedPanelActionOpenOptions, PluginThreadEventHandler, PluginThreadEventName, PluginThreadEventPayloads, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, PluginTimelineRendererProps, PluginTimelineRendererRegistration, PluginTimelineRendererRow, PluginTimelineRowPresentation, PluginTimelineRowStatus, PluginUi, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps };
17354
+ export type { BbContext, BbNavigate, BbPluginApi, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalComposerSubmitOptions, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalHostCallOptions, ExperimentalHostClient, ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignalEvent, ExperimentalHostSignals, ExperimentalHostWatchChange, ExperimentalHostWatchChangeType, ExperimentalHostWatchEvent, ExperimentalHostWatchListener, ExperimentalHostWatchOptions, ExperimentalHostWatchSubscription, ExperimentalHostWorkerLease, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPermissionModePickerProps, ExperimentalPluginFixedTabReference, ExperimentalProviderModelPickerProps, ExperimentalProviderModelPickerRouting, ExperimentalProviderModelPickerValue, ExperimentalSidebarNavigationAction, ExperimentalSidebarNavigationActivationOptions, ExperimentalSidebarNavigationIcon, ExperimentalSidebarNavigationItem, ExperimentalSidebarNavigationProps, ExperimentalSidebarNavigationRegistration, ExperimentalSidebarNavigationShortcut, JsonValue, MarkdownProps, MessageDispatchHookContext, MessageDispatchHookDecision, NewThreadComposerProps, NewThreadRequest, PluginAgentConfiguration, PluginAgentConfigurationContext, PluginAgentToolContentPart, PluginAgentToolContext, PluginAgentToolLabels, PluginAgentToolPresentation, PluginAgentToolRegistrationBase, PluginAgentToolResult, PluginAgentToolSelection, PluginAgents, PluginAiServiceDeclaration, PluginAiServiceKind, PluginAiServices, PluginAppBuilder, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginBackground, PluginCli, PluginCliCommandInfo, PluginCliContext, PluginCliExecutionResult, PluginCliOutputLimitError, PluginCliRegistration, PluginCliResult, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginDispatchAttemptKind, PluginDispatchExecution, PluginDispatchExecutionSources, PluginDispatchInput, PluginEvents, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginFixedTabDeclaration, PluginFixedTabRegistration, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginHookHandler, PluginHookName, PluginHookSignatures, PluginHooks, PluginHosts, PluginHttp, PluginHttpAuthMode, PluginHttpHandler, PluginInteractionCancelReason, PluginInteractionRequest, PluginInteractionResult, PluginKvStorage, PluginLogger, PluginMentionItem, PluginMentionProviderRegistration, PluginMentionSearchContext, PluginMentionTrigger, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPanelActionOpenOptions, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginProviderCapabilities, PluginProviderComposerAction, PluginProviderDeclaration, PluginProviderExtensionKindDeclaration, PluginProviderFallbackModel, PluginProviderIconRegistration, PluginProviderMaintenance, PluginProviderModelCatalogScope, PluginProviderNativeRootEntry, PluginProviderNativeRoots, PluginProviderOptionDescriptor, PluginProviderOptionsContext, PluginProviderPermissionMode, PluginProviderReasoningLevel, PluginProviderStrings, PluginProviders, PluginProvidersState, PluginRealtime, PluginRealtimeConnectionState, PluginRpc, PluginRpcCallArgs, PluginRpcClient, PluginRpcContract, PluginRpcError, PluginRpcErrorCode, PluginRpcHandlers, PluginRpcIssuePathSegment, PluginRpcMethodContract, PluginRpcResult, PluginRpcValidationIssue, PluginSdkApp, PluginServerApi, PluginSettingDescriptor, PluginSettingDescriptors, PluginSettingValue, PluginSettings, PluginSettingsHandle, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsState, PluginSettingsValues, PluginSharedPortTunnelIdentity, PluginSidebarFooterActionContext, PluginSidebarFooterActionProps, PluginSidebarFooterActionRegistration, PluginSidebarProject, PluginSidebarPullRequest, PluginSidebarSplitPane, PluginSidebarThread, PluginSidebarThreadActions, PluginSidebarThreadActivity, PluginSidebarThreadIndicator, PluginSidebarThreadPullRequestState, PluginSidebarThreadSplit, PluginSidebarThreadsState, PluginSidebarWorkspaceKind, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginStatusApi, PluginStorage, PluginTargetedPanelActionOpenOptions, PluginThreadEventHandler, PluginThreadEventName, PluginThreadEventPayloads, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, PluginTimelineRendererProps, PluginTimelineRendererRegistration, PluginTimelineRendererRow, PluginTimelineRowPresentation, PluginTimelineRowStatus, PluginTurnFailedEvent, PluginUi, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps };