@withgateway/sdk 0.2.8 → 0.2.9

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.
Files changed (45) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +332 -163
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +332 -163
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +119 -15
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +119 -15
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/index.d.mts +1 -1
  11. package/dist/index.d.ts +1 -1
  12. package/dist/index.js +229 -120
  13. package/dist/index.js.map +1 -1
  14. package/dist/index.mjs +220 -120
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/traces/index.js +119 -15
  17. package/dist/traces/index.js.map +1 -1
  18. package/dist/traces/index.mjs +119 -15
  19. package/dist/traces/index.mjs.map +1 -1
  20. package/dist/tracing/index.js +1 -1
  21. package/dist/tracing/index.js.map +1 -1
  22. package/dist/tracing/index.mjs +1 -1
  23. package/dist/tracing/index.mjs.map +1 -1
  24. package/dist/worlds/index.d.mts +78 -9
  25. package/dist/worlds/index.d.ts +78 -9
  26. package/dist/worlds/index.js +219 -119
  27. package/dist/worlds/index.js.map +1 -1
  28. package/dist/worlds/index.mjs +220 -120
  29. package/dist/worlds/index.mjs.map +1 -1
  30. package/package.json +1 -1
  31. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  32. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
  33. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
  34. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
  35. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  36. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
  37. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
  38. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  39. package/skills/benchmarks-getting-started/SKILL.md +3 -3
  40. package/skills/connector-schema-authoring/SKILL.md +1 -1
  41. package/skills/connector-schema-authoring/world-schema.md +1 -1
  42. package/skills/worlds-getting-started/SKILL.md +11 -11
  43. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  44. package/skills/worlds-getting-started/references/gotchas.md +5 -1
  45. package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
@@ -1181,6 +1181,52 @@ declare function computerUseToolkit(browser: WorldBrowser, opts?: {
1181
1181
  maxText?: number;
1182
1182
  }): WorldToolkit;
1183
1183
 
1184
+ declare const PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
1185
+ /** How long one platform request may go unanswered before it is abandoned; `GATEWAY_TIMEOUT_MS` overrides it. */
1186
+ declare const PLATFORM_TIMEOUT_DEFAULT_MS = 120000;
1187
+ type PlatformEndpoint = {
1188
+ host: string;
1189
+ publicKey: string;
1190
+ secretKey: string;
1191
+ };
1192
+ type PlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
1193
+ type PlatformReply = {
1194
+ status: number;
1195
+ ok: boolean;
1196
+ text: string;
1197
+ };
1198
+ /** The request budget in force: `GATEWAY_TIMEOUT_MS` when set, else the default. */
1199
+ declare function platformTimeoutMs(env?: NodeJS.ProcessEnv): number;
1200
+ /** Why a request got no answer, from the socket-level error undici hides under `fetch failed`. */
1201
+ declare class TransportCause {
1202
+ readonly reason: string;
1203
+ readonly detail: string | null;
1204
+ readonly next: string;
1205
+ private constructor();
1206
+ static timeout(timeoutMs: number): TransportCause;
1207
+ static of(error: unknown): TransportCause;
1208
+ describe(): string;
1209
+ }
1210
+ /** A platform request that never got an answer: one line naming the request, the host, the cause and the next step. */
1211
+ declare class UnreachableError extends Error {
1212
+ readonly host: string;
1213
+ readonly method: string;
1214
+ readonly route: string;
1215
+ readonly failure: TransportCause;
1216
+ constructor(host: string, method: string, route: string, failure: TransportCause);
1217
+ }
1218
+ /** The one door every CLI and SDK request to the platform goes through: Basic auth with the project key, a per-request timeout, and a transport failure turned into an `UnreachableError`. */
1219
+ declare class PlatformTransport {
1220
+ private readonly endpoint;
1221
+ private readonly timeoutMs;
1222
+ constructor(endpoint: PlatformEndpoint, timeoutMs?: number);
1223
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
1224
+ budget(ownMs?: number): number;
1225
+ send(method: PlatformMethod, route: string, body?: unknown, opts?: {
1226
+ timeoutMs?: number;
1227
+ }): Promise<PlatformReply>;
1228
+ }
1229
+
1184
1230
  /** Mirrors `WorldSessionListItemSchema` (web/features/public-api/types/world-sessions.ts). */
