@stacklink/sdk 0.3.14 → 0.4.0

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.
@@ -1,8 +1,8 @@
1
- import type { BotFileUpload, BotFileUploadInput, BotAttachment } from '../domain/bot-contract.js';
1
+ import type { BotFileUpload, BotFileUploadInput, BotFileLink, BotAttachment } from '../domain/bot-contract.js';
2
2
  import type { Bot, BotPatch, BotRun, BotRunInput, PublishChannels, SavedBotApi, ContextApi, BotApiSigningKey, BotApiSigningKeyRequest } from '../domain/bot-contract.js';
3
3
  import type { ApprovalRecord, ApprovalDecision, ApprovalChange, ApprovalListResponse, ApprovalListQuery, CustomerApprovalGrantInput, CustomerApprovalGrantResponse } from '../domain/platform-approval-contract.js';
4
4
  export type { ApprovalRecord, ApprovalDecision, ApprovalChange, ApprovalListResponse, ApprovalAudience, ApprovalRequirement, CustomerApprovalGrantInput, CustomerApprovalGrantResponse } from '../domain/platform-approval-contract.js';
5
- export type { BotFileUpload, BotFileUploadInput, BotAttachment, BotFileSettings, BotOutputFile, FileCitation, FileCoverage, Bot, BotPatch, BotRun, BotRunInput, PublishChannels, SavedBotApi, ContextApi, BotApiSigningKey, BotApiSigningKeyRequest, BotTrigger, BotPreparation, BotRunDisplay, BotReadinessIssue, BotCapabilityFact, BotConnectionAction, BotWaitingOperation, BotRequirement } from '../domain/bot-contract.js';
5
+ export type { BotAvatar, BotIdentity, BotFileUpload, BotFileUploadInput, BotFileLink, BotAttachment, BotFileSettings, BotOutputFile, BotWebSource, FileCitation, FileCoverage, Bot, BotPatch, BotRun, BotRunInput, PublishChannels, SavedBotApi, ContextApi, BotApiSigningKey, BotApiSigningKeyRequest, BotTrigger, BotPreparation, BotRunDisplay, BotReadinessIssue, BotCapabilityFact, BotConnectionAction, BotWaitingOperation, BotRequirement } from '../domain/bot-contract.js';
6
6
  import { type StacklinkMetaToolName, type StacklinkAgentSearchResponse } from '../domain/stacklink-meta-tools.js';
7
7
  export type { StacklinkAgentSearchResponse } from '../domain/stacklink-meta-tools.js';
8
8
  import type { ProviderBrandDescriptor } from '../domain/provider-branding.js';
