@withgateway/sdk 0.3.3 → 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 (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -46,7 +46,7 @@ function platformTimeoutMs(env = process.env) {
46
46
  if (Number.isInteger(value) && value > 0) return value;
47
47
  throw new Error(`${PLATFORM_TIMEOUT_ENV} must be a positive whole number of milliseconds, not \`${raw}\`.`);
48
48
  }
49
- var PLATFORM_TIMEOUT_ENV, PLATFORM_TIMEOUT_DEFAULT_MS, CHECK_HOST, RETRY, CAUSES, UNKNOWN_CAUSE, TransportCause, UnreachableError, sleep, RetryPolicy, Attempt, PlatformTransport;
49
+ var PLATFORM_TIMEOUT_ENV, PLATFORM_TIMEOUT_DEFAULT_MS, CHECK_HOST, RETRY, FETCH_LIMIT, CAUSES, UNKNOWN_CAUSE, TransportCause, UnreachableError, sleep, RetryPolicy, Attempt, PlatformTransport;
50
50
  var init_transport = __esm({
51
51
  "src/worlds/transport.ts"() {
52
52
  "use strict";
@@ -54,7 +54,13 @@ var init_transport = __esm({
54
54
  PLATFORM_TIMEOUT_DEFAULT_MS = 12e4;
55
55
  CHECK_HOST = "Check GATEWAY_HOST (or --host) points at a running platform, then retry.";
56
56
  RETRY = "Retry; if it repeats, check the network between here and the platform.";
57
+ FETCH_LIMIT = {
58
+ reason: "Node's fetch stopped waiting after 300 s",
59
+ next: "The platform may still be running it: check what it changed before you retry."
60
+ };
57
61
  CAUSES = {
62
+ UND_ERR_HEADERS_TIMEOUT: FETCH_LIMIT,
63
+ UND_ERR_BODY_TIMEOUT: FETCH_LIMIT,
58
64
  ECONNREFUSED: { reason: "connection refused", next: CHECK_HOST },
59
65
  ENOTFOUND: { reason: "DNS lookup failed", next: CHECK_HOST },
60
66
  EAI_AGAIN: { reason: "DNS lookup failed", next: CHECK_HOST },
@@ -1500,17 +1506,34 @@ var init_nativeComputer = __esm({
1500
1506
  });
1501
1507
 
1502
1508
  // src/worlds/sessionContract.ts
1503
- var CALL_BODY_LIMIT_BYTES, EXPLORATORY_TASK;
1509
+ var CALL_BODY_LIMIT_BYTES, REQUEST_BODY_CAPTURE_BYTES, EXPLORATORY_TASK;
1504
1510
  var init_sessionContract = __esm({
1505
1511
  "src/worlds/sessionContract.ts"() {
1506
1512
  "use strict";
1507
1513
  CALL_BODY_LIMIT_BYTES = 4 * 1024 * 1024;
1514
+ REQUEST_BODY_CAPTURE_BYTES = 64 * 1024;
1508
1515
  EXPLORATORY_TASK = Object.freeze({
1509
1516
  instruction: "exploratory session"
1510
1517
  });
1511
1518
  }
1512
1519
  });
1513
1520
 
1521
+ // src/worlds/toolSchema.ts
1522
+ var init_toolSchema = __esm({
1523
+ "src/worlds/toolSchema.ts"() {
1524
+ "use strict";
1525
+ }
1526
+ });
1527
+
1528
+ // src/worlds/requestLedger.ts
1529
+ var init_requestLedger = __esm({
1530
+ "src/worlds/requestLedger.ts"() {
1531
+ "use strict";
1532
+ init_worlds();
1533
+ init_sessionContract();
1534
+ }
1535
+ });
1536
+
1514
1537
  // src/worlds/sessionReadiness.ts
1515
1538
  var READY_TIMEOUT_MS;
1516
1539
  var init_sessionReadiness = __esm({
@@ -1568,6 +1591,8 @@ var init_session2 = __esm({
1568
1591
  init_browser();
1569
1592
  init_nativeComputer();
1570
1593
  init_sessionContract();
1594
+ init_toolSchema();
1595
+ init_requestLedger();
1571
1596
  init_sessionReadiness();
1572
1597
  init_session();
1573
1598
  init_taskRef();
@@ -1596,6 +1621,14 @@ var init_tasks = __esm({
1596
1621
  }
1597
1622
  });
1598
1623
 
1624
+ // src/worlds/taskGrades.ts
1625
+ var init_taskGrades = __esm({
1626
+ "src/worlds/taskGrades.ts"() {
1627
+ "use strict";
1628
+ init_worlds();
1629
+ }
1630
+ });
1631
+
1599
1632
  // src/worlds/surfaceDescriptor.ts
1600
1633
  var init_surfaceDescriptor = __esm({
1601
1634
  "src/worlds/surfaceDescriptor.ts"() {
@@ -1718,6 +1751,7 @@ var init_setRun = __esm({
1718
1751
  var init_requestLog = __esm({
1719
1752
  "src/worlds/requestLog.ts"() {
1720
1753
  "use strict";
1754
+ init_requestLedger();
1721
1755
  }
1722
1756
  });
1723
1757
 
@@ -1781,10 +1815,14 @@ var init_validate = __esm({
1781
1815
  });
1782
1816
 
1783
1817
  // src/worlds/sandbox.ts
1818
+ import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
1819
+ var SANDBOX_WRITE_CHUNK_BYTES, SANDBOX_FILE_MAX_BYTES;
1784
1820
  var init_sandbox = __esm({
1785
1821
  "src/worlds/sandbox.ts"() {
1786
1822
  "use strict";
1787
1823
  init_worlds();
1824
+ SANDBOX_WRITE_CHUNK_BYTES = 4 * 1024 * 1024;
1825
+ SANDBOX_FILE_MAX_BYTES = 256 * 1024 * 1024;
1788
1826
  }
1789
1827
  });
1790
1828
 
@@ -1805,7 +1843,7 @@ var init_json = __esm({
1805
1843
  });
1806
1844
 
1807
1845
  // src/worlds/transforms.ts
1808
- import { createHash as createHash4 } from "crypto";
1846
+ import { createHash as createHash5 } from "crypto";
1809
1847
  var WHITESPACE, WHITESPACE_EDGES, WHITESPACE_RUN, NOT_DIGIT, STRIP_PREFIX, trim, emailLocalPart, emailDomain, hex, SIMPLE, TRANSFORMS;
1810
1848
  var init_transforms = __esm({
1811
1849
  "src/worlds/transforms.ts"() {
@@ -1825,7 +1863,7 @@ var init_transforms = __esm({
1825
1863
  const at = value.lastIndexOf("@");
1826
1864
  return at === -1 ? "" : value.slice(at + 1).toLowerCase();
1827
1865
  };
1828
- hex = (algorithm, value) => createHash4(algorithm).update(value, "utf8").digest("hex");
1866
+ hex = (algorithm, value) => createHash5(algorithm).update(value, "utf8").digest("hex");
1829
1867
  SIMPLE = {
1830
1868
  lower: (value) => value.toLowerCase(),
1831
1869
  upper: (value) => value.toUpperCase(),
@@ -1845,7 +1883,7 @@ var init_transforms = __esm({
1845
1883
  });
1846
1884
 
1847
1885
  // src/worlds/redaction.ts
1848
- import { createHash as createHash5 } from "crypto";
1886
+ import { createHash as createHash6 } from "crypto";
1849
1887
  var init_redaction = __esm({
1850
1888
  "src/worlds/redaction.ts"() {
1851
1889
  "use strict";
@@ -1899,31 +1937,45 @@ var init_dryRun = __esm({
1899
1937
  });
1900
1938
 
1901
1939
  // src/worlds/index.ts
1902
- function parseErrorBody(text, limit = 600) {
1903
- const raw = { detail: text.slice(0, limit), code: null };
1940
+ function edgeAnswer(text, status) {
1941
+ if (status !== void 0 && status >= 500) return EDGE_ANSWERS[status] ?? EDGE_FAILURE;
1942
+ return /^\s*</.test(text) ? EDGE_PAGE : null;
1943
+ }
1944
+ function parseErrorBody(text, status) {
1945
+ const raw = { detail: text.slice(0, DETAIL_LIMIT), code: null };
1904
1946
  let parsed;
1905
1947
  try {
1906
1948
  parsed = JSON.parse(text);
1907
1949
  } catch {
1908
- return raw;
1950
+ return { detail: (edgeAnswer(text, status) ?? text).slice(0, DETAIL_LIMIT), code: null };
1909
1951
  }
1910
1952
  if (parsed === null || typeof parsed !== "object") return raw;
1911
- const { message, code } = parsed;
1953
+ const { message, code, error } = parsed;
1912
1954
  const stableCode = typeof code === "string" ? code : null;
1913
1955
  if (typeof message !== "string") return { ...raw, code: stableCode };
1914
- if (stableCode === null)
1915
- return { detail: message.slice(0, limit), code: null };
1956
+ const fields = invalidFields(error);
1957
+ const said = fields ? `${message}: ${fields}` : message;
1958
+ if (stableCode === null) return { detail: said.slice(0, DETAIL_LIMIT), code: null };
1916
1959
  return {
1917
- detail: `${message} (${stableCode})`.slice(0, limit),
1960
+ detail: `${said} (${stableCode})`.slice(0, DETAIL_LIMIT),
1918
1961
  code: stableCode
1919
1962
  };
1920
1963
  }
1964
+ function invalidFields(error) {
1965
+ const issues = Array.isArray(error) ? error : [];
1966
+ return issues.filter(
1967
+ (issue) => issue !== null && typeof issue === "object" && typeof issue.message === "string"
1968
+ ).map((issue) => {
1969
+ const path8 = Array.isArray(issue.path) ? issue.path.map(String).join(".") : "";
1970
+ return path8 ? `${path8}: ${issue.message}` : issue.message;
1971
+ }).join("; ");
1972
+ }
1921
1973
  async function apiRequest(options, method, path8, body, init = {}) {
1922
1974
  const reply = await new PlatformTransport(requirePlatformEndpoint(options)).send(method, path8, body, init);
1923
1975
  if (!reply.ok) throw new ApiError(reply.status, method, path8, reply.text);
1924
1976
  return JSON.parse(reply.text);
1925
1977
  }
1926
- var ApiError;
1978
+ var ApiError, DETAIL_LIMIT, EDGE_ANSWERS, EDGE_FAILURE, EDGE_PAGE;
1927
1979
  var init_worlds = __esm({
1928
1980
  "src/worlds/index.ts"() {
1929
1981
  "use strict";
@@ -1936,6 +1988,7 @@ var init_worlds = __esm({
1936
1988
  init_sessionContract();
1937
1989
  init_taskRef();
1938
1990
  init_tasks();
1991
+ init_taskGrades();
1939
1992
  init_taskSessions();
1940
1993
  init_taskRun();
1941
1994
  init_setRun();
@@ -1944,6 +1997,7 @@ var init_worlds = __esm({
1944
1997
  init_browser();
1945
1998
  init_surfaceDescriptor();
1946
1999
  init_requestLog();
2000
+ init_requestLedger();
1947
2001
  init_browserReconnect();
1948
2002
  init_nativeComputer();
1949
2003
  init_hub();
@@ -1960,7 +2014,7 @@ var init_worlds = __esm({
1960
2014
  init_worldNotice();
1961
2015
  ApiError = class extends Error {
1962
2016
  constructor(status, method, path8, text) {
1963
- const parsed = parseErrorBody(text);
2017
+ const parsed = parseErrorBody(text, status);
1964
2018
  super(`${method} ${path8} -> ${status}: ${parsed.detail}`);
1965
2019
  this.status = status;
1966
2020
  this.text = text;
@@ -1971,6 +2025,14 @@ var init_worlds = __esm({
1971
2025
  text;
1972
2026
  code;
1973
2027
  };
2028
+ DETAIL_LIMIT = 600;
2029
+ EDGE_ANSWERS = {
2030
+ 502: "Bad Gateway from the load balancer in front of the platform, not the platform's answer: the web server dropped the connection or restarted mid-request. Retry; if it repeats, the platform is restarting or overloaded.",
2031
+ 503: "Service Unavailable from the load balancer in front of the platform, not the platform's answer: no web server was ready to take the request (a deploy or a restart). Retry in a minute.",
2032
+ 504: "Gateway Time-out from the load balancer in front of the platform, not the platform's answer: the request sent nothing back within the load balancer's idle timeout (60 s unless the deployment raises it: Helm ingress.idleTimeoutSeconds) and was cut there, though the platform may still be running it. Check what it changed before you retry."
2033
+ };
2034
+ EDGE_FAILURE = "The platform failed without its JSON error body: a proxy in front of it answered, or the server stopped before its error handler ran. Retry; if it repeats, report the request and the time.";
2035
+ EDGE_PAGE = "An HTML page answered instead of the platform's JSON: a proxy in front of the platform, or the configured host is not the platform.";
1974
2036
  }
1975
2037
  });
1976
2038