@withgateway/sdk 0.2.8 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +2695 -657
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2675 -637
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -0
  7. package/dist/files/index.d.ts +1 -0
  8. package/dist/files/index.js +1443 -36
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +1441 -28
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-Cz8Q6Keo.d.mts → index-D6oi1TWE.d.mts} +93 -34
  13. package/dist/{index-BO2SNSgy.d.ts → index-DAb-FCMg.d.ts} +93 -34
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.ts +4 -3
  16. package/dist/index.js +1986 -235
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1941 -218
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/media-CbcAfQvd.d.mts +83 -0
  21. package/dist/media-CbcAfQvd.d.ts +83 -0
  22. package/dist/traces/index.d.mts +1 -0
  23. package/dist/traces/index.d.ts +1 -0
  24. package/dist/traces/index.js +1440 -33
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +1438 -25
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -1
  29. package/dist/tracing/index.d.ts +2 -1
  30. package/dist/tracing/index.js +512 -11
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +501 -10
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +614 -25
  35. package/dist/worlds/index.d.ts +614 -25
  36. package/dist/worlds/index.js +1923 -214
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1910 -201
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  42. package/runtime/gatewaysdk/environment/schema/api.py +38 -56
  43. package/runtime/gatewaysdk/environment/schema/grading.py +1 -5
  44. package/runtime/gatewaysdk/environment/schema/host.py +53 -90
  45. package/runtime/gatewaysdk/environment/schema/local.py +15 -7
  46. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  47. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
  48. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
  49. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  50. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +4 -2
  51. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
  52. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
  53. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  54. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  55. package/skills/benchmarks-getting-started/SKILL.md +3 -3
  56. package/skills/connector-schema-authoring/SKILL.md +1 -1
  57. package/skills/connector-schema-authoring/world-schema.md +1 -1
  58. package/skills/worlds-getting-started/SKILL.md +18 -18
  59. package/skills/worlds-getting-started/references/cli-mcp-map.md +4 -2
  60. package/skills/worlds-getting-started/references/gotchas.md +5 -1
  61. package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
package/README.md CHANGED
@@ -319,6 +319,14 @@ await session.close({ keepWarm: true });
319
319
  Sessions trace themselves from the platform — one trace per episode, one span
320
320
  per tool call — so an episode is readable even if your process dies mid-run.
321
321
 
322
+ **Request timeout.** Since 0.2.9 every platform request the SDK makes — sessions,
323
+ the worlds helpers and the CLI — is abandoned after **120 s** without an answer
324
+ and fails with one line naming the cause (connection refused, DNS lookup
325
+ failed, timed out) instead of waiting forever. Set `GATEWAY_TIMEOUT_MS` to a
326
+ positive whole number of milliseconds to change it (`GATEWAY_TIMEOUT_MS=300000`
327
+ for five minutes); any other value is refused. Sandbox requests keep their own
328
+ 660 s budget, since one `exec` may run for 600 s.
329
+
322
330
  **Full worked example:** [`examples/world-suite.ts`](examples/world-suite.ts)
323
331
  is a complete local production harness — a real tool-calling agent loop,
324
332
  parallel execution, a pass gate, a JSON artifact and a CI exit code. The
@@ -332,13 +340,13 @@ flags (`npm i -g @withgateway/sdk`, or `npx -p @withgateway/sdk gateway …`).
332
340
 
333
341
  The package bundles the schema runtime (the SDK's stdlib-only Python
334
342
  `gatewaysdk/environment` directory, the same files the platform executes). With
335
- any `python3 >= 3.11` on the machine the CLI runs it locally — `worlds serve`,
343
+ any `python3 >= 3.12` on the machine the CLI runs it locally — `worlds serve`,
336
344
  `connector capture`, `schema check|compile|describe`, `data import` on a
337
345
  directory — with no pip and no login. Without one, those commands send the
338
346
  world's files to `POST /api/public/worlds/runtime` and the platform runs the
339
347
  same code. `GATEWAY_RUNTIME=local|platform` forces a side. The interpreter is
340
348
  `GATEWAY_PYTHON` when set, else the first of `python3.13`, `python3.12`,
341
- `python3.11`, `python3`, `python`, then `uv python find` that is new enough — a
349
+ `python3`, `python`, then `uv python find` that is new enough — a
342
350
  Mac whose `python3` is the system 3.9 gets one line naming `GATEWAY_PYTHON`
343
351
  (`GATEWAY_PYTHON="$(brew --prefix python@3.12)/bin/python3.12"` or
344
352
  `GATEWAY_PYTHON="$(uv python find 3.12)"`). Only `bench eval|install|harvest-harbor`
@@ -351,14 +359,19 @@ gateway bench --help # every command in a group
351
359
  gateway bench push --help # a command's positionals and flags
352
360
  ```
353
361
 
354
- Credentials resolve in this order: `--host` / `--api-key` flags, then
355
- `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` / `GATEWAY_SECRET_KEY`, then
356
- `~/.gateway/config.json` written by `gateway auth login`. `GATEWAY_ENV_FILE=path`
362
+ Credentials resolve in this order: `--host` (and `--api-key` on `secret`,
363
+ `agent`, `run`, `dataset upload`, `release gate`, `traces import` and
364
+ `worlds serve`), then `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
365
+ `GATEWAY_SECRET_KEY` (`GATEWAY_API_KEY` is accepted for the secret key), then
366
+ `~/.gateway/config.json` written by `gateway auth login` (`GATEWAY_CONFIG_DIR`
367
+ moves it). `auth login` needs all three of `--host`, `--public-key` and
368
+ `--api-key`, each of which may come from its environment variable instead. `GATEWAY_ENV_FILE=path`
357
369
  loads a `KEY=value` file into the environment first, in the form people write it
358
370
  — `KEY = value`, quoted values, `export KEY=value` and `#` comments are all
359
371
  accepted, so the file need not be shell-sourceable; a variable already in the
360
372
  shell's environment wins. Commands print JSON where the Python CLI does and exit
361
- non-zero with the reason on stderr.
373
+ non-zero with the reason on stderr. A request with no answer in 120 s ends the
374
+ command the same way; `GATEWAY_TIMEOUT_MS` changes that budget.
362
375
 
363
376
  | Group | Commands |
364
377
  | --- | --- |
@@ -368,7 +381,8 @@ non-zero with the reason on stderr.
368
381
  | `run` | `start`, `verify`, `list` |
369
382
  | `dataset` | `upload FILE --name …` |
370
383
  | `bench` | `push`, `pull`, `checkout`, `fork`, `diff`, `propose`, `status`, `log`, `branch`, `tag`, `dispatch`, `run`, `run-configs`, `secrets`, `validate`, `resolve`, `tasks`, `refs`, `proposals` |
371
- | `worlds session` | `open`, `status`, `browse`, `close`, `seed`, `export` |
384
+ | `worlds session` | `open`, `status`, `list`, `state`, `reset`, `grade`, `browse`, `seed`, `export`, `pin`, `close`, `reopen`, `task save` |
385
+ | `worlds sandbox` | `open`, `status`, `list`, `read`, `write`, `exec`, `check`, `commit [--rebase]`, `import`, `close [--force]` — edit a world server-side; nothing lands on this disk |
372
386
  | `worlds describe` | what a world holds and how each field is stored — entities, keys, relationships, row counts, the `[redact]` policy per field — for a directory or a platform slug |
373
387
  | `worlds schema` | `templates`, `init`, `compile`, `check`, `describe` (the schema runtime runs on the platform) |
374
388
  | `worlds connector` | `validate`, `capture`, `conform`, `ingest`, `publish`, `list`, `pull`, `clone`, `skill` |
@@ -382,7 +396,7 @@ Python-only, and said so by the command itself (exit 2 with the equivalent):
382
396
  `bench eval` (local engines → `bench dispatch`), `bench install`,
383
397
  `bench harvest-harbor`, `bench push --build-wheel`, `deploy`, `init`,
384
398
  `algorithm list|new`. `worlds serve` runs the bundled runtime with any
385
- `python3 >= 3.11`, and opens a hosted `api` session when there is none.
399
+ `python3 >= 3.12`, and opens a hosted `api` session when there is none.
386
400
 
387
401
  Rows files for `worlds data import` and `worlds session seed` are a JSON
388
402
  object `{"<entity>": [row, …]}`, JSONL of `{"entity", "row"}` lines, or bare
@@ -485,6 +499,8 @@ gateway worlds skill --install . # land every guide (and its agen
485
499
  | `worlds-getting-started` | building a world or environment from scratch: templates, workspace connectors, vendor captures, custom contracts; publishing, sessions, running, iterating |
486
500
  | `world-data-ingestion` | putting rows into a world from any source: rows-file contract, `worlds data import\|check\|extract`, session seeding and export, refusals |
487
501
  | `connector-schema-authoring` | writing a connector schema world (`gateway-world/1`) by hand or from a vendor spec |
502
+ | `benchmarks-getting-started` | building, dry-running, pushing and running a benchmark: a world with `[[tasks]]` or a harbor / verifiers container benchmark |
503
+ | `hooks-getting-started` | rules around an agent's tool calls from one `gateway-hooks.toml`: the alias door, redaction, per-task overrides, `gateway hooks check` |
488
504
 
489
505
  `--install DIR` writes the skills under `DIR/.claude/skills/` (and the
490
506
  connector-template-author agent under `DIR/.claude/agents/`), so the agent