@@ -14,13 +14,14 @@ export type { StacklinkMemoryAvailabilityMode, StacklinkMemoryCaptureController,
14
14
  export type StacklinkFetch = typeof fetch;
15
15
  export type StacklinkMcpToolName = StacklinkMetaToolName;
16
16
  export type StacklinkToolSurfaceName = StacklinkMcpToolName | (string & {});
17
- export declare const stacklinkTypeScriptSdkVersion = "0.3.14";
17
+ export declare const stacklinkTypeScriptSdkVersion = "0.4.0";
18
18
  export declare class StacklinkApiError extends Error {
19
19
  readonly statusCode: number;
20
20
  readonly code?: string | undefined;
21
21
  readonly details?: unknown | undefined;
22
22
  readonly retryAfterMs?: number | undefined;
23
- constructor(message: string, statusCode: number, code?: string | undefined, details?: unknown | undefined, retryAfterMs?: number | undefined);
23
+ readonly failureId?: string | undefined;
24
+ constructor(message: string, statusCode: number, code?: string | undefined, details?: unknown | undefined, retryAfterMs?: number | undefined, failureId?: string | undefined);
24
25
  }
25
26
  type QueryPrimitive = string | number | boolean | null | undefined;
26
27
  type QueryValue = QueryPrimitive | QueryPrimitive[];
@@ -709,7 +710,32 @@ export interface StacklinkUsageBucket {
709
710
  overage: number;
710
711
  overageCents: number;
711
712
  }
713
+ export interface StacklinkResourceUsage {
714
+ credited?: number;
715
+ key: 'tool_calls' | 'delivered_events' | 'memory_calls' | 'memory_input_tokens' | 'memory_retrievals' | 'workbench_standard' | 'workbench_medium' | 'workbench_large' | 'workbench_ready_standard' | 'workbench_ready_medium' | 'workbench_ready_large';
716
+ label: string;
717
+ unit: string;
718
+ included: number;
719
+ used: number;
720
+ reserved: number;
721
+ /** Included allowance available now; approved additional spending is separate. */
722
+ remaining: number;
723
+ additional: number;
724
+ additionalCents: number;
725
+ priceMicros: string;
726
+ unitQuantity: number;
727
+ rateVersion: string;
728
+ }
712
729
  export interface StacklinkUsageSummary {
730
+ agreementVersion?: string;
731
+ resources?: StacklinkResourceUsage[];
732
+ spending?: Record<string, {
733
+ approvedCents: number;
734
+ usedCents: number;
735
+ reservedCents: number;
736
+ availableCents: number;
737
+ currency: 'USD';
738
+ }>;
713
739
  workspace?: {
714
740
  id: string;
715
741
  name: string;
@@ -821,6 +847,38 @@ export interface StacklinkWebhookSignatureInput {
821
847
  toleranceSeconds?: number | undefined;
822
848
  now?: Date | undefined;
823
849
  }
850
+ export interface WorkbenchComputeStatus {
851
+ workbenchSession: WorkbenchSession;
852
+ compute: {
853
+ status: string;
854
+ stopped: boolean;
855
+ fundedThrough?: number | null;
856
+ activeExecutionCount?: number;
857
+ generation?: number | null;
858
+ };
859
+ billing: {
860
+ measurement: 'customer_active_ms' | 'legacy_operations';
861
+ settlementStatus: 'pending' | 'acknowledgement_pending' | 'settled';
862
+ reservedMilliseconds: number;
863
+ workspace: null | {
864
+ resource: string;
865
+ unit: string;
866
+ included: number;
867
+ used: number;
868
+ reserved: number;
869
+ available: number;
870
+ quantity: number;
871
+ additionalSpending: {
872
+ approvedCents: number;
873
+ usedCents: number;
874
+ reservedCents: number;
875
+ availableCents: number;
876
+ };
877
+ reason: string | null;
878
+ nextAction: string;
879
+ };
880
+ };
881
+ }
824
882
  export interface WorkbenchSession {
825
883
  id: string;
826
884
  consumerAppId?: string | undefined;
@@ -845,6 +903,18 @@ export interface WorkbenchSession {
845
903
  createdAt?: string | undefined;
846
904
  updatedAt?: string | undefined;
847
905
  }
906
+ export interface WorkbenchStorageOperation<T = unknown> {
907
+ operationId: string;
908
+ workbenchSessionId: string;
909
+ kind: 'delete' | 'upload_finalize' | 'artifact_promote';
910
+ status: 'pending' | 'processing' | 'completed' | 'failed';
911
+ statusUrl: string;
912
+ stage: string;
913
+ retryAfterMs: number;
914
+ pendingReason?: string;
915
+ result?: T;
916
+ error?: unknown;
917
+ }
848
918
  export interface WorkbenchSessionDeleteReceipt {
849
919
  deleted: true;
850
920
  workbenchSessionId: string;
@@ -889,6 +959,7 @@ export interface WorkbenchReusableRunRequest {
889
959
  versionReason?: string | undefined;
890
960
  }
891
961
  export interface WorkbenchRunCodeInput {
962
+ afterExecution?: WorkbenchWaitRequest;
892
963
  workbenchSessionId?: string | undefined;
893
964
  language: WorkbenchRuntimeLanguage;
894
965
  code: string;
@@ -904,6 +975,7 @@ export interface WorkbenchRunCodeInput {
904
975
  metadata?: Record<string, unknown> | undefined;
905
976
  }
906
977
  export interface WorkbenchRunBashInput {
978
+ afterExecution?: WorkbenchWaitRequest;
907
979
  workbenchSessionId?: string | undefined;
908
980
  command: string;
909
981
  timeoutMs?: number | undefined;
@@ -924,8 +996,27 @@ export interface WorkbenchRuntimeDiagnostics {
924
996
  exitCode?: number | undefined;
925
997
  error?: unknown;
926
998
  }
927
- export type WorkbenchExecutionStatus = 'waiting_for_approval' | 'queued' | 'started' | 'running' | 'cancel_requested' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
999
+ export type WorkbenchExecutionStatus = 'checkpointing' | 'waiting_saved' | 'waiting_ready' | 'resuming' | 'waiting_for_approval' | 'queued' | 'started' | 'running' | 'cancel_requested' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
1000
+ export interface WorkbenchWaitRequest {
1001
+ mode?: 'saved' | 'keep_ready';
1002
+ reason: 'approval' | 'connection' | 'user_input' | 'external_event';
1003
+ maximumWaitMs?: number;
1004
+ continuation: {
1005
+ language: WorkbenchRuntimeLanguage;
1006
+ code: string;
1007
+ timeoutMs: number;
1008
+ };
1009
+ keepReady?: {
1010
+ maximumWaitMs: number;
1011
+ maximumChargeMicros: string;
1012
+ rateVersion: string;
1013
+ priceMicros: string;
1014
+ unitQuantity: number;
1015
+ };
1016
+ }
928
1017
  export interface WorkbenchExecutionLog {
1018
+ waitRevision?: number;
1019
+ waitState?: Record<string, unknown> | null;
929
1020
  id: string;
930
1021
  executionId?: string | undefined;
931
1022
  executionKind?: 'workbench_code' | 'workbench_bash' | undefined;
@@ -1017,7 +1108,7 @@ export interface WorkbenchOutputPreview {
1017
1108
  export interface WorkbenchExecutionResponse {
1018
1109
  approvalRequestId?: string | undefined;
1019
1110
  executed?: boolean | undefined;
1020
- nextAction?: 'wait_for_approval' | undefined;
1111
+ nextAction?: 'wait_for_approval' | 'resume_saved_work' | undefined;
1021
1112
  workbenchSession: WorkbenchSession;
1022
1113
  executionKind: 'workbench_code' | 'workbench_bash';
1023
1114
  executionId: string;
@@ -1029,9 +1120,9 @@ export interface WorkbenchExecutionResponse {
1029
1120
  artifact?: WorkbenchArtifact | undefined;
1030
1121
  }
1031
1122
  export interface WorkbenchFile {
1032
- id: string;
1123
+ id: string | null;
1033
1124
  path: string;
1034
- contentType: string;
1125
+ contentType: string | null;
1035
1126
  sizeBytes: number | string;
1036
1127
  storageKind: 'r2_workspace' | 'database_blob' | string;
1037
1128
  sha256?: string | null | undefined;
@@ -1056,6 +1147,7 @@ export interface WorkbenchFileSignedDownload {
1056
1147
  };
1057
1148
  downloadUrl: string;
1058
1149
  expiresAt: string;
1150
+ requiredHeaders?: Record<string, string>;
1059
1151
  }
1060
1152
  export interface WorkbenchArtifact {
1061
1153
  id: string;
@@ -1152,6 +1244,8 @@ export interface WorkbenchRunReplayResponse {
1152
1244
  }
1153
1245
  export type WorkbenchBudgetPeriod = 'daily' | 'weekly' | 'monthly' | 'all_time';
1154
1246
  export interface WorkbenchBudgetPolicy {
1247
+ /** 1: legacy estimates and summed durations; 2: active runtime and customer charges. */
1248
+ measurementVersion: 1 | 2;
1155
1249
  id: string;
1156
1250
  tenantId: string;
1157
1251
  workbenchSessionId?: string | null | undefined;
@@ -1171,7 +1265,15 @@ export interface WorkbenchUsage {
1171
1265
  heartbeats?: unknown[];
1172
1266
  events?: unknown[];
1173
1267
  ledger?: unknown[];
1174
- summary?: unknown;
1268
+ summary?: {
1269
+ scope: 'workbench_session';
1270
+ period: 'all_time';
1271
+ measurement: 'settled_customer_runtime';
1272
+ runtimeMs: number;
1273
+ customerChargeMicros?: number | string;
1274
+ settledIntervals: number;
1275
+ };
1276
+ costLedgerMeasurement?: 'internal_estimate';
1175
1277
  budgets?: WorkbenchBudgetPolicy[];
1176
1278
  }
1177
1279
  export interface WorkbenchModelOption {
@@ -1183,6 +1285,8 @@ export interface WorkbenchModelOption {
1183
1285
  default?: boolean | undefined;
1184
1286
  }
1185
1287
  export interface StacklinkSessionData {
1288
+ closeRequestedAt?: string | null;
1289
+ closeTargetStatus?: string | null;
1186
1290
  id: string;
1187
1291
  tenantId: string;
1188
1292
  status?: string | undefined;
@@ -2166,10 +2270,20 @@ export declare class Stacklink {
2166
2270
  createAuthConfig(input: Record<string, unknown>): Promise<{
2167
2271
  authConfig: AuthConfig;
2168
2272
  }>;
2273
+ resumeWorkbenchExecution(input: {
2274
+ sessionId: string;
2275
+ executionId: string;
2276
+ expectedWaitRevision: number;
2277
+ checkpointId: string;
2278
+ }, options?: StacklinkRequestOptions): Promise<{
2279
+ executionId: string;
2280
+ status: WorkbenchExecutionStatus;
2281
+ waitRevision: number;
2282
+ executionLog: WorkbenchExecutionLog;
2283
+ }>;
2169
2284
  workbenchModels(): Promise<{
2170
2285
  models: WorkbenchModelOption[];
2171
2286
  defaultModel: string;
2172
- webSearchDefaultProvider: string;
2173
2287
  }>;
2174
2288
  runWorkbench(input: Record<string, unknown>, options?: StacklinkRequestOptions): Promise<Record<string, unknown>>;
2175
2289
  useWorkbenchSession(input: {
@@ -2181,16 +2295,36 @@ export declare class Stacklink {
2181
2295
  workbenchSession: WorkbenchSession;
2182
2296
  reused: boolean;
2183
2297
  }>;
2298
+ getWorkbenchOperation<T = unknown>(input: {
2299
+ sessionId: string;
2300
+ workbenchSessionId: string;
2301
+ operationId: string;
2302
+ }, options?: StacklinkRequestOptions): Promise<{
2303
+ operation: WorkbenchStorageOperation<T>;
2304
+ }>;
2305
+ waitForWorkbenchOperation<T>(input: {
2306
+ sessionId: string;
2307
+ workbenchSessionId: string;
2308
+ operationId: string;
2309
+ }, options?: {
2310
+ timeoutMs?: number | undefined;
2311
+ signal?: AbortSignal | undefined;
2312
+ }): Promise<T>;
2184
2313
  deleteWorkbenchSession(input: {
2185
2314
  sessionId: string;
2186
2315
  workbenchSessionId: string;
2316
+ }, options?: {
2317
+ timeoutMs?: number | undefined;
2318
+ signal?: AbortSignal | undefined;
2187
2319
  }): Promise<WorkbenchSessionDeleteReceipt>;
2188
2320
  listWorkbenchFiles(input: {
2189
2321
  sessionId: string;
2190
2322
  workbenchSessionId: string;
2323
+ cursor?: string;
2324
+ limit?: number;
2191
2325
  }): Promise<{
2192
- workbenchSession: WorkbenchSession;
2193
2326
  files: WorkbenchFile[];
2327
+ nextCursor: string | null;
2194
2328
  }>;
2195
2329
  readWorkbenchFile(input: {
2196
2330
  sessionId: string;
@@ -2207,9 +2341,10 @@ export declare class Stacklink {
2207
2341
  content: string | Uint8Array;
2208
2342
  contentType?: string | undefined;
2209
2343
  metadata?: Record<string, unknown> | undefined;
2344
+ uploadId?: string;
2210
2345
  }): Promise<{
2211
- workbenchSession: WorkbenchSession;
2212
2346
  file: WorkbenchFile;
2347
+ finalized: true;
2213
2348
  }>;
2214
2349
  prepareWorkbenchFileUpload(input: {
2215
2350
  sessionId: string;
@@ -2217,6 +2352,7 @@ export declare class Stacklink {
2217
2352
  path: string;
2218
2353
  contentType: string;
2219
2354
  sizeBytes: number;
2355
+ uploadId?: string;
2220
2356
  }): Promise<{
2221
2357
  workbenchSession: WorkbenchSession;
2222
2358
  upload: WorkbenchFileSignedUpload;
@@ -2226,18 +2362,28 @@ export declare class Stacklink {
2226
2362
  workbenchSessionId: string;
2227
2363
  uploadId: string;
2228
2364
  metadata?: Record<string, unknown> | undefined;
2365
+ }, options?: {
2366
+ timeoutMs?: number | undefined;
2367
+ signal?: AbortSignal | undefined;
2229
2368
  }): Promise<{
2230
2369
  file: WorkbenchFile;
2370
+ uploadId: string;
2371
+ finalized: true;
2231
2372
  }>;
2232
2373
  uploadWorkbenchFileDirect(input: {
2233
2374
  sessionId: string;
2234
2375
  workbenchSessionId: string;
2235
2376
  path: string;
2236
- content: string | Uint8Array;
2377
+ content: string | Uint8Array | Blob;
2237
2378
  contentType?: string | undefined;
2238
2379
  metadata?: Record<string, unknown> | undefined;
2380
+ uploadId?: string;
2381
+ transferTimeoutMs?: number;
2382
+ signal?: AbortSignal;
2239
2383
  }): Promise<{
2240
2384
  file: WorkbenchFile;
2385
+ uploadId: string;
2386
+ finalized: true;
2241
2387
  }>;
2242
2388
  getWorkbenchFileDownload(input: {
2243
2389
  sessionId: string;
@@ -2318,6 +2464,10 @@ export declare class Stacklink {
2318
2464
  }): Promise<{
2319
2465
  runDefinition: WorkbenchRunDefinition;
2320
2466
  }>;
2467
+ getWorkbenchComputeStatus(input: {
2468
+ sessionId: string;
2469
+ workbenchSessionId: string;
2470
+ }, options?: StacklinkRequestOptions): Promise<WorkbenchComputeStatus>;
2321
2471
  destroyWorkbenchSession(input: {
2322
2472
  sessionId: string;
2323
2473
  workbenchSessionId: string;
@@ -2651,6 +2801,7 @@ export declare class Stacklink {
2651
2801
  sessionId: string;
2652
2802
  workbenchSessionId: string;
2653
2803
  path: string;
2804
+ artifactRef?: string;
2654
2805
  label?: string | undefined;
2655
2806
  contentType?: string | undefined;
2656
2807
  metadata?: Record<string, unknown> | undefined;
@@ -2675,6 +2826,7 @@ export declare class Stacklink {
2675
2826
  limit?: number;
2676
2827
  }): Promise<{
2677
2828
  budgetPolicies: WorkbenchBudgetPolicy[];
2829
+ newPolicyMeasurementVersion?: 1 | 2;
2678
2830
  }>;
2679
2831
  createWorkbenchBudget(input: Record<string, unknown>): Promise<{
2680
2832
  budgetPolicy: WorkbenchBudgetPolicy;
@@ -3301,9 +3453,12 @@ export declare class StacklinkWorkbenchFiles {
3301
3453
  private readonly platformSessionId;
3302
3454
  private readonly workbenchSessionId;
3303
3455
  constructor(client: Stacklink, platformSessionId: string, workbenchSessionId: () => Promise<string>);
3304
- list(): Promise<{
3305
- workbenchSession: WorkbenchSession;
3456
+ list(options?: {
3457
+ cursor?: string;
3458
+ limit?: number;
3459
+ }): Promise<{
3306
3460
  files: WorkbenchFile[];
3461
+ nextCursor: string | null;
3307
3462
  }>;
3308
3463
  read(path: string): Promise<{
3309
3464
  workbenchSession: WorkbenchSession;
@@ -3314,17 +3469,23 @@ export declare class StacklinkWorkbenchFiles {
3314
3469
  content: string | Uint8Array;
3315
3470
  contentType?: string | undefined;
3316
3471
  metadata?: Record<string, unknown> | undefined;
3472
+ uploadId?: string;
3317
3473
  }): Promise<{
3318
- workbenchSession: WorkbenchSession;
3319
3474
  file: WorkbenchFile;
3475
+ finalized: true;
3320
3476
  }>;
3321
3477
  uploadLarge(input: {
3322
3478
  path: string;
3323
- content: string | Uint8Array;
3479
+ content: string | Uint8Array | Blob;
3324
3480
  contentType?: string | undefined;
3325
3481
  metadata?: Record<string, unknown> | undefined;
3482
+ uploadId?: string;
3483
+ transferTimeoutMs?: number;
3484
+ signal?: AbortSignal;
3326
3485
  }): Promise<{
3327
3486
  file: WorkbenchFile;
3487
+ uploadId: string;
3488
+ finalized: true;
3328
3489
  }>;
3329
3490
  download(path: string): Promise<Response>;
3330
3491
  delete(path: string): Promise<{
@@ -3409,6 +3570,12 @@ export declare class StacklinkSessionSandbox {
3409
3570
  readonly artifacts: StacklinkWorkbenchArtifacts;
3410
3571
  private activeWorkbenchSessionId;
3411
3572
  constructor(client: Stacklink, platformSessionId: string);
3573
+ resume(executionId: string, expectedWaitRevision: number, checkpointId: string): Promise<{
3574
+ executionId: string;
3575
+ status: WorkbenchExecutionStatus;
3576
+ waitRevision: number;
3577
+ executionLog: WorkbenchExecutionLog;
3578
+ }>;
3412
3579
  use(workbenchSessionId?: string, input?: {
3413
3580
  createNew?: boolean | undefined;
3414
3581
  metadata?: Record<string, unknown> | undefined;
@@ -3650,10 +3817,7 @@ export declare class StacklinkBotsClient {
3650
3817
  }>;
3651
3818
  link: (botId: string, fileId: string, input: {
3652
3819
  sessionId: string;
3653
- }) => Promise<{
3654
- url: string;
3655
- expiresAt: string;
3656
- }>;
3820
+ }) => Promise<BotFileLink>;
3657
3821
  };
3658
3822
  constructor(client: Stacklink);
3659
3823
  apis(): Promise<{
@@ -3730,7 +3894,11 @@ export declare class StacklinkBotsClient {
3730
3894
  status: string;
3731
3895
  }>;
3732
3896
  }>;
3733
- create(name: string): Promise<Bot>;
3897
+ create(name: string, identity?: {
3898
+ publicDescription?: string;
3899
+ iconAssetId?: string | null;
3900
+ avatar?: import('../domain/bot-contract.js').BotAvatar | null;
3901
+ }): Promise<Bot>;
3734
3902
  get(botId: string): Promise<Bot>;
3735
3903
  update(botId: string, revision: number, patch: BotPatch): Promise<Bot>;
3736
3904
  publish(botId: string, revision: number, channels: PublishChannels): Promise<{