@withgateway/sdk 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -26,6 +26,12 @@ gateway worlds schema init ./x --from-openapi github.json --include '/repos/{own
26
26
  Inside a world sandbox (`run_gateway_cli`, `sandbox exec`) only a workspace path is accepted:
27
27
  write the document into the workspace first (`sandbox write --from spec.yaml`), then import.
28
28
 
29
+ The import itself runs in this machine's schema runtime whenever it has one; `GATEWAY_RUNTIME=local`
30
+ demands it and sends nothing to the platform. A YAML document is read by PyYAML in the Python that
31
+ runs the runtime: without it the command stops before anything is sent and names the fix
32
+ (`pip install pyyaml` there, point `GATEWAY_PYTHON` at a Python that has it, or convert the
33
+ document to JSON).
34
+
29
35
  ## What the plan says
30
36
 
31
37
  `--from-openapi` always prints the plan first (JSON, one object):
@@ -50,28 +56,51 @@ With `--plan-only` the same object carries `"written": false` and no `domain`/`n
50
56
 
51
57
  ## Conversion rules (decided; the importer documents them in `schema/provenance.json`)
52
58
 
53
- - **Entities.** Every object schema under `definitions` / `components.schemas` that some selected
54
- operation returns and that has an id-like key (`id`, `<name>Id`, `<name>_id`, a `readOnly`
55
- field the vendor marks `x-unique`/`x-primary-key`, else the first `required` string/integer field) becomes a `$defs` entry plus
56
- `x-gateway.entities.<snake_plural>` with `primary_key` (snake_case, at most 64 characters —
57
- a longer vendor name is truncated, the original kept in provenance). Keyless objects stay `$defs`,
58
- referenced inline. `allOf` is merged; `oneOf`/`anyOf` become a union the world validator
59
- accepts. Entity roots close (`additionalProperties: false`); the vendor's field names are kept
60
- as spelled (so a rows file shaped like the vendor's response imports as it is); the vendor's
61
- schema name stays the `$defs` key and `schema/provenance.json` maps every entity and operation
62
- back to its source name and JSON pointer.
59
+ - **Entities are the rows the routes carry.** The importer reads each selected operation's
60
+ response and request body through the vendor's envelope to the item schema: an array of
61
+ objects, or an object that declares no key and holds exactly one array (Crossref's
62
+ `{status, message: {items: [Work], total-results}}`, ClinicalTrials.gov's
63
+ `{studies: [Study], nextPageToken}`); a single-row response is the item when some list carries
64
+ it, it declares a key, or it names the field the route's own `{segment}` reads it by, else the
65
+ one object its wrapper holds. Wrappers never become entities. An item no planned route reads or
66
+ writes is no entity either (it stays an inline `$def`). Each entity is a `$defs` entry plus
67
+ `x-gateway.entities.<snake_plural>` with `primary_key` (snake_case, at most 64 characters, the
68
+ original kept in provenance); `allOf` is merged; `oneOf`/`anyOf` become a union the world
69
+ validator accepts. Entity roots close (`additionalProperties: false`); the vendor's field names
70
+ are kept exactly as spelled, hyphens included (`reference-count`), so a rows file shaped like
71
+ the vendor's response imports as it is.
72
+ - **Keys.** A declared key first (`id`, `<name>Id`, `<name>_id`, a `readOnly` field the vendor
73
+ marks `x-unique`/`x-primary-key`), else the field the single-row route reads the row by:
74
+ top-level and spelled the vendor's way (`/works/{doi}` → `DOI`), or nested in the row's
75
+ objects (`/studies/{nctId}` → the JSON Pointer `/protocolSection/identificationModule/nctId`,
76
+ every object on the path made required; never through an array or a nullable object). An item
77
+ only list routes carry falls back to its first required string/integer field, with a warning
78
+ that rows sharing it collapse: mark the key with `x-primary-key` or include the read route.
63
79
  - **Routes.** Every path+method in `get|post|put|patch|delete` becomes an `[[operations]]` entry:
64
80
  `name` = `operationId` snake_cased, at most 64 characters, deduped with `_2`, `_3` and a
65
- warning; `entity` = the response schema's entity when it resolves to one (an array → a list
66
- route, an object → `read|create|update|delete` by method); path parameters and declared query
67
- parameters become `params`; a `{data: [...]}` wrapper becomes `results`; on a list route a
68
- declared query parameter that names a top-level entity field becomes a `filter` (paging names
69
- such as `page`, `limit`, `offset`, `cursor` never do). A path that repeats a placeholder
70
- (`/a/{id}/{id}`) is skipped with its reason. An operation whose response is not an
71
- entity (login, upload, HTML) stays a **passthrough** route with no entity — it is served, and
72
- answers `501 {"error": "not_modelled"}` until you give it a handler.
81
+ warning; `entity` = the entity its response (or, for a write, its body or the path's `GET`)
82
+ carries, a list route or `read|create|update|delete` by method; path parameters and declared
83
+ query parameters become `params`, the vendor's names kept, dots included (`query.bibliographic`,
84
+ `filter.overallStatus`). The envelope's path becomes `results` and the route's dotted
85
+ `envelope` (`message.items`), and the rest of the envelope its `wrapper`, so the served world
86
+ answers the vendor's shape (`{status: "ok", message-type: "work-list", message: {items, …}}`).
87
+ On a list route a declared query parameter that names an entity field becomes a `filter`
88
+ (paging names never do). A single read whose path argument names no field of the row, and an
89
+ operation whose response is not an entity (login, upload, HTML), stay **passthrough** routes with
90
+ no entity, the reason in the plan — served, answering `501 {"error": "not_modelled"}` until you
91
+ give them a handler.
92
+ - **Paging.** A cursor parameter (`cursor`, `pageToken`) with a next-cursor field beside the rows
93
+ (`next-cursor`, `nextPageToken`) pages by cursor; an `offset` parameter by offset; the limit's
94
+ `default` becomes `page_size`; the count beside the rows (`total-results`, `totalCount`) is the
95
+ hits key. `[api]` pages the way most list routes do, a route paging otherwise names its own
96
+ `page`, and page-number paging (`page` + `per_page`) is named in a warning (that route answers
97
+ every row on one page).
98
+ - **Tools.** An import declares none: routes are never tools. An agent reaches the world's routes
99
+ over HTTP (the api url and token `session open --surface api` prints); declare a tool in
100
+ `x-gateway.tools`, with a handler, where an agent needs one.
73
101
  - **Skipped, with a reason:** `HEAD`/`OPTIONS`/`TRACE`; a path argument that is not an
74
- identifier; a second operation on the same method+path shape. **Refused, with a JSON pointer
102
+ identifier; a path that repeats a placeholder (`/a/{id}/{id}`); a second operation on the same
103
+ method+path shape. **Refused, with a JSON pointer
75
104
  into the document, nothing written:** no `paths`; an unknown or external `$ref`; an entity root
76
105
  that is (transitively) cyclic — model the recursion as a relationship field (`parent_id`)
77
106
  instead; a path parameter nothing declares (`--param <name>` on a hand-written route); a
@@ -85,6 +114,6 @@ With `--plan-only` the same object carries `"written": false` and no `domain`/`n
85
114
 
86
115
  The printed `next` steps are the loop, in order: `schema compile`, `schema check`, `data import
87
116
  <rows.json> --entity <first list entity>` (rows shaped like the vendor's response), `worlds serve`
88
- then `worlds call http://127.0.0.1:<port> <list_route> --args '{}'`, and `sandbox commit` when the
89
- tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
117
+ then `curl -s http://127.0.0.1:<port>/<list path>` (the route over HTTP), and `sandbox commit` when
118
+ the tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
90
119
  served world back against the spec.