@withgateway/sdk 0.3.0 → 0.3.1

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 (47) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +1497 -712
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +1500 -715
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +34 -0
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +34 -0
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/{index-DAb-FCMg.d.ts → index-CBqbB_0J.d.ts} +2 -12
  11. package/dist/{index-D6oi1TWE.d.mts → index-D-AMnAMa.d.mts} +2 -12
  12. package/dist/index.d.mts +3 -3
  13. package/dist/index.d.ts +3 -3
  14. package/dist/index.js +173 -50
  15. package/dist/index.js.map +1 -1
  16. package/dist/index.mjs +171 -50
  17. package/dist/index.mjs.map +1 -1
  18. package/dist/traces/index.js +34 -0
  19. package/dist/traces/index.js.map +1 -1
  20. package/dist/traces/index.mjs +34 -0
  21. package/dist/traces/index.mjs.map +1 -1
  22. package/dist/tracing/index.d.mts +1 -1
  23. package/dist/tracing/index.d.ts +1 -1
  24. package/dist/tracing/index.js +39 -20
  25. package/dist/tracing/index.js.map +1 -1
  26. package/dist/tracing/index.mjs +39 -20
  27. package/dist/tracing/index.mjs.map +1 -1
  28. package/dist/worlds/index.d.mts +66 -18
  29. package/dist/worlds/index.d.ts +66 -18
  30. package/dist/worlds/index.js +171 -50
  31. package/dist/worlds/index.js.map +1 -1
  32. package/dist/worlds/index.mjs +171 -50
  33. package/dist/worlds/index.mjs.map +1 -1
  34. package/package.json +1 -1
  35. package/runtime/gatewaysdk/environment/schema/api.py +7 -8
  36. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  37. package/runtime/gatewaysdk/environment/schema/platform.py +1 -7
  38. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
  39. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
  40. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +6 -6
  41. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
  42. package/skills/connector-schema-authoring/SKILL.md +3 -3
  43. package/skills/connector-schema-authoring/connector-worlds.md +12 -5
  44. package/skills/connector-schema-authoring/world-schema.md +8 -0
  45. package/skills/world-data-ingestion/SKILL.md +2 -2
  46. package/skills/worlds-getting-started/SKILL.md +6 -6
  47. package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
@@ -1689,7 +1689,7 @@ type ListSessionsFilter = {
1689
1689
  slug?: string;
1690
1690
  limit?: number;
1691
1691
  };
1692
- /** The project's live sessions, newest first — the ones an agent can attach to. */
1692
+ /** The project's sessions in every state, newest first; `state` narrows to one. */
1693
1693
  declare function listSessions(filter?: ListSessionsFilter, options?: WorldsClientOptions): Promise<WorldSessionListItem[]>;
1694
1694
 
1695
1695
  /**
@@ -1740,6 +1740,27 @@ declare function serializeCallBody(body: unknown): string;
1740
1740
  * `IDLE_WARNING_MINUTES` left, else null. `now` is for tests. */
1741
1741
  declare function idleWarning(idleExpiresAt: string | null | undefined, now?: Date): string | null;
1742
1742
 
1743
+ /** Where a session answers, in the shape `session open` prints and a
1744
+ * `task up` manifest keeps per world. */
1745
+ type SurfaceDescriptor = {
1746
+ surfaces: WorldSurfaceKind[];
1747
+ api?: {
1748
+ url: string;
1749
+ token?: string;
1750
+ };
1751
+ ui?: {
1752
+ url: string;
1753
+ entry: string;
1754
+ apiPath: string | null;
1755
+ };
1756
+ browser?: {
1757
+ wsUrl: string;
1758
+ viewport?: unknown;
1759
+ tier?: BrowserTier;
1760
+ };
1761
+ };
1762
+ declare function surfaceDescriptor(s: SessionSurfaces): SurfaceDescriptor;
1763
+
1743
1764
  /** The per-world entry of a `WorldTaskSpec.worlds` table. */
1744
1765
  type WorldTaskWorld = {
1745
1766
  slug: string;
@@ -1785,21 +1806,7 @@ type TaskManifestSession = {
1785
1806
  sessionId: string;
1786
1807
  ready: boolean;
1787
1808
  state: string;
1788
- surfaces: WorldSurfaceKind[];
1789
- api?: {
1790
- url: string;
1791
- token?: string;
1792
- };
1793
- ui?: {
1794
- url: string;
1795
- entry: string;
1796
- apiPath: string | null;
1797
- };
1798
- browser?: {
1799
- wsUrl: string;
1800
- viewport?: unknown;
1801
- };
1802
- };
1809
+ } & SurfaceDescriptor;
1803
1810
  /** The manifest: every session of the task, keyed by alias. The file
1804
1811
  * `task up --out` writes and `task down|status|grade|export` read. */