1185
1231
  type WorldSessionListItem = {
1186
1232
  sessionId: string;
@@ -2669,6 +2715,23 @@ type SandboxOpenNew = {
2669
2715
  type SandboxOpenTarget = SandboxOpenExisting | SandboxOpenNew;
2670
2716
  /** `slug` or `slug@ref` → the open body; a bare slug opens the latest READY version. */
2671
2717
  declare function parseSlugRef(slugRef: string): SandboxOpenExisting;
2718
+ /** One sandbox request may run the platform's longest exec (600 s) plus the answer; the Python twin waits the same 660 s. */
2719
+ declare const SANDBOX_REQUEST_TIMEOUT_MS = 660000;
2720
+ /** Mirrors `PostSandboxCommitBody`: `rebase` replays the sandbox's edits onto the branch head when the base moved. */
2721
+ type SandboxCommitInput = {
2722
+ message: string;
2723
+ branch?: string;
2724
+ rebase?: boolean;
2725
+ };
2726
+ /** One path a rebase refused, as the 409 body's `conflicts[]` names it. */
2727
+ type RebaseConflictPath = {
2728
+ path: string;
2729
+ reason: string;
2730
+ };
2731
+ /** A 409 from `commit --rebase`: the paths both sides changed and why each was refused. Null for any other failure. */
2732
+ declare function rebaseConflicts(error: unknown): RebaseConflictPath[] | null;
2733
+ /** A 409 `sandbox_uncommitted` from `close`: the paths a commit would keep. Null for any other failure. */
2734
+ declare function uncommittedPaths(error: unknown): string[] | null;
2672
2735
  /** `sandbox list` narrows: status, world, count (newest first). */
2673
2736
  type SandboxListFilter = {
2674
2737
  status?: "open" | "closed";
@@ -2678,6 +2741,7 @@ type SandboxListFilter = {
2678
2741
  declare class WorldSandboxClient {
2679
2742
  private readonly options;
2680
2743
  constructor(options?: WorldsClientOptions);
2744
+ private request;
2681
2745
  /**
2682
2746
  * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
2683
2747
  * a world that does not exist yet (409 `world_exists` if the slug is taken,
@@ -2703,10 +2767,8 @@ declare class WorldSandboxClient {
2703
2767
  timeoutMs?: number;
2704
2768
  }): Promise<SandboxExecResult>;
2705
2769
  check(sandboxId: string): Promise<SandboxCheckResult>;
2706
- commit(sandboxId: string, input: {
2707
- message: string;
2708
- branch?: string;
2709
- }): Promise<SandboxCommitResult>;
2770
+ /** With `rebase`, a moved base is replayed onto; a 409 then names the conflicting paths (`rebaseConflicts`). */
2771
+ commit(sandboxId: string, input: SandboxCommitInput): Promise<SandboxCommitResult>;
2710
2772
  /**
2711
2773
  * A rows file already in the sandbox tree into the PLATFORM world the
2712
2774
  * sandbox was opened on (201 with the version, 202 with the batch to poll,
@@ -2714,7 +2776,10 @@ declare class WorldSandboxClient {
2714
2776
  * tree and never carries data.
2715
2777
  */
2716
2778
  importData(sandboxId: string, input: SandboxImportInput): Promise<SandboxImportResult | SandboxImportPending>;
2717
- close(sandboxId: string): Promise<SandboxSummary>;
2779
+ /** Uncommitted work is a 409 (`uncommittedPaths`) unless `force` discards it. */
2780
+ close(sandboxId: string, opts?: {
2781
+ force?: boolean;
2782
+ }): Promise<SandboxSummary>;
2718
2783
  }
2719
2784
 
2720
2785
  /**
@@ -2921,8 +2986,9 @@ type DispatchedRun = {
2921
2986
  * server's error class name. */
2922
2987
  declare class ApiError extends Error {
2923
2988
  readonly status: number;
2989
+ readonly text: string;
2924
2990
  readonly code: string | null;
2925
- constructor(status: number, method: string, path: string, body: string);
2991
+ constructor(status: number, method: string, path: string, text: string);
2926
2992
  }
2927
2993
  /** What a client shows for one non-2xx body and the stable code it carries.
2928
2994
  * Python twin: `gatewaysdk.api_errors.error_detail`. */
@@ -2931,8 +2997,11 @@ declare function parseErrorBody(text: string, limit?: number): {
2931
2997
  code: string | null;
2932
2998
  };
2933
2999
  /** Authenticated JSON request against the platform API — the primitive the
2934
- * worlds helpers and the TS CLI share. */
2935
- declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
3000
+ * worlds helpers and the TS CLI share. `init.timeoutMs` is the request's own
3001
+ * budget when it legitimately outlasts `GATEWAY_TIMEOUT_MS`. */
3002
+ declare function apiRequest<T>(options: WorldsClientOptions, method: PlatformMethod, path: string, body?: unknown, init?: {
3003
+ timeoutMs?: number;
3004
+ }): Promise<T>;
2936
3005
  /** Set (or rotate) one environment secret — write-only: no API returns it. */
2937
3006
  declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
2938
3007
  key: string;
@@ -3123,4 +3192,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
3123
3192
  */
3124
3193
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
3125
3194
 
3126
- export { ApiError, BROWSER_GONE_PATTERNS, BROWSER_TIERS, type BrowserActionEvent, BrowserActionRecorder, type BrowserConnection, type BrowserMode, type BrowserPage, BrowserReconnected, BrowserReconnector, type BrowserTier, BrowserUnrecoverable, CALL_BODY_LIMIT_BYTES, CALL_BODY_LIMIT_LABEL, COMPUTER_USE_SPECS, type Checkout, CheckoutProvenance, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, type DryRunImageDecision, DryRunOutcome, type DryRunSettlement, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EXPLORATORY_TASK, EXPLORATORY_TASK_SOURCE, type EditSessionCloseInput, type EditSessionList, type EditSessionListQuery, type EditSessionResult, type EditSessionRollbackInput, type EditSessionSummary, type EvalSample, type FinalizeEvaluationOptions, GatewayEvalsClient, type GradeResult, HostedDryRunClient, type HostedDryRunDispatch, type HostedDryRunStatus, type HostedDryRunVerdict, IDLE_WARNING_MINUTES, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NO_GRADER_REASON, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, type Plaintext, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RepairAnswer, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SESSION_STATES, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitResult, type SandboxExecResult, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WorldBrowser, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVerifier, type WorldTaskVerifierRow, type WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
3195
+ export { ApiError, BROWSER_GONE_PATTERNS, BROWSER_TIERS, type BrowserActionEvent, BrowserActionRecorder, type BrowserConnection, type BrowserMode, type BrowserPage, BrowserReconnected, BrowserReconnector, type BrowserTier, BrowserUnrecoverable, CALL_BODY_LIMIT_BYTES, CALL_BODY_LIMIT_LABEL, COMPUTER_USE_SPECS, type Checkout, CheckoutProvenance, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, type DryRunImageDecision, DryRunOutcome, type DryRunSettlement, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EXPLORATORY_TASK, EXPLORATORY_TASK_SOURCE, type EditSessionCloseInput, type EditSessionList, type EditSessionListQuery, type EditSessionResult, type EditSessionRollbackInput, type EditSessionSummary, type EvalSample, type FinalizeEvaluationOptions, GatewayEvalsClient, type GradeResult, HostedDryRunClient, type HostedDryRunDispatch, type HostedDryRunStatus, type HostedDryRunVerdict, IDLE_WARNING_MINUTES, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NO_GRADER_REASON, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, PLATFORM_TIMEOUT_DEFAULT_MS, PLATFORM_TIMEOUT_ENV, type ParsedToolCall, type Plaintext, type PlatformEndpoint, type PlatformMethod, type PlatformReply, PlatformTransport, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, type RebaseConflictPath, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RepairAnswer, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SANDBOX_REQUEST_TIMEOUT_MS, SESSION_STATES, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitInput, type SandboxCommitResult, type SandboxExecResult, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, TransportCause, UnreachableError, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WorldBrowser, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVerifier, type WorldTaskVerifierRow, type WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, platformTimeoutMs, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
@@ -1181,6 +1181,52 @@ declare function computerUseToolkit(browser: WorldBrowser, opts?: {
1181
1181
  maxText?: number;
1182
1182
  }): WorldToolkit;
1183
1183
 
1184
+ declare const PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
1185
+ /** How long one platform request may go unanswered before it is abandoned; `GATEWAY_TIMEOUT_MS` overrides it. */
1186
+ declare const PLATFORM_TIMEOUT_DEFAULT_MS = 120000;
1187
+ type PlatformEndpoint = {
1188
+ host: string;
1189
+ publicKey: string;
1190
+ secretKey: string;
1191
+ };
1192
+ type PlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
1193
+ type PlatformReply = {
1194
+ status: number;
1195
+ ok: boolean;
1196
+ text: string;
1197
+ };
1198
+ /** The request budget in force: `GATEWAY_TIMEOUT_MS` when set, else the default. */
1199
+ declare function platformTimeoutMs(env?: NodeJS.ProcessEnv): number;
1200
+ /** Why a request got no answer, from the socket-level error undici hides under `fetch failed`. */
1201
+ declare class TransportCause {
1202
+ readonly reason: string;
1203
+ readonly detail: string | null;
1204
+ readonly next: string;
1205
+ private constructor();
1206
+ static timeout(timeoutMs: number): TransportCause;
1207
+ static of(error: unknown): TransportCause;
1208
+ describe(): string;
1209
+ }
1210
+ /** A platform request that never got an answer: one line naming the request, the host, the cause and the next step. */
1211
+ declare class UnreachableError extends Error {
1212
+ readonly host: string;
1213
+ readonly method: string;
1214
+ readonly route: string;
1215
+ readonly failure: TransportCause;
1216
+ constructor(host: string, method: string, route: string, failure: TransportCause);
1217
+ }
1218
+ /** The one door every CLI and SDK request to the platform goes through: Basic auth with the project key, a per-request timeout, and a transport failure turned into an `UnreachableError`. */
1219
+ declare class PlatformTransport {
1220
+ private readonly endpoint;
1221
+ private readonly timeoutMs;
1222
+ constructor(endpoint: PlatformEndpoint, timeoutMs?: number);
1223
+ /** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
1224
+ budget(ownMs?: number): number;
1225
+ send(method: PlatformMethod, route: string, body?: unknown, opts?: {
1226
+ timeoutMs?: number;
1227
+ }): Promise<PlatformReply>;
1228
+ }
1229
+
1184
1230
  /** Mirrors `WorldSessionListItemSchema` (web/features/public-api/types/world-sessions.ts). */
1185
1231
  type WorldSessionListItem = {
1186
1232
  sessionId: string;
@@ -2669,6 +2715,23 @@ type SandboxOpenNew = {
2669
2715
  type SandboxOpenTarget = SandboxOpenExisting | SandboxOpenNew;
2670
2716
  /** `slug` or `slug@ref` → the open body; a bare slug opens the latest READY version. */
2671
2717
  declare function parseSlugRef(slugRef: string): SandboxOpenExisting;
2718
+ /** One sandbox request may run the platform's longest exec (600 s) plus the answer; the Python twin waits the same 660 s. */
2719
+ declare const SANDBOX_REQUEST_TIMEOUT_MS = 660000;
2720
+ /** Mirrors `PostSandboxCommitBody`: `rebase` replays the sandbox's edits onto the branch head when the base moved. */
2721
+ type SandboxCommitInput = {
2722
+ message: string;
2723
+ branch?: string;
2724
+ rebase?: boolean;
2725
+ };
2726
+ /** One path a rebase refused, as the 409 body's `conflicts[]` names it. */
2727
+ type RebaseConflictPath = {
2728
+ path: string;
2729
+ reason: string;
2730
+ };
2731
+ /** A 409 from `commit --rebase`: the paths both sides changed and why each was refused. Null for any other failure. */
2732
+ declare function rebaseConflicts(error: unknown): RebaseConflictPath[] | null;
2733
+ /** A 409 `sandbox_uncommitted` from `close`: the paths a commit would keep. Null for any other failure. */
2734
+ declare function uncommittedPaths(error: unknown): string[] | null;
2672
2735
  /** `sandbox list` narrows: status, world, count (newest first). */
2673
2736
  type SandboxListFilter = {
2674
2737
  status?: "open" | "closed";
@@ -2678,6 +2741,7 @@ type SandboxListFilter = {
2678
2741
  declare class WorldSandboxClient {
2679
2742
  private readonly options;
2680
2743
  constructor(options?: WorldsClientOptions);
2744
+ private request;
2681
2745
  /**
2682
2746
  * `{ slug, ref? }` opens a READY version; `{ new, from }` opens a sandbox on
2683
2747
  * a world that does not exist yet (409 `world_exists` if the slug is taken,
@@ -2703,10 +2767,8 @@ declare class WorldSandboxClient {
2703
2767
  timeoutMs?: number;
2704
2768
  }): Promise<SandboxExecResult>;
2705
2769
  check(sandboxId: string): Promise<SandboxCheckResult>;
2706
- commit(sandboxId: string, input: {
2707
- message: string;
2708
- branch?: string;
2709
- }): Promise<SandboxCommitResult>;
2770
+ /** With `rebase`, a moved base is replayed onto; a 409 then names the conflicting paths (`rebaseConflicts`). */
2771
+ commit(sandboxId: string, input: SandboxCommitInput): Promise<SandboxCommitResult>;
2710
2772
  /**
2711
2773
  * A rows file already in the sandbox tree into the PLATFORM world the
2712
2774
  * sandbox was opened on (201 with the version, 202 with the batch to poll,
@@ -2714,7 +2776,10 @@ declare class WorldSandboxClient {
2714
2776
  * tree and never carries data.
2715
2777
  */
2716
2778
  importData(sandboxId: string, input: SandboxImportInput): Promise<SandboxImportResult | SandboxImportPending>;
2717
- close(sandboxId: string): Promise<SandboxSummary>;
2779
+ /** Uncommitted work is a 409 (`uncommittedPaths`) unless `force` discards it. */
2780
+ close(sandboxId: string, opts?: {
2781
+ force?: boolean;
2782
+ }): Promise<SandboxSummary>;
2718
2783
  }
2719
2784
 
2720
2785
  /**
@@ -2921,8 +2986,9 @@ type DispatchedRun = {
2921
2986
  * server's error class name. */
2922
2987
  declare class ApiError extends Error {
2923
2988
  readonly status: number;
2989
+ readonly text: string;
2924
2990
  readonly code: string | null;
2925
- constructor(status: number, method: string, path: string, body: string);
2991
+ constructor(status: number, method: string, path: string, text: string);
2926
2992
  }
2927
2993
  /** What a client shows for one non-2xx body and the stable code it carries.
2928
2994
  * Python twin: `gatewaysdk.api_errors.error_detail`. */
@@ -2931,8 +2997,11 @@ declare function parseErrorBody(text: string, limit?: number): {
2931
2997
  code: string | null;
2932
2998
  };
2933
2999
  /** Authenticated JSON request against the platform API — the primitive the
2934
- * worlds helpers and the TS CLI share. */
2935
- declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
3000
+ * worlds helpers and the TS CLI share. `init.timeoutMs` is the request's own
3001
+ * budget when it legitimately outlasts `GATEWAY_TIMEOUT_MS`. */
3002
+ declare function apiRequest<T>(options: WorldsClientOptions, method: PlatformMethod, path: string, body?: unknown, init?: {
3003
+ timeoutMs?: number;
3004
+ }): Promise<T>;
2936
3005
  /** Set (or rotate) one environment secret — write-only: no API returns it. */
2937
3006
  declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
2938
3007
  key: string;
@@ -3123,4 +3192,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
3123
3192
  */
3124
3193
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
3125
3194
 
3126
- export { ApiError, BROWSER_GONE_PATTERNS, BROWSER_TIERS, type BrowserActionEvent, BrowserActionRecorder, type BrowserConnection, type BrowserMode, type BrowserPage, BrowserReconnected, BrowserReconnector, type BrowserTier, BrowserUnrecoverable, CALL_BODY_LIMIT_BYTES, CALL_BODY_LIMIT_LABEL, COMPUTER_USE_SPECS, type Checkout, CheckoutProvenance, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, type DryRunImageDecision, DryRunOutcome, type DryRunSettlement, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EXPLORATORY_TASK, EXPLORATORY_TASK_SOURCE, type EditSessionCloseInput, type EditSessionList, type EditSessionListQuery, type EditSessionResult, type EditSessionRollbackInput, type EditSessionSummary, type EvalSample, type FinalizeEvaluationOptions, GatewayEvalsClient, type GradeResult, HostedDryRunClient, type HostedDryRunDispatch, type HostedDryRunStatus, type HostedDryRunVerdict, IDLE_WARNING_MINUTES, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NO_GRADER_REASON, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, type Plaintext, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RepairAnswer, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SESSION_STATES, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitResult, type SandboxExecResult, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WorldBrowser, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVerifier, type WorldTaskVerifierRow, type WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
3195
+ export { ApiError, BROWSER_GONE_PATTERNS, BROWSER_TIERS, type BrowserActionEvent, BrowserActionRecorder, type BrowserConnection, type BrowserMode, type BrowserPage, BrowserReconnected, BrowserReconnector, type BrowserTier, BrowserUnrecoverable, CALL_BODY_LIMIT_BYTES, CALL_BODY_LIMIT_LABEL, COMPUTER_USE_SPECS, type Checkout, CheckoutProvenance, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, type DryRunImageDecision, DryRunOutcome, type DryRunSettlement, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, EXPLORATORY_TASK, EXPLORATORY_TASK_SOURCE, type EditSessionCloseInput, type EditSessionList, type EditSessionListQuery, type EditSessionResult, type EditSessionRollbackInput, type EditSessionSummary, type EvalSample, type FinalizeEvaluationOptions, GatewayEvalsClient, type GradeResult, HostedDryRunClient, type HostedDryRunDispatch, type HostedDryRunStatus, type HostedDryRunVerdict, IDLE_WARNING_MINUTES, type IngestExplode, type IngestFieldSpec, type IngestMapping, type IngestMode, type IngestOptions, type IngestRefusal, type IngestReport, type IngestSource, type IngestSourceReport, type IngestToolCallsOptions, type IngestToolCallsReport, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NO_GRADER_REASON, type ObservationConversion, type ObservationLike, type OpenSessionOptions, type OpenTaskOptions, PLATFORM_TIMEOUT_DEFAULT_MS, PLATFORM_TIMEOUT_ENV, type ParsedToolCall, type Plaintext, type PlatformEndpoint, type PlatformMethod, type PlatformReply, PlatformTransport, type PlaywrightBrowserLike, type PlaywrightLike, PushSlugConflict, type PushSlugResolution, RECOVER_BUDGET_MS, type RebaseConflictPath, type RecoveryResult, type RedactMode, type RedactPolicy, type Redaction, type RepairAnswer, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, type RunSetOptions, type RunSetResult, type RunSummary, type RunTaskOptions, type RunTaskSummary, SANDBOX_REQUEST_TIMEOUT_MS, SESSION_STATES, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SandboxChanges, type SandboxCheckResult, type SandboxCommitInput, type SandboxCommitResult, type SandboxExecResult, type SandboxImportInput, type SandboxImportPending, type SandboxImportResult, type SandboxListFilter, type SandboxOpenExisting, type SandboxOpenNew, type SandboxOpenTarget, type SandboxOpened, type SandboxSummary, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldSessionState, type ToolCallRecord, type ToolCallSink, type ToolFunctions, type Transform, TransportCause, UnreachableError, VERIFIER_REWARD_PREFIX, type ValidateReport, type ValidatedRun, type VerifierGrade, WHITESPACE, WorldBrowser, WorldCallTooLarge, type WorldDependency, type WorldDeprecation, type WorldDescription, WorldEditClient, type WorldEntity, type WorldEntityMapping, type WorldField, type WorldMigrationRefusal, type WorldMigrationReport, type WorldQueryAcrossOptions, type WorldQueryAcrossResult, type WorldQueryCompare, type WorldQueryCompareStatus, type WorldQueryGroup, type WorldQueryOptions, type WorldQueryResult, type WorldQuerySnapshot, type WorldQueryWhere, type WorldRelationship, WorldSandboxClient, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionListItem, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVerifier, type WorldTaskVerifierRow, type WorldTaskVersionSummary, type WorldTaskWorld, type WorldTaskWorldValidation, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, aggregateTaskGrade, apiRequest, applyTransforms, archiveMode, assertBrowserTier, assertTaskRef, attachManifest, attachSession, attachTask, buildFileManifest, buildSourceTarball, captureToolCalls, checkoutIdentity, closeConnection, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, describeWorld, detectProvenance, extractBundle, getRun, getTask, hashForm, idleWarning, ingest, ingestToolCalls, isBrowserGone, isSandboxImportPending, isTaskIdRef, isTaskManifest, isTaskSpec, listEnvSecretKeys, listRunConfigs, listRuns, listSessions, listTaskSessions, listTasks, localTreeState, migrateProjectWorlds, migrateWorld, modelToolName, openBrowser, openSession, openTask, openWorld, openWorldVersion, parseErrorBody, parseSlugRef, parseToolCallRecord, parseTransform, parseWorldTaskRefs, platformTimeoutMs, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };