@stacklink/sdk 0.3.15 → 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.15";
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[];
@@ -711,7 +712,7 @@ export interface StacklinkUsageBucket {
711
712
  }
712
713
  export interface StacklinkResourceUsage {
713
714
  credited?: number;
714
- key: 'tool_calls' | 'delivered_events' | 'memory_calls' | 'memory_input_tokens' | 'memory_retrievals' | 'workbench_standard' | 'workbench_medium' | 'workbench_large';
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';
715
716
  label: string;
716
717
  unit: string;
717
718
  included: number;
@@ -902,6 +903,18 @@ export interface WorkbenchSession {
902
903
  createdAt?: string | undefined;
903
904
  updatedAt?: string | undefined;
904
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
+ }
905
918
  export interface WorkbenchSessionDeleteReceipt {
906
919
  deleted: true;
907
920
  workbenchSessionId: string;
@@ -946,6 +959,7 @@ export interface WorkbenchReusableRunRequest {
946
959
  versionReason?: string | undefined;
947
960
  }
948
961
  export interface WorkbenchRunCodeInput {
962
+ afterExecution?: WorkbenchWaitRequest;
949
963
  workbenchSessionId?: string | undefined;
950
964
  language: WorkbenchRuntimeLanguage;
951
965
  code: string;
@@ -961,6 +975,7 @@ export interface WorkbenchRunCodeInput {
961
975
  metadata?: Record<string, unknown> | undefined;
962
976
  }
963
977
  export interface WorkbenchRunBashInput {
978
+ afterExecution?: WorkbenchWaitRequest;
964
979
  workbenchSessionId?: string | undefined;
965
980
  command: string;
966
981
  timeoutMs?: number | undefined;
@@ -981,8 +996,27 @@ export interface WorkbenchRuntimeDiagnostics {
981
996
  exitCode?: number | undefined;
982
997
  error?: unknown;
983
998
  }
984
- 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
+ }
985
1017
  export interface WorkbenchExecutionLog {
1018
+ waitRevision?: number;
1019
+ waitState?: Record<string, unknown> | null;
986
1020
  id: string;
987
1021
  executionId?: string | undefined;
988
1022
  executionKind?: 'workbench_code' | 'workbench_bash' | undefined;
@@ -1074,7 +1108,7 @@ export interface WorkbenchOutputPreview {
1074
1108
  export interface WorkbenchExecutionResponse {
1075
1109
  approvalRequestId?: string | undefined;
1076
1110
  executed?: boolean | undefined;
1077
- nextAction?: 'wait_for_approval' | undefined;
1111
+ nextAction?: 'wait_for_approval' | 'resume_saved_work' | undefined;
1078
1112
  workbenchSession: WorkbenchSession;
1079
1113
  executionKind: 'workbench_code' | 'workbench_bash';
1080
1114
  executionId: string;
@@ -1086,9 +1120,9 @@ export interface WorkbenchExecutionResponse {
1086
1120
  artifact?: WorkbenchArtifact | undefined;
1087
1121
  }
1088
1122
  export interface WorkbenchFile {
1089
- id: string;
1123
+ id: string | null;
1090
1124
  path: string;
1091
- contentType: string;
1125
+ contentType: string | null;
1092
1126
  sizeBytes: number | string;
1093
1127
  storageKind: 'r2_workspace' | 'database_blob' | string;
1094
1128
  sha256?: string | null | undefined;
@@ -1113,6 +1147,7 @@ export interface WorkbenchFileSignedDownload {
1113
1147
  };
1114
1148
  downloadUrl: string;
1115
1149
  expiresAt: string;
1150
+ requiredHeaders?: Record<string, string>;
1116
1151
  }
1117
1152
  export interface WorkbenchArtifact {
1118
1153
  id: string;
@@ -2235,10 +2270,20 @@ export declare class Stacklink {
2235
2270
  createAuthConfig(input: Record<string, unknown>): Promise<{
2236
2271
  authConfig: AuthConfig;
2237
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
+ }>;
2238
2284
  workbenchModels(): Promise<{
2239
2285
  models: WorkbenchModelOption[];
2240
2286
  defaultModel: string;
2241
- webSearchDefaultProvider: string;
2242
2287
  }>;
2243
2288
  runWorkbench(input: Record<string, unknown>, options?: StacklinkRequestOptions): Promise<Record<string, unknown>>;
2244
2289
  useWorkbenchSession(input: {
@@ -2250,16 +2295,36 @@ export declare class Stacklink {
2250
2295
  workbenchSession: WorkbenchSession;
2251
2296
  reused: boolean;
2252
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>;
2253
2313
  deleteWorkbenchSession(input: {
2254
2314
  sessionId: string;
2255
2315
  workbenchSessionId: string;
2316
+ }, options?: {
2317
+ timeoutMs?: number | undefined;
2318
+ signal?: AbortSignal | undefined;
2256
2319
  }): Promise<WorkbenchSessionDeleteReceipt>;
2257
2320
  listWorkbenchFiles(input: {
2258
2321
  sessionId: string;
2259
2322
  workbenchSessionId: string;
2323
+ cursor?: string;
2324
+ limit?: number;
2260
2325
  }): Promise<{
2261
- workbenchSession: WorkbenchSession;
2262
2326
  files: WorkbenchFile[];
2327
+ nextCursor: string | null;
2263
2328
  }>;
2264
2329
  readWorkbenchFile(input: {
2265
2330
  sessionId: string;
@@ -2276,9 +2341,10 @@ export declare class Stacklink {
2276
2341
  content: string | Uint8Array;
2277
2342
  contentType?: string | undefined;
2278
2343
  metadata?: Record<string, unknown> | undefined;
2344
+ uploadId?: string;
2279
2345
  }): Promise<{
2280
- workbenchSession: WorkbenchSession;
2281
2346
  file: WorkbenchFile;
2347
+ finalized: true;
2282
2348
  }>;
2283
2349
  prepareWorkbenchFileUpload(input: {
2284
2350
  sessionId: string;
@@ -2286,6 +2352,7 @@ export declare class Stacklink {
2286
2352
  path: string;
2287
2353
  contentType: string;
2288
2354
  sizeBytes: number;
2355
+ uploadId?: string;
2289
2356
  }): Promise<{
2290
2357
  workbenchSession: WorkbenchSession;
2291
2358
  upload: WorkbenchFileSignedUpload;
@@ -2295,18 +2362,28 @@ export declare class Stacklink {
2295
2362
  workbenchSessionId: string;
2296
2363
  uploadId: string;
2297
2364
  metadata?: Record<string, unknown> | undefined;
2365
+ }, options?: {
2366
+ timeoutMs?: number | undefined;
2367
+ signal?: AbortSignal | undefined;
2298
2368
  }): Promise<{
2299
2369
  file: WorkbenchFile;
2370
+ uploadId: string;
2371
+ finalized: true;
2300
2372
  }>;
2301
2373
  uploadWorkbenchFileDirect(input: {
2302
2374
  sessionId: string;
2303
2375
  workbenchSessionId: string;
2304
2376
  path: string;
2305
- content: string | Uint8Array;
2377
+ content: string | Uint8Array | Blob;
2306
2378
  contentType?: string | undefined;
2307
2379
  metadata?: Record<string, unknown> | undefined;
2380
+ uploadId?: string;
2381
+ transferTimeoutMs?: number;
2382
+ signal?: AbortSignal;
2308
2383
  }): Promise<{
2309
2384
  file: WorkbenchFile;
2385
+ uploadId: string;
2386
+ finalized: true;
2310
2387
  }>;
2311
2388
  getWorkbenchFileDownload(input: {
2312
2389
  sessionId: string;
@@ -2724,6 +2801,7 @@ export declare class Stacklink {
2724
2801
  sessionId: string;
2725
2802
  workbenchSessionId: string;
2726
2803
  path: string;
2804
+ artifactRef?: string;
2727
2805
  label?: string | undefined;
2728
2806
  contentType?: string | undefined;
2729
2807
  metadata?: Record<string, unknown> | undefined;
@@ -3375,9 +3453,12 @@ export declare class StacklinkWorkbenchFiles {
3375
3453
  private readonly platformSessionId;
3376
3454
  private readonly workbenchSessionId;
3377
3455
  constructor(client: Stacklink, platformSessionId: string, workbenchSessionId: () => Promise<string>);
3378
- list(): Promise<{
3379
- workbenchSession: WorkbenchSession;
3456
+ list(options?: {
3457
+ cursor?: string;
3458
+ limit?: number;
3459
+ }): Promise<{
3380
3460
  files: WorkbenchFile[];
3461
+ nextCursor: string | null;
3381
3462
  }>;
3382
3463
  read(path: string): Promise<{
3383
3464
  workbenchSession: WorkbenchSession;
@@ -3388,17 +3469,23 @@ export declare class StacklinkWorkbenchFiles {
3388
3469
  content: string | Uint8Array;
3389
3470
  contentType?: string | undefined;
3390
3471
  metadata?: Record<string, unknown> | undefined;
3472
+ uploadId?: string;
3391
3473
  }): Promise<{
3392
- workbenchSession: WorkbenchSession;
3393
3474
  file: WorkbenchFile;
3475
+ finalized: true;
3394
3476
  }>;
3395
3477
  uploadLarge(input: {
3396
3478
  path: string;
3397
- content: string | Uint8Array;
3479
+ content: string | Uint8Array | Blob;
3398
3480
  contentType?: string | undefined;
3399
3481
  metadata?: Record<string, unknown> | undefined;
3482
+ uploadId?: string;
3483
+ transferTimeoutMs?: number;
3484
+ signal?: AbortSignal;
3400
3485
  }): Promise<{
3401
3486
  file: WorkbenchFile;
3487
+ uploadId: string;
3488
+ finalized: true;
3402
3489
  }>;
3403
3490
  download(path: string): Promise<Response>;
3404
3491
  delete(path: string): Promise<{
@@ -3483,6 +3570,12 @@ export declare class StacklinkSessionSandbox {
3483
3570
  readonly artifacts: StacklinkWorkbenchArtifacts;
3484
3571
  private activeWorkbenchSessionId;
3485
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
+ }>;
3486
3579
  use(workbenchSessionId?: string, input?: {
3487
3580
  createNew?: boolean | undefined;
3488
3581
  metadata?: Record<string, unknown> | undefined;
@@ -3724,10 +3817,7 @@ export declare class StacklinkBotsClient {
3724
3817
  }>;
3725
3818
  link: (botId: string, fileId: string, input: {
3726
3819
  sessionId: string;
3727
- }) => Promise<{
3728
- url: string;
3729
- expiresAt: string;
3730
- }>;
3820
+ }) => Promise<BotFileLink>;
3731
3821
  };
3732
3822
  constructor(client: Stacklink);
3733
3823
  apis(): Promise<{
@@ -3804,7 +3894,11 @@ export declare class StacklinkBotsClient {
3804
3894
  status: string;
3805
3895
  }>;
3806
3896
  }>;
3807
- 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>;
3808
3902
  get(botId: string): Promise<Bot>;
3809
3903
  update(botId: string, revision: number, patch: BotPatch): Promise<Bot>;
3810
3904
  publish(botId: string, revision: number, channels: PublishChannels): Promise<{