1805
1812
  type TaskManifest = {
@@ -1969,7 +1976,11 @@ type RunTaskOptions = {
1969
1976
  surfaces?: WorldSurfaceKind[];
1970
1977
  /** Directory the run's own `<runId>/` folder is created under. Default `"runs"`. */
1971
1978
  outDir?: string;
1972
- /** Initialize tracing when GATEWAY_* credentials are configured. Default `true`. */
1979
+ /**
1980
+ * Initialize tracing when GATEWAY_* credentials are configured. Default `true`.
1981
+ * When it cannot start (e.g. the optional `@opentelemetry/*` peers are missing),
1982
+ * the run goes on untraced and the process warns once.
1983
+ */
1973
1984
  trace?: boolean;
1974
1985
  /** File one rollout when the run ends. Default `true`. */
1975
1986
  file?: boolean;
@@ -2126,6 +2137,41 @@ declare class GatewayEvalsClient {
2126
2137
  finalizeEvaluation(evaluationId: string, opts?: FinalizeEvaluationOptions): Promise<string>;
2127
2138
  }
2128
2139
 
2140
+ /** One vendor-route request the world answered, as its own log keeps it: the
2141
+ * `calls` a grader reads, with the door it came in by (`via`: api, ui, tool). */
2142
+ type WorldRequest = {
2143
+ seq: number;
2144
+ at?: string;
2145
+ operation?: string;
2146
+ method?: string;
2147
+ path?: string;
2148
+ args?: unknown;
2149
+ query?: unknown;
2150
+ body?: unknown;
2151
+ via?: string;
2152
+ status?: number;
2153
+ rows?: number | null;
2154
+ found?: boolean;
2155
+ };
2156
+ /**
2157
+ * The world's own request log, read from a live session's state. The platform's
2158
+ * call ledger (`export()`) holds what it brokered — tool calls, seeds, grades;
2159
+ * this holds the requests the world answered on its routes, the browser's and a
2160
+ * direct `api.url` client's included. A world without HTTP routes, or not on the
2161
+ * World Host, keeps none.
2162
+ */
2163
+ declare class WorldRequestLog {
2164
+ readonly requests: WorldRequest[];
2165
+ private constructor();
2166
+ static read(session: WorldSession): Promise<WorldRequestLog | null>;
2167
+ /** How many older requests the world no longer keeps (its log is bounded): the gap
2168
+ * before the first entry it still holds. */
2169
+ get dropped(): number;
2170
+ /** Each request in the shape of a ledger line, `kind: "request"`, so one JSONL
2171
+ * file holds both. */
2172
+ asCalls(): WorldSessionCall[];
2173
+ }
2174
+
2129
2175
  /** One entry the archive rules dropped: a whole directory (`name/`, `files`
2130
2176
  * counted) or a single file. */
2131
2177
  type Exclusion = {
@@ -2455,6 +2501,8 @@ type WorldField = {
2455
2501
  required: boolean;
2456
2502
  /** How the store holds it; null means in the clear (queryable by plaintext as given). */
2457
2503
  redaction: Redaction | null;
2504
+ /** The values the schema allows; absent when it lists none. */
2505
+ enum?: unknown[];
2458
2506
  };
2459
2507
  type WorldRelationship = {
2460
2508
  fields: string[];
@@ -3712,4 +3760,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
3712
3760
  */
3713
3761
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
3714
3762
 
3715
- export { ACTION_NAMES, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkModelOutput, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult, 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, ComputerAction, type ComputerCallOutput, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, Display, 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, KEY_NAMES, KeyChord, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NOT_EXECUTED, NO_GRADER_REASON, NativeComputer, type NativeComputerKinds, type NativeComputerOptions, type NativeComputerProvider, type NativePage, type ObservationConversion, type ObservationLike, OpenAIComputer, OpenAIPreviewComputer, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, PendingSafetyChecks, type Plaintext, PlatformMethod, 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, SECRET_KEY, SESSION_STATES, SPAN_PREFIX, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SafetyCheck, 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, Screen, type ScreenBrowser, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, TaskEditClient, type TaskEditCloseInput, type TaskEditCloseResult, type TaskEditRollbackInput, type TaskEditRollbackResult, type TaskEditSealed, type TaskEditStatus, type TaskEditTarget, type TaskEditTaskRef, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldRef, 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, playwrightKey, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readField, 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 };
3763
+ export { ACTION_NAMES, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkModelOutput, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult, 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, ComputerAction, type ComputerCallOutput, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, Display, 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, KEY_NAMES, KeyChord, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NOT_EXECUTED, NO_GRADER_REASON, NativeComputer, type NativeComputerKinds, type NativeComputerOptions, type NativeComputerProvider, type NativePage, type ObservationConversion, type ObservationLike, OpenAIComputer, OpenAIPreviewComputer, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, PendingSafetyChecks, type Plaintext, PlatformMethod, 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, SECRET_KEY, SESSION_STATES, SPAN_PREFIX, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SafetyCheck, 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, Screen, type ScreenBrowser, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, type SurfaceDescriptor, TRANSFORMS, TaskEditClient, type TaskEditCloseInput, type TaskEditCloseResult, type TaskEditRollbackInput, type TaskEditRollbackResult, type TaskEditSealed, type TaskEditStatus, type TaskEditTarget, type TaskEditTaskRef, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldRef, 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, type WorldRequest, WorldRequestLog, 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, playwrightKey, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readField, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceDescriptor, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
@@ -1689,7 +1689,7 @@ type ListSessionsFilter = {
1689
1689
  slug?: string;
1690
1690
  limit?: number;
1691
1691
  };
1692
- /** The project's live sessions, newest first — the ones an agent can attach to. */
1692
+ /** The project's sessions in every state, newest first; `state` narrows to one. */
1693
1693
  declare function listSessions(filter?: ListSessionsFilter, options?: WorldsClientOptions): Promise<WorldSessionListItem[]>;
1694
1694
 
1695
1695
  /**
@@ -1740,6 +1740,27 @@ declare function serializeCallBody(body: unknown): string;
1740
1740
  * `IDLE_WARNING_MINUTES` left, else null. `now` is for tests. */
1741
1741
  declare function idleWarning(idleExpiresAt: string | null | undefined, now?: Date): string | null;
1742
1742
 
1743
+ /** Where a session answers, in the shape `session open` prints and a
1744
+ * `task up` manifest keeps per world. */
1745
+ type SurfaceDescriptor = {
1746
+ surfaces: WorldSurfaceKind[];
1747
+ api?: {
1748
+ url: string;
1749
+ token?: string;
1750
+ };
1751
+ ui?: {
1752
+ url: string;
1753
+ entry: string;
1754
+ apiPath: string | null;
1755
+ };
1756
+ browser?: {
1757
+ wsUrl: string;
1758
+ viewport?: unknown;
1759
+ tier?: BrowserTier;
1760
+ };
1761
+ };
1762
+ declare function surfaceDescriptor(s: SessionSurfaces): SurfaceDescriptor;
1763
+
1743
1764
  /** The per-world entry of a `WorldTaskSpec.worlds` table. */
1744
1765
  type WorldTaskWorld = {
1745
1766
  slug: string;
@@ -1785,21 +1806,7 @@ type TaskManifestSession = {
1785
1806
  sessionId: string;
1786
1807
  ready: boolean;
1787
1808
  state: string;
1788
- surfaces: WorldSurfaceKind[];
1789
- api?: {
1790
- url: string;
1791
- token?: string;
1792
- };
1793
- ui?: {
1794
- url: string;
1795
- entry: string;
1796
- apiPath: string | null;
1797
- };
1798
- browser?: {
1799
- wsUrl: string;
1800
- viewport?: unknown;
1801
- };
1802
- };
1809
+ } & SurfaceDescriptor;
1803
1810
  /** The manifest: every session of the task, keyed by alias. The file
1804
1811
  * `task up --out` writes and `task down|status|grade|export` read. */
1805
1812
  type TaskManifest = {
@@ -1969,7 +1976,11 @@ type RunTaskOptions = {
1969
1976
  surfaces?: WorldSurfaceKind[];
1970
1977
  /** Directory the run's own `<runId>/` folder is created under. Default `"runs"`. */
1971
1978
  outDir?: string;
1972
- /** Initialize tracing when GATEWAY_* credentials are configured. Default `true`. */
1979
+ /**
1980
+ * Initialize tracing when GATEWAY_* credentials are configured. Default `true`.
1981
+ * When it cannot start (e.g. the optional `@opentelemetry/*` peers are missing),
1982
+ * the run goes on untraced and the process warns once.
1983
+ */
1973
1984
  trace?: boolean;
1974
1985
  /** File one rollout when the run ends. Default `true`. */
1975
1986
  file?: boolean;
@@ -2126,6 +2137,41 @@ declare class GatewayEvalsClient {
2126
2137
  finalizeEvaluation(evaluationId: string, opts?: FinalizeEvaluationOptions): Promise<string>;
2127
2138
  }
2128
2139
 
2140
+ /** One vendor-route request the world answered, as its own log keeps it: the
2141
+ * `calls` a grader reads, with the door it came in by (`via`: api, ui, tool). */
2142
+ type WorldRequest = {
2143
+ seq: number;
2144
+ at?: string;
2145
+ operation?: string;
2146
+ method?: string;
2147
+ path?: string;
2148
+ args?: unknown;
2149
+ query?: unknown;
2150
+ body?: unknown;
2151
+ via?: string;
2152
+ status?: number;
2153
+ rows?: number | null;
2154
+ found?: boolean;
2155
+ };
2156
+ /**
2157
+ * The world's own request log, read from a live session's state. The platform's
2158
+ * call ledger (`export()`) holds what it brokered — tool calls, seeds, grades;
2159
+ * this holds the requests the world answered on its routes, the browser's and a
2160
+ * direct `api.url` client's included. A world without HTTP routes, or not on the
2161
+ * World Host, keeps none.
2162
+ */
2163
+ declare class WorldRequestLog {
2164
+ readonly requests: WorldRequest[];
2165
+ private constructor();
2166
+ static read(session: WorldSession): Promise<WorldRequestLog | null>;
2167
+ /** How many older requests the world no longer keeps (its log is bounded): the gap
2168
+ * before the first entry it still holds. */
2169
+ get dropped(): number;
2170
+ /** Each request in the shape of a ledger line, `kind: "request"`, so one JSONL
2171
+ * file holds both. */
2172
+ asCalls(): WorldSessionCall[];
2173
+ }
2174
+
2129
2175
  /** One entry the archive rules dropped: a whole directory (`name/`, `files`
2130
2176
  * counted) or a single file. */
2131
2177
  type Exclusion = {
@@ -2455,6 +2501,8 @@ type WorldField = {
2455
2501
  required: boolean;
2456
2502
  /** How the store holds it; null means in the clear (queryable by plaintext as given). */
2457
2503
  redaction: Redaction | null;
2504
+ /** The values the schema allows; absent when it lists none. */
2505
+ enum?: unknown[];
2458
2506
  };
2459
2507
  type WorldRelationship = {
2460
2508
  fields: string[];
@@ -3712,4 +3760,4 @@ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Prom
3712
3760
  */
3713
3761
  declare function openWorldVersion(slug: string, versionId: string, options?: WorldsClientOptions): Promise<WorldSet>;
3714
3762
 
3715
- export { ACTION_NAMES, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkModelOutput, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult, 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, ComputerAction, type ComputerCallOutput, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, Display, 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, KEY_NAMES, KeyChord, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NOT_EXECUTED, NO_GRADER_REASON, NativeComputer, type NativeComputerKinds, type NativeComputerOptions, type NativeComputerProvider, type NativePage, type ObservationConversion, type ObservationLike, OpenAIComputer, OpenAIPreviewComputer, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, PendingSafetyChecks, type Plaintext, PlatformMethod, 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, SECRET_KEY, SESSION_STATES, SPAN_PREFIX, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SafetyCheck, 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, Screen, type ScreenBrowser, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, TRANSFORMS, TaskEditClient, type TaskEditCloseInput, type TaskEditCloseResult, type TaskEditRollbackInput, type TaskEditRollbackResult, type TaskEditSealed, type TaskEditStatus, type TaskEditTarget, type TaskEditTaskRef, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldRef, 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, playwrightKey, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readField, 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 };
3763
+ export { ACTION_NAMES, type ActionArgs, type ActionResult, ActionTracer, type AiSdkAnthropicOutput, type AiSdkComputerCall, type AiSdkComputerOutput, type AiSdkModelOutput, AnthropicComputer, AnthropicComputer20251124, type AnthropicToolResult, 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, ComputerAction, type ComputerCallOutput, type CreateEvaluationOptions, DEFAULT_BRANCH, DEFAULT_VIEWPORT, DRY_RUN_AGENT, DRY_RUN_KIND, DetachedPushError, type DispatchedRun, Display, 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, KEY_NAMES, KeyChord, type ListRunsFilter, type ListSessionsFilter, type LiveTaskSession, type LocalMeta, type MigrateWorldOptions, NOT_EXECUTED, NO_GRADER_REASON, NativeComputer, type NativeComputerKinds, type NativeComputerOptions, type NativeComputerProvider, type NativePage, type ObservationConversion, type ObservationLike, OpenAIComputer, OpenAIPreviewComputer, type OpenSessionOptions, type OpenTaskOptions, type ParsedToolCall, PendingSafetyChecks, type Plaintext, PlatformMethod, 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, SECRET_KEY, SESSION_STATES, SPAN_PREFIX, STATUS_WAIT_CAP_SECONDS, STRIP_PREFIX, SURFACE_KINDS, type SafetyCheck, 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, Screen, type ScreenBrowser, SecretScrubber, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type SetRunDoc, type SettleOptions, type SlugDeclaration, type SurfaceDescriptor, TRANSFORMS, TaskEditClient, type TaskEditCloseInput, type TaskEditCloseResult, type TaskEditRollbackInput, type TaskEditRollbackResult, type TaskEditSealed, type TaskEditStatus, type TaskEditTarget, type TaskEditTaskRef, type TaskExport, type TaskGrade, type TaskManifest, type TaskManifestSession, TaskRun, type TaskRunResult, TaskSessions, type TaskSessionsResponse, type TaskWorldRef, 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, type WorldRequest, WorldRequestLog, 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, playwrightKey, preserveForm, propose, pull, push, pushBranch, pushSlug, pyText, queryRows, queryRowsSearch, readField, readLocalMeta, readToolCallRecords, rebaseConflicts, redactActionArgs, redactionOf, releaseConnection, resolveBrowserMode, resolvePushSlug, roundForm, runSessions, runSet, runTask, schemaFromSignature, serializeCallBody, sessionToolObservations, setEnvSecret, shapeText, snapshotTreeHashes, storedForms, surfaceDescriptor, surfaceKinds, taskLabel, toolCallRecordsIn, toolCallsFromObservations, uiEntryUrl, uiUrl, uncommittedPaths, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
@@ -3057,6 +3057,28 @@ var init_tasks = __esm({
3057
3057
  }
3058
3058
  });
3059
3059
 
3060
+ // src/worlds/surfaceDescriptor.ts
3061
+ function surfaceDescriptor(s) {
3062
+ return {
3063
+ surfaces: surfaceKinds(s),
3064
+ ...s.api ? { api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} } } : {},
3065
+ ...s.ui ? { ui: { url: s.ui.url, entry: uiEntryUrl(s.ui), apiPath: s.ui.apiPath ?? null } } : {},
3066
+ ...s.browser ? {
3067
+ browser: {
3068
+ wsUrl: s.browser.wsUrl,
3069
+ viewport: s.browser.viewport,
3070
+ ...s.browser.tier ? { tier: s.browser.tier } : {}
3071
+ }
3072
+ } : {}
3073
+ };
3074
+ }
3075
+ var init_surfaceDescriptor = __esm({
3076
+ "src/worlds/surfaceDescriptor.ts"() {
3077
+ "use strict";
3078
+ init_browser();
3079
+ }
3080
+ });
3081
+
3060
3082
  // src/worlds/taskSessions.ts
3061
3083
  function aggregateTaskGrade(worlds) {
3062
3084
  const rewards = {};
@@ -3207,6 +3229,7 @@ var init_taskSessions = __esm({
3207
3229
  "use strict";
3208
3230
  init_worlds();
3209
3231
  init_browser();
3232
+ init_surfaceDescriptor();
3210
3233
  init_session2();
3211
3234
  TASK_SESSIONS = "/api/public/world-task-sessions";
3212
3235
  VERIFIER_REWARD_PREFIX = "x.";
@@ -3218,18 +3241,7 @@ var init_taskSessions = __esm({
3218
3241
  sessionId: state2.sessionId,
3219
3242
  ready: state2.ready,
3220
3243
  state: state2.state,
3221
- surfaces: surfaceKinds(s),
3222
- ...s.api ? {
3223
- api: { url: s.api.url, ...s.api.token ? { token: s.api.token } : {} }
3224
- } : {},
3225
- ...s.ui ? {
3226
- ui: {
3227
- url: s.ui.url,
3228
- entry: uiEntryUrl(s.ui),
3229
- apiPath: s.ui.apiPath ?? null
3230
- }
3231
- } : {},
3232
- ...s.browser ? { browser: { wsUrl: s.browser.wsUrl, viewport: s.browser.viewport } } : {}
3244
+ ...surfaceDescriptor(s)
3233
3245
  });
3234
3246
  TaskSessions = class {
3235
3247
  constructor(taskId, taskVersion, name, instruction, sessions, worlds, hash = null) {
@@ -3408,6 +3420,49 @@ var init_evals = __esm({
3408
3420
  }
3409
3421
  });
3410
3422
 
3423
+ // src/tracing/prerequisites.ts
3424
+ function getEnv(key) {
3425
+ const value = process.env[key];
3426
+ return value ? value : void 0;
3427
+ }
3428
+ function isGatewayConfigured() {
3429
+ return !!(getEnv(GATEWAY_ENV.HOST) && getEnv(GATEWAY_ENV.PUBLIC_KEY) && getEnv(GATEWAY_ENV.SECRET_KEY));
3430
+ }
3431
+ var GATEWAY_ENV, OPENTELEMETRY_PEERS, MODULE_NOT_FOUND, OpenTelemetryMissing;
3432
+ var init_prerequisites = __esm({
3433
+ "src/tracing/prerequisites.ts"() {
3434
+ "use strict";
3435
+ GATEWAY_ENV = {
3436
+ HOST: "GATEWAY_HOST",
3437
+ PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
3438
+ SECRET_KEY: "GATEWAY_SECRET_KEY",
3439
+ ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
3440
+ };
3441
+ OPENTELEMETRY_PEERS = [
3442
+ "@opentelemetry/api",
3443
+ "@opentelemetry/exporter-trace-otlp-http",
3444
+ "@opentelemetry/resources",
3445
+ "@opentelemetry/sdk-trace-base",
3446
+ "@opentelemetry/sdk-trace-node"
3447
+ ];
3448
+ MODULE_NOT_FOUND = /* @__PURE__ */ new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
3449
+ OpenTelemetryMissing = class _OpenTelemetryMissing extends Error {
3450
+ constructor() {
3451
+ super(
3452
+ `OpenTelemetry packages not found. Install them with:
3453
+ npm install ${OPENTELEMETRY_PEERS.join(" ")}`
3454
+ );
3455
+ this.name = "OpenTelemetryMissing";
3456
+ }
3457
+ static explains(error) {
3458
+ if (error instanceof _OpenTelemetryMissing) return true;
3459
+ const { code, message } = error ?? {};
3460
+ return MODULE_NOT_FOUND.has(String(code)) && String(message).includes("@opentelemetry/");
3461
+ }
3462
+ };
3463
+ }
3464
+ });
3465
+
3411
3466
  // src/users/index.ts
3412
3467
  function parseEvent(payload) {
3413
3468
  return {
@@ -4091,7 +4146,7 @@ var require_package = __commonJS({
4091
4146
  "package.json"(exports2, module2) {
4092
4147
  module2.exports = {
4093
4148
  name: "@withgateway/sdk",
4094
- version: "0.3.0",
4149
+ version: "0.3.1",
4095
4150
  description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
4096
4151
  main: "./dist/index.js",
4097
4152
  module: "./dist/index.mjs",
@@ -4500,10 +4555,6 @@ __export(init_exports, {
4500
4555
  isInitialized: () => isInitialized,
4501
4556
  shutdown: () => shutdown
4502
4557
  });
4503
- function getEnv(key) {
4504
- const value = process.env[key];
4505
- return value ? value : void 0;
4506
- }
4507
4558
  function log(message, ...args) {
4508
4559
  if (state.debug) {
4509
4560
  console.log(`[gatewaysdk.tracing] ${message}`, ...args);
@@ -4513,10 +4564,10 @@ function warn(message, ...args) {
4513
4564
  console.warn(`[gatewaysdk.tracing] ${message}`, ...args);
4514
4565
  }
4515
4566
  function buildProvider(config, logFn) {
4516
- const host = config.host ?? getEnv(ENV_VARS.HOST);
4517
- const publicKey = config.publicKey ?? getEnv(ENV_VARS.PUBLIC_KEY);
4518
- const secretKey = config.secretKey ?? getEnv(ENV_VARS.SECRET_KEY);
4519
- const endpoint = config.endpoint ?? getEnv(ENV_VARS.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4567
+ const host = config.host ?? getEnv(GATEWAY_ENV.HOST);
4568
+ const publicKey = config.publicKey ?? getEnv(GATEWAY_ENV.PUBLIC_KEY);
4569
+ const secretKey = config.secretKey ?? getEnv(GATEWAY_ENV.SECRET_KEY);
4570
+ const endpoint = config.endpoint ?? getEnv(GATEWAY_ENV.ENDPOINT) ?? (host ? `${host.replace(/\/$/, "")}${DEFAULT_OTLP_PATH}` : void 0);
4520
4571
  const missing = [];
4521
4572
  if (!host) missing.push("host (or GATEWAY_HOST env var)");
4522
4573
  if (!publicKey) missing.push("publicKey (or GATEWAY_PUBLIC_KEY env var)");
@@ -4553,9 +4604,7 @@ function buildProvider(config, logFn) {
4553
4604
  ATTR_SERVICE_NAME = "service.name";
4554
4605
  }
4555
4606
  } catch {
4556
- throw new Error(
4557
- "OpenTelemetry packages not found. Install them with:\nnpm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources"
4558
- );
4607
+ throw new OpenTelemetryMissing();
4559
4608
  }
4560
4609
  const resourceAttrs = {
4561
4610
  [ATTR_SERVICE_NAME]: config.serviceName ?? "gatewaysdk-tracing"
@@ -4761,13 +4810,7 @@ async function shutdown() {
4761
4810
  function isInitialized() {
4762
4811
  return state.initialized;
4763
4812
  }
4764
- function isGatewayConfigured() {
4765
- const host = getEnv(ENV_VARS.HOST);
4766
- const publicKey = getEnv(ENV_VARS.PUBLIC_KEY);
4767
- const secretKey = getEnv(ENV_VARS.SECRET_KEY);
4768
- return !!(host && publicKey && secretKey);
4769
- }
4770
- var ENV_VARS, DEFAULT_OTLP_PATH, state;
4813
+ var DEFAULT_OTLP_PATH, state;
4771
4814
  var init_init = __esm({
4772
4815
  "src/tracing/init.ts"() {
4773
4816
  "use strict";
@@ -4776,12 +4819,8 @@ var init_init = __esm({
4776
4819
  init_session();
4777
4820
  init_scores();
4778
4821
  init_build();
4779
- ENV_VARS = {
4780
- HOST: "GATEWAY_HOST",
4781
- PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
4782
- SECRET_KEY: "GATEWAY_SECRET_KEY",
4783
- ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
4784
- };
4822
+ init_prerequisites();
4823
+ init_prerequisites();
4785
4824
  DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
4786
4825
  state = {
4787
4826
  initialized: false,
@@ -4790,6 +4829,45 @@ var init_init = __esm({
4790
4829
  }
4791
4830
  });
4792
4831
 
4832
+ // src/worlds/taskTracing.ts
4833
+ var TaskTracing;
4834
+ var init_taskTracing = __esm({
4835
+ "src/worlds/taskTracing.ts"() {
4836
+ "use strict";
4837
+ init_prerequisites();
4838
+ TaskTracing = class _TaskTracing {
4839
+ constructor(load = () => Promise.resolve().then(() => (init_init(), init_exports))) {
4840
+ this.load = load;
4841
+ }
4842
+ load;
4843
+ static warned = false;
4844
+ async start(requested) {
4845
+ if (!requested || !isGatewayConfigured()) return false;
4846
+ try {
4847
+ (await this.load()).init();
4848
+ return true;
4849
+ } catch (error) {
4850
+ _TaskTracing.warnOnce(error);
4851
+ return false;
4852
+ }
4853
+ }
4854
+ static warnOnce(error) {
4855
+ if (_TaskTracing.warned) return;
4856
+ _TaskTracing.warned = true;
4857
+ console.warn(
4858
+ `[gatewaysdk.tracing] Task runs in this process are not traced. ${_TaskTracing.reason(error)}
4859
+ Pass --no-trace (trace: false) to run untraced without this warning.`
4860
+ );
4861
+ }
4862
+ static reason(error) {
4863
+ if (OpenTelemetryMissing.explains(error))
4864
+ return new OpenTelemetryMissing().message;
4865
+ return error instanceof Error ? error.message : String(error);
4866
+ }
4867
+ };
4868
+ }
4869
+ });
4870
+
4793
4871
  // src/worlds/taskRun.ts
4794
4872
  function worldRef(live, alias) {
4795
4873
  const { slug, ref } = live.worldRef(alias);
@@ -4902,18 +4980,7 @@ async function runTask(ref, agent, opts) {
4902
4980
  const started = Date.now();
4903
4981
  try {
4904
4982
  await live.ready();
4905
- let traced = false;
4906
- if (opts.trace !== false) {
4907
- try {
4908
- const { isGatewayConfigured: isGatewayConfigured2, init: init2 } = await Promise.resolve().then(() => (init_init(), init_exports));
4909
- if (isGatewayConfigured2()) {
4910
- init2();
4911
- traced = true;
4912
- }
4913
- } catch {
4914
- traced = false;
4915
- }
4916
- }
4983
+ const traced = await new TaskTracing().start(opts.trace !== false);
4917
4984
  const taskRun = new TaskRun(
4918
4985
  runId,
4919
4986
  live.instruction ?? "",
@@ -5004,6 +5071,7 @@ var init_taskRun = __esm({
5004
5071
  init_evals();
5005
5072
  init_session2();
5006
5073
  init_taskSessions();
5074
+ init_taskTracing();
5007
5075
  TaskRun = class {
5008
5076
  constructor(runId, instruction, model, sessions, manifest) {
5009
5077
  this.runId = runId;
@@ -5207,6 +5275,52 @@ var init_setRun = __esm({
5207
5275
  }
5208
5276
  });
5209
5277
 
5278
+ // src/worlds/requestLog.ts
5279
+ var WorldRequestLog;
5280
+ var init_requestLog = __esm({
5281
+ "src/worlds/requestLog.ts"() {
5282
+ "use strict";
5283
+ WorldRequestLog = class _WorldRequestLog {
5284
+ constructor(requests) {
5285
+ this.requests = requests;
5286
+ }
5287
+ requests;
5288
+ static async read(session) {
5289
+ const state2 = await session.state();
5290
+ const calls = state2?.calls;
5291
+ if (!Array.isArray(calls)) return null;
5292
+ return new _WorldRequestLog(calls.filter((c) => typeof c === "object" && c !== null));
5293
+ }
5294
+ /** How many older requests the world no longer keeps (its log is bounded): the gap
5295
+ * before the first entry it still holds. */
5296
+ get dropped() {
5297
+ const first = Number(this.requests[0]?.seq) || 1;
5298
+ return Math.max(0, first - 1);
5299
+ }
5300
+ /** Each request in the shape of a ledger line, `kind: "request"`, so one JSONL
5301
+ * file holds both. */
5302
+ asCalls() {
5303
+ return this.requests.map((r) => ({
5304
+ seq: Number(r.seq) || 0,
5305
+ kind: "request",
5306
+ tool: r.operation ?? null,
5307
+ args: {
5308
+ method: r.method ?? null,
5309
+ path: r.path ?? null,
5310
+ args: r.args ?? null,
5311
+ query: r.query ?? null,
5312
+ body: r.body ?? null,
5313
+ via: r.via ?? null
5314
+ },
5315
+ result: { status: r.status ?? null, rows: r.rows ?? null, found: r.found ?? null },
5316
+ error: null,
5317
+ completedAt: r.at ?? null
5318
+ }));
5319
+ }
5320
+ };
5321
+ }
5322
+ });
5323
+
5210
5324
  // src/worlds/checkoutTarget.ts
5211
5325
  var fs2, path2, CheckoutRefusedError, NAMED_EDITS, CheckoutTarget;
5212
5326
  var init_checkoutTarget = __esm({
@@ -7036,7 +7150,7 @@ async function localBridge(request, local, opts = {}) {
7036
7150
  child.stdin.end(input);
7037
7151
  });
7038
7152
  }
7039
- var import_node_child_process2, fs7, net, path7, MIN_PYTHON, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7153
+ var import_node_child_process2, fs7, net, path7, MIN_PYTHON, MIN_PYTHON_LABEL, DIAGNOSTIC_TAIL, BRIDGE_BOOTSTRAP, pythonCache, pythonProbes, PYTHON_CANDIDATES, UV_FIND;
7040
7154
  var init_local = __esm({
7041
7155
  "src/cli/runtime/local.ts"() {
7042
7156
  "use strict";
@@ -7047,6 +7161,7 @@ var init_local = __esm({
7047
7161
  init_router();
7048
7162
  init_config();
7049
7163
  MIN_PYTHON = [3, 12];
7164
+ MIN_PYTHON_LABEL = MIN_PYTHON.join(".");
7050
7165
  DIAGNOSTIC_TAIL = 600;
7051
7166
  BRIDGE_BOOTSTRAP = `import sys,runpy,types,os
7052
7167
  root=sys.argv[1]
@@ -8416,6 +8531,7 @@ __export(worlds_exports, {
8416
8531
  WorldBrowser: () => WorldBrowser,
8417
8532
  WorldCallTooLarge: () => WorldCallTooLarge,
8418
8533
  WorldEditClient: () => WorldEditClient,
8534
+ WorldRequestLog: () => WorldRequestLog,
8419
8535
  WorldSandboxClient: () => WorldSandboxClient,
8420
8536
  WorldSession: () => WorldSession,
8421
8537
  WorldSessionCallError: () => WorldSessionCallError,
@@ -8509,6 +8625,7 @@ __export(worlds_exports, {
8509
8625
  shapeText: () => shapeText,
8510
8626
  snapshotTreeHashes: () => snapshotTreeHashes,
8511
8627
  storedForms: () => storedForms,
8628
+ surfaceDescriptor: () => surfaceDescriptor,
8512
8629
  surfaceKinds: () => surfaceKinds,
8513
8630
  taskLabel: () => taskLabel,
8514
8631
  toolCallRecordsIn: () => toolCallRecordsIn,
@@ -8750,6 +8867,8 @@ var init_worlds = __esm({
8750
8867
  init_checkoutProvenance();
8751
8868
  init_evals();
8752
8869
  init_browser();
8870
+ init_surfaceDescriptor();
8871
+ init_requestLog();
8753
8872
  init_browserReconnect();
8754
8873
  init_nativeComputer();
8755
8874
  init_hub();
@@ -8917,6 +9036,7 @@ init_worlds();
8917
9036
  WorldBrowser,
8918
9037
  WorldCallTooLarge,
8919
9038
  WorldEditClient,
9039
+ WorldRequestLog,
8920
9040
  WorldSandboxClient,
8921
9041
  WorldSession,
8922
9042
  WorldSessionCallError,
@@ -9010,6 +9130,7 @@ init_worlds();
9010
9130
  shapeText,
9011
9131
  snapshotTreeHashes,
9012
9132
  storedForms,
9133
+ surfaceDescriptor,
9013
9134
  surfaceKinds,
9014
9135
  taskLabel,
9015
9136
  toolCallRecordsIn,