@withgateway/sdk 0.2.1 → 0.2.3

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 (44) hide show
  1. package/dist/cli.js +438 -81
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +439 -82
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +9 -5
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +9 -5
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/index.d.mts +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.js +21 -10
  12. package/dist/index.js.map +1 -1
  13. package/dist/index.mjs +20 -10
  14. package/dist/index.mjs.map +1 -1
  15. package/dist/traces/index.js +9 -5
  16. package/dist/traces/index.js.map +1 -1
  17. package/dist/traces/index.mjs +9 -5
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +1 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +1 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +7 -1
  24. package/dist/worlds/index.d.ts +7 -1
  25. package/dist/worlds/index.js +19 -9
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +19 -9
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +1 -1
  30. package/runtime/gatewaysdk/environment/schema/api.py +61 -3
  31. package/runtime/gatewaysdk/environment/schema/batch.py +5 -1
  32. package/runtime/gatewaysdk/environment/schema/connector.py +11 -0
  33. package/runtime/gatewaysdk/environment/schema/data.py +76 -2
  34. package/runtime/gatewaysdk/environment/schema/dependencies.py +11 -1
  35. package/runtime/gatewaysdk/environment/schema/host.py +8 -17
  36. package/runtime/gatewaysdk/environment/schema/local.py +105 -19
  37. package/runtime/gatewaysdk/environment/schema/mapping.py +13 -1
  38. package/runtime/gatewaysdk/environment/schema/platform.py +32 -5
  39. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +4 -1
  40. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +5 -5
  41. package/runtime/gatewaysdk/environment/schema/tools_world.py +5 -1
  42. package/runtime/gatewaysdk/environment/schema/validation.py +4 -3
  43. package/skills/benchmarks-getting-started/SKILL.md +4 -1
  44. package/skills/worlds-getting-started/SKILL.md +5 -5
package/dist/cli.mjs CHANGED
@@ -2236,7 +2236,7 @@ async function push(dir, opts = {}) {
2236
2236
  const pyproject = readPyproject(dir);
2237
2237
  const contractVersion = pyproject.version ? void 0 : readWorldContractVersion(dir).version;
2238
2238
  if (contractVersion) pyproject.version = contractVersion;
2239
- const slug = opts.slug ?? pyproject.name ?? path4.basename(path4.resolve(dir));
2239
+ const slug = opts.slug ?? localMeta.slug ?? pyproject.name ?? path4.basename(path4.resolve(dir));
2240
2240
  const resolve22 = await apiRequest(
2241
2241
  options,
2242
2242
  "POST",
@@ -3150,14 +3150,19 @@ async function importLocalWorldData(dir, rows, opts, creds) {
3150
3150
  files: readWorldFiles(dir),
3151
3151
  rows,
3152
3152
  mode: opts.mode ?? "append",
3153
+ ...opts.merge && opts.merge !== "upsert" ? { merge: opts.merge } : {},
3153
3154
  ...opts.redact && opts.redact !== "off" ? { redact: opts.redact } : {}
3154
3155
  });
3155
3156
  if (res.files?.length) writeWorldFiles(dir, res.files);
3156
- if (res.changed) dropBuildOutputs(dir);
3157
+ const dropped = res.changed ? dropBuildOutputs(dir) : [];
3157
3158
  return {
3158
3159
  kind: res.kind ?? "unknown",
3159
3160
  entity_counts: res.entity_counts ?? {},
3160
- changed: Boolean(res.changed)
3161
+ changed: Boolean(res.changed),
3162
+ ...dropped.length ? {
3163
+ dropped_build_outputs: dropped,
3164
+ next: `gateway worlds schema compile ${dir} # rebuilds the snapshots from the imported data`
3165
+ } : {}
3161
3166
  };
3162
3167
  }
3163
3168
  function dropBuildOutputs(dir) {
@@ -4009,6 +4014,7 @@ var init_ingest = __esm({
4009
4014
  // src/worlds/index.ts
4010
4015
  var worlds_exports = {};
4011
4016
  __export(worlds_exports, {
4017
+ ApiError: () => ApiError2,
4012
4018
  BrowserActionRecorder: () => BrowserActionRecorder,
4013
4019
  COMPUTER_USE_SPECS: () => COMPUTER_USE_SPECS,
4014
4020
  DEFAULT_BRANCH: () => DEFAULT_BRANCH,
@@ -4117,11 +4123,7 @@ async function apiRequest(options, method, path30, body) {
4117
4123
  ...body === void 0 ? {} : { body: JSON.stringify(body) }
4118
4124
  });
4119
4125
  const text2 = await res.text();
4120
- if (!res.ok) {
4121
- throw new Error(
4122
- `${method} ${path30} -> ${res.status}: ${text2.slice(0, 400)}`
4123
- );
4124
- }
4126
+ if (!res.ok) throw new ApiError2(res.status, method, path30, text2.slice(0, 400));
4125
4127
  return JSON.parse(text2);
4126
4128
  }
4127
4129
  async function setEnvSecret(slug, key, value, options = {}) {
@@ -4273,7 +4275,7 @@ async function openWorld(slugRef, options = {}) {
4273
4275
  }
4274
4276
  return world;
4275
4277
  }
4276
- var WorldTask, WorldSet;
4278
+ var ApiError2, WorldTask, WorldSet;
4277
4279
  var init_worlds = __esm({
4278
4280
  "src/worlds/index.ts"() {
4279
4281
  "use strict";
@@ -4288,6 +4290,13 @@ var init_worlds = __esm({
4288
4290
  init_query();
4289
4291
  init_migrate();
4290
4292
  init_ingest();
4293
+ ApiError2 = class extends Error {
4294
+ constructor(status, method, path30, body) {
4295
+ super(`${method} ${path30} -> ${status}: ${body}`);
4296
+ this.status = status;
4297
+ this.name = "ApiError";
4298
+ }
4299
+ };
4291
4300
  WorldTask = class {
4292
4301
  constructor(world, name, variant) {
4293
4302
  this.world = world;
@@ -4932,14 +4941,15 @@ function initNextSteps(dir, shape) {
4932
4941
  );
4933
4942
  if (shape.blank)
4934
4943
  steps.push(
4935
- `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier state_present`,
4936
- `gateway worlds schema compile ${dir}`
4944
+ `gateway worlds schema verifier add ${dir} <verifier> --entity <entity> --where "<sql condition>" # SQL that grades the end state; state_present.sql is the placeholder`,
4945
+ `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier <verifier>`
4937
4946
  );
4938
4947
  steps.push(
4948
+ `gateway worlds schema compile ${dir} # after any edit to schema/, connector.toml or gateway-env.toml`,
4939
4949
  `gateway worlds schema check ${dir}`,
4940
- `gateway worlds data import ${dir} <rows.json>`,
4941
- `gateway worlds serve ${dir}`,
4942
- `gateway worlds create <slug> --from ${dir}`
4950
+ `gateway worlds data import ${dir} <rows.json> # {"<entity>": [row, ...]}`,
4951
+ `gateway worlds serve ${dir} # then: gateway worlds call http://127.0.0.1:<port> <tool> --args '{...}'`,
4952
+ `gateway worlds create <slug> --from ${dir} # publish last`
4943
4953
  );
4944
4954
  return steps;
4945
4955
  }
@@ -5196,7 +5206,7 @@ function registerSchemaCommands(schema) {
5196
5206
  for (const [command2, help] of [
5197
5207
  [
5198
5208
  "compile",
5199
- "Compile the world's contract on the platform and write back what the compiler produced."
5209
+ "Compile the world's contract (the bundled runtime here; the platform's bridge, with a login, when this machine has no python3) and write back what the compiler produced."
5200
5210
  ],
5201
5211
  [
5202
5212
  "check",
@@ -6735,6 +6745,9 @@ function harborRunPlan(dir, taskId, logsDir = LOGS_PLACEHOLDER) {
6735
6745
  validation
6736
6746
  };
6737
6747
  }
6748
+ function notGraded(step, status) {
6749
+ return `the image build failed (${step} exit ${status}); the grader never ran, so there is no reward to read \u2014 fix the image (a registry limit? pull it by hand, or from a mirror, and retry), then dry-run again`;
6750
+ }
6738
6751
  function dockerBin() {
6739
6752
  return process.env.GATEWAY_DOCKER || "docker";
6740
6753
  }
@@ -6766,10 +6779,12 @@ function dryRunHarbor(dir, plan) {
6766
6779
  };
6767
6780
  const image = plan.image.dockerfile ? plan.image.tag : plan.image.ref;
6768
6781
  if (!image) return { executed: false, reason: "the task names no image", commands };
6769
- if (plan.commands.build && spawnArgv(plan.commands.build, 20 * 6e4) !== 0)
6770
- return { executed: true, docker: docker.version, image, exitCode: 1, reward: null, output: outputs.join("\n"), commands, reason: "the image build failed" };
6771
- if (plan.commands.pull && spawnArgv(plan.commands.pull, 20 * 6e4) !== 0)
6772
- return { executed: true, docker: docker.version, image, exitCode: 1, reward: null, output: outputs.join("\n"), commands, reason: "the image pull failed" };
6782
+ const buildStatus = plan.commands.build ? spawnArgv(plan.commands.build, 20 * 6e4) : 0;
6783
+ if (buildStatus !== 0)
6784
+ return { executed: true, docker: docker.version, image, exitCode: buildStatus, output: outputs.join("\n"), commands, reason: notGraded("docker build", buildStatus) };
6785
+ const pullStatus = plan.commands.pull ? spawnArgv(plan.commands.pull, 20 * 6e4) : 0;
6786
+ if (pullStatus !== 0)
6787
+ return { executed: true, docker: docker.version, image, exitCode: pullStatus, output: outputs.join("\n"), commands, reason: notGraded("docker pull", pullStatus) };
6773
6788
  const run = plan.commands.run.map((a) => a.replace(`${LOGS_PLACEHOLDER}:/logs`, `${logs}:/logs`));
6774
6789
  const exitCode = spawnArgv(run, (plan.timeouts.agent + plan.timeouts.verifier) * 1e3);
6775
6790
  const rewards = readReward(path10.join(logs, "verifier"));
@@ -6890,7 +6905,8 @@ function dryRunVerifiers(dir, plan, opts) {
6890
6905
  };
6891
6906
  commands.push(`${shellLine(plan.commands.build)} # Dockerfile on stdin: ${JSON.stringify(plan.image.dockerfile)}`);
6892
6907
  const built = spawnSync2(plan.commands.build[0], plan.commands.build.slice(1), { encoding: "utf8", timeout: 20 * 6e4, input: plan.image.dockerfile });
6893
- if (built.status !== 0) return { executed: true, exitCode: built.status ?? 1, reward: null, reason: "the image build failed", commands, output: tail2((built.stdout ?? "") + (built.stderr ?? "")) };
6908
+ if (built.status !== 0)
6909
+ return { executed: true, exitCode: built.status ?? 1, reason: notGraded("docker build", built.status ?? 1), commands, output: tail2((built.stdout ?? "") + (built.stderr ?? "")) };
6894
6910
  commands.push(shellLine(plan.commands.run));
6895
6911
  const ran = spawnSync2(plan.commands.run[0], plan.commands.run.slice(1), { encoding: "utf8", timeout: 5 * 6e4 });
6896
6912
  return { ...discoverResult(readDiscover(ran.stdout ?? ""), `${plan.image.tag} (Docker ${docker.version})`, ran.stderr ?? "", commands), docker: docker.version, image: plan.image.tag };
@@ -8038,8 +8054,9 @@ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
8038
8054
  if (arg.bool(args, "json")) printJson(ctx, { plan: plan2, result: result2 });
8039
8055
  else printDryRun(ctx, plan2, result2);
8040
8056
  if (invalid) return 2;
8057
+ if (result2.executed && result2.reward === void 0) return 2;
8041
8058
  if (result2.executed && result2.reward !== 1) {
8042
- ctx.stderr(result2.reward === null ? "ungraded: the grader wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8059
+ ctx.stderr(result2.reward === null ? "ungraded: the grader ran but wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8043
8060
  return 2;
8044
8061
  }
8045
8062
  return 0;
@@ -8823,17 +8840,23 @@ async function extractRows(input, config, opts, out) {
8823
8840
  const keys = entity.primaryKey;
8824
8841
  const summary2 = { read: 0, rows: 0, unknownFields: {}, redacted: { dropped: 0, hashed: 0 } };
8825
8842
  const held = /* @__PURE__ */ new Map();
8843
+ const skipped = {};
8844
+ const skip = (reason) => {
8845
+ skipped[reason] = (skipped[reason] ?? 0) + 1;
8846
+ };
8826
8847
  const take = (raw) => {
8827
8848
  summary2.read++;
8828
8849
  const row = clean(raw, entity.fields, summary2);
8829
- if (!keys.every((name) => row.has(name))) return;
8850
+ if (!keys.every((name) => row.has(name))) return skip(`row lacks the primary key (${keys.join(", ")})`);
8830
8851
  const key = dumps(keys.map((name) => row.get(name)));
8831
8852
  const existing = held.get(key);
8832
8853
  if (!existing) held.set(key, row);
8833
8854
  else if (opts.merge === "upsert") held.set(key, row);
8834
8855
  else for (const [name, value] of row) if (!existing.has(name)) existing.set(name, value);
8835
8856
  };
8836
- await adapters[opts.shape](input, config, keys, take);
8857
+ await adapters[opts.shape](input, config, keys, take, skip);
8858
+ if (Object.keys(skipped).length) summary2.skipped = skipped;
8859
+ if (summary2.read === 0 && Object.keys(skipped).length) summary2.hint = SHAPE_HINT[opts.shape];
8837
8860
  const policy = opts.redact ? config.redact : null;
8838
8861
  for (const row of held.values()) {
8839
8862
  let final = row;
@@ -8868,14 +8891,30 @@ function countRedaction(before, after, policy, summary2) {
8868
8891
  else if (policy.hash.includes(name) && value !== null) summary2.redacted.hashed++;
8869
8892
  }
8870
8893
  }
8871
- var toolResults = async (input, _config, keys, take) => {
8894
+ var SHAPE_HINT = {
8895
+ "tool-results": 'tool-results reads JSONL, one {"raw_output": {"results": [row, ...]}} (or "items") per line, rows carrying the primary key; a bare rows file goes to `data import` as it is',
8896
+ "vendor-envelope": "vendor-envelope reads the vendor's own response: a bare array, or an object whose [api].envelope key holds the rows",
8897
+ "session-export": 'session-export reads `gateway worlds session export` JSONL: {"kind": "call", "result": ...} records, rows under result.<[api].envelope>; `data calls pull` + `data ingest` turns other call logs into rows'
8898
+ };
8899
+ var toolResults = async (input, _config, keys, take, skip) => {
8872
8900
  for await (const record of records(input)) {
8873
- if (!isObject(record)) continue;
8901
+ if (!isObject(record)) {
8902
+ skip("line is not a JSON object");
8903
+ continue;
8904
+ }
8874
8905
  const raw = record.get("raw_output");
8875
- if (!isObject(raw)) continue;
8906
+ if (!isObject(raw)) {
8907
+ skip("record has no raw_output object");
8908
+ continue;
8909
+ }
8876
8910
  let listed = raw.get("results");
8877
8911
  if (listed === void 0 || listed === null) listed = raw.get("items");
8878
- for (const item of objects(listed)) if (keys.every((name) => item.has(name))) take(item);
8912
+ const items = objects(listed);
8913
+ if (items.length === 0) skip("raw_output has no results[] or items[]");
8914
+ for (const item of items) {
8915
+ if (keys.every((name) => item.has(name))) take(item);
8916
+ else skip(`row lacks the primary key (${keys.join(", ")})`);
8917
+ }
8879
8918
  }
8880
8919
  };
8881
8920
  var vendorEnvelope = async (input, config, _keys, take) => {
@@ -8914,13 +8953,21 @@ var vendorEnvelope = async (input, config, _keys, take) => {
8914
8953
  }
8915
8954
  for (const row of objects(dig(document, envelope))) take(row);
8916
8955
  };
8917
- var sessionExport = async (input, config, _keys, take) => {
8956
+ var sessionExport = async (input, config, _keys, take, skip) => {
8918
8957
  for await (const record of records(input)) {
8919
- if (!isObject(record) || record.get("kind") !== "call") continue;
8958
+ if (!isObject(record) || record.get("kind") !== "call") {
8959
+ skip('record is not {"kind": "call", ...}');
8960
+ continue;
8961
+ }
8920
8962
  const error = record.get("error");
8921
- if (error !== null && error !== void 0) continue;
8963
+ if (error !== null && error !== void 0) {
8964
+ skip("call record carries an error");
8965
+ continue;
8966
+ }
8922
8967
  const result = record.get("result") ?? null;
8923
- for (const row of objects(config.envelope ? dig(result, config.envelope) : result)) take(row);
8968
+ const rows = objects(config.envelope ? dig(result, config.envelope) : result);
8969
+ if (rows.length === 0) skip(config.envelope ? `result.${config.envelope} holds no rows` : "result is not an array of rows");
8970
+ for (const row of rows) take(row);
8924
8971
  }
8925
8972
  };
8926
8973
  var adapters = {
@@ -9264,6 +9311,13 @@ function skeleton(records2, entities, kind, opts = {}) {
9264
9311
  let select = kind === "tool-call" ? "result" : "$record";
9265
9312
  const shapeNames = Object.keys(group.shapes);
9266
9313
  if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an array of objects")) select = "result[*]";
9314
+ else if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an object")) {
9315
+ const listed = Object.entries(group.fields).filter(([, info]) => info.list && Object.keys(info.nested).length).map(([name2]) => name2);
9316
+ if (listed.length === 1) {
9317
+ select = `result.${listed[0]}[*]`;
9318
+ lines.push(`# result.${listed[0]} holds the rows: [*] selects each item of an array`);
9319
+ }
9320
+ }
9267
9321
  lines.push("[[sources]]", `name = "${name}"`, `kind = "${kind}"`, `select = "${select}"`);
9268
9322
  lines.push(chosen ? `entity = "${chosen}"` : `entity = "" # one of: ${names.join(", ")}`);
9269
9323
  lines.push("[sources.fields]");
@@ -9756,7 +9810,7 @@ var ENTITY_FLAG = { name: "entity", help: "The entity bare-row files hold." };
9756
9810
  var REPORT_FLAG = { name: "report", help: "Write the refusals as JSONL here." };
9757
9811
  var MESSAGE_FLAG = { name: "message", short: "m", help: "Change reason for the version." };
9758
9812
  function registerDataCommands(root) {
9759
- const data = root.group("worlds", "Build, seed, serve and run worlds.").group("data", "Put rows into a world, or see what it holds \u2014 local directory or platform slug");
9813
+ const data = root.group("worlds", "Build, seed, serve and run worlds.").group("data", "Put rows into a world, or see what it holds \u2014 local directory or platform slug. Start a mapping with `data ingest map init`.");
9760
9814
  data.command({
9761
9815
  name: "import",
9762
9816
  help: "Put rows into a world through its own gate.",
@@ -9919,7 +9973,7 @@ primary key, the world's [redact] policy applied. Summary on stderr:
9919
9973
  { name: "session", help: "With --from traces: every trace of this session (GET /api/public/sessions/{id}?includeIO=true)." },
9920
9974
  { name: "since", help: "With --from traces: only calls that started at or after this ISO time." },
9921
9975
  { name: "tool", help: "Keep only calls of this tool; repeat for more.", repeat: true },
9922
- { name: "entity", help: "With --from rows and no map: the entity bare-row files hold. With map init: the entity to fill in." },
9976
+ { name: "entity", help: "With --from rows or --from csv and no map: the entity the bare rows (or CSV columns, header = field names) hold. With map init: the entity to fill in." },
9923
9977
  { name: "out", help: "With map init: where the skeleton goes (default ingest.toml in the world, or stdout for a slug)." },
9924
9978
  { name: "mode", help: "append (upsert by primary key) | replace (named entities).", default: "append" },
9925
9979
  REDACT_FLAG,
@@ -10352,7 +10406,8 @@ async function mapInitCommand(world, samples, args, ctx) {
10352
10406
  }
10353
10407
  if (fs27.existsSync(out) && !arg.bool(args, "dry-run")) throw new CliError(`${out} exists; pass --out for another path, or move it first`, 1);
10354
10408
  fs27.writeFileSync(out, text2);
10355
- ctx.stderr(`wrote ${out}: fill in the entity and fields, then run \`gateway worlds data ingest ${world} ${samples[0]} --map ${out} --dry-run\``);
10409
+ const fromFlag = from === "tool-calls" ? "" : ` --from ${from}`;
10410
+ ctx.stderr(`wrote ${out}: fill in the entity and fields, then run \`gateway worlds data ingest ${world} ${samples[0]}${fromFlag} --map ${out} --dry-run\``);
10356
10411
  return 0;
10357
10412
  }
10358
10413
  async function ingestCommand(world, inputs, args, ctx, labels = {}) {
@@ -10378,7 +10433,12 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10378
10433
  if (local) return dryRun ? checkLocalDirectory(world, inputs, args, ctx, labels) : importLocalDirectory(world, inputs, args, ctx, labels);
10379
10434
  return importBatch(world, inputs, args, ctx, dryRun ? "check" : "import", void 0, labels);
10380
10435
  }
10381
- if (from === "csv" && transform === void 0 && mapFile === void 0 && !(local && worldMapping(world))) throw new CliError("--from csv needs --transform or --map: a CSV says nothing about which entity or fields its columns are");
10436
+ const bareCsv = from === "csv" && transform === void 0 && mapFile === void 0 && !(local && worldMapping(world));
10437
+ const csvEntity = bareCsv ? arg.str(args, "entity") : void 0;
10438
+ if (bareCsv && csvEntity === void 0)
10439
+ throw new CliError(
10440
+ "--from csv needs --entity <entity> (the header row names that entity's fields, every value a string), --transform or --map: a CSV says nothing about which entity its columns fill"
10441
+ );
10382
10442
  const mapText = mapFile !== void 0 ? readMapping(mapFile) : void 0;
10383
10443
  const { toolCallsFromObservations: toolCallsFromObservations2 } = await Promise.resolve().then(() => (init_ingest(), ingest_exports));
10384
10444
  const dir = local ? world : await pullWorld(world, credentials(args));
@@ -10416,7 +10476,23 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10416
10476
  const runtimeCreds = credentialsForRuntime2(arg.str(args, "host"));
10417
10477
  let projected = {};
10418
10478
  try {
10419
- if (transform !== void 0) {
10479
+ if (csvEntity !== void 0) {
10480
+ projected = { [csvEntity]: records2.filter((r) => typeof r === "object" && r !== null) };
10481
+ const landed = local && !dryRun ? await importLocalWorldData2(dir, projected, { mode, redact: redact2 }, runtimeCreds) : await checkLocalWorldData2(dir, projected, runtimeCreds, local ? { redact: redact2 } : {});
10482
+ Object.assign(out, {
10483
+ via: "rows",
10484
+ records: records2.length,
10485
+ ingested: records2.length,
10486
+ skipped: {},
10487
+ refusals: [],
10488
+ rows: { [csvEntity]: projected[csvEntity].length },
10489
+ dryRun,
10490
+ redact: redact2,
10491
+ changed: local && !dryRun ? landed.changed : false,
10492
+ kind: landed.kind,
10493
+ entityCounts: landed.entity_counts
10494
+ });
10495
+ } else if (transform !== void 0) {
10420
10496
  const ran = await runTransform(transform, records2, { timeoutMs: timeoutSeconds * 1e3 });
10421
10497
  for (const line of ran.stderr.split("\n")) if (line.trim()) ctx.stderr(`transform: ${line}`);
10422
10498
  projected = ran.rows;
@@ -10519,10 +10595,11 @@ function worldSlug(dir) {
10519
10595
  const slug = readLocalMeta(dir)?.slug;
10520
10596
  return typeof slug === "string" && slug ? slug : path21.basename(path21.resolve(dir));
10521
10597
  }
10522
- async function inlineRows(dir, files, args, ctx) {
10598
+ async function inlineRows(dir, files, args, ctx, opts = {}) {
10523
10599
  const entity = arg.str(args, "entity");
10524
- const tooLarge = () => new CliError(
10525
- `${files.length} file(s) exceed the inline cap (${INLINE_ROWS} rows / ${INLINE_BYTES} bytes) for a directory; import into the platform world \`${worldSlug(dir)}\``,
10600
+ const capped = opts.cap ?? true;
10601
+ const tooLarge = (what) => new CliError(
10602
+ `${what} across ${files.length} file(s) exceed the inline cap (${INLINE_ROWS} rows / ${INLINE_BYTES} bytes) a directory takes at once; split the rows into smaller files, or import into the platform world \`${worldSlug(dir)}\` (\`gateway worlds data import ${worldSlug(dir)} <rows>\`), which streams them`,
10526
10603
  1
10527
10604
  );
10528
10605
  const paths = [];
@@ -10541,9 +10618,11 @@ async function inlineRows(dir, files, args, ctx) {
10541
10618
  size += fs27.statSync(file).size;
10542
10619
  paths.push(file);
10543
10620
  }
10544
- if (size > INLINE_BYTES) throw tooLarge();
10545
- let count = 0;
10546
- for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge();
10621
+ if (capped) {
10622
+ if (size > INLINE_BYTES) throw tooLarge(`${size} bytes`);
10623
+ let count = 0;
10624
+ for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge(`more than ${INLINE_ROWS} rows`);
10625
+ }
10547
10626
  return parseRows(paths, entity);
10548
10627
  } finally {
10549
10628
  if (scratch) fs27.rmSync(scratch, { recursive: true, force: true });
@@ -10551,16 +10630,39 @@ async function inlineRows(dir, files, args, ctx) {
10551
10630
  }
10552
10631
  async function importLocalDirectory(dir, files, args, ctx, labels = {}) {
10553
10632
  const mode = rowsMode(arg.str(args, "mode"));
10633
+ const merge = arg.str(args, "merge") ?? "upsert";
10634
+ if (merge !== "upsert" && merge !== "fill") throw new CliError("--merge is upsert|fill", 1);
10554
10635
  const redact2 = rowsRedact(arg.str(args, "redact"));
10555
10636
  const rows = await inlineRows(dir, files, args, ctx);
10637
+ const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10556
10638
  const { importLocalWorldData: importLocalWorldData2 } = await runtimeData();
10557
10639
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
10640
+ const { BridgeRejected: BridgeRejected2 } = await Promise.resolve().then(() => (init_client(), client_exports));
10558
10641
  const creds = credentialsForRuntime2(arg.str(args, "host"));
10559
- printJson(ctx, { world: dir, ...inputsField(files, labels), ...await importLocalWorldData2(dir, rows, { mode, redact: redact2 }, creds) });
10560
- return 0;
10642
+ const report = arg.str(args, "report");
10643
+ try {
10644
+ const imported = await importLocalWorldData2(dir, rows, { mode, ...merge === "fill" ? { merge } : {}, redact: redact2 }, creds);
10645
+ if (report !== void 0) fs27.writeFileSync(report, "");
10646
+ printJson(ctx, {
10647
+ world: dir,
10648
+ ...inputsField(files, labels),
10649
+ rows: count,
10650
+ refusalCount: 0,
10651
+ refusals: [],
10652
+ ...imported,
10653
+ ...imported.entity_counts ? { entityCounts: imported.entity_counts } : {}
10654
+ });
10655
+ return 0;
10656
+ } catch (error) {
10657
+ if (!(error instanceof BridgeRejected2)) throw error;
10658
+ const refusals = refusalsFromBridge(error.detail);
10659
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10660
+ printJson(ctx, { world: dir, ...inputsField(files, labels), rows: count, refusalCount: refusals.length, refusals, entityCounts: {}, changed: false });
10661
+ return 2;
10662
+ }
10561
10663
  }
10562
10664
  async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10563
- const rows = await inlineRows(dir, files, args, ctx);
10665
+ const rows = await inlineRows(dir, files, args, ctx, { cap: false });
10564
10666
  const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10565
10667
  const { checkLocalWorldData: checkLocalWorldData2 } = await runtimeData();
10566
10668
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
@@ -10574,14 +10676,19 @@ async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10574
10676
  return 0;
10575
10677
  } catch (error) {
10576
10678
  if (!(error instanceof BridgeRejected2)) throw error;
10577
- const refusal = refusalFromBridge(error.detail);
10578
- if (report !== void 0) fs27.writeFileSync(report, JSON.stringify(refusal) + "\n");
10579
- printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: 1, refusals: [refusal], entityCounts: {} });
10679
+ const refusals = refusalsFromBridge(error.detail);
10680
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10681
+ printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: refusals.length, refusals, entityCounts: {} });
10580
10682
  return 2;
10581
10683
  }
10582
10684
  }
10685
+ function refusalsFromBridge(detail) {
10686
+ if (Array.isArray(detail.refusals) && detail.refusals.length && detail.refusals.every((r) => typeof r === "object" && r !== null))
10687
+ return detail.refusals;
10688
+ return [refusalFromBridge(detail)];
10689
+ }
10583
10690
  function refusalFromBridge(detail) {
10584
- const pointer = detail.path ?? "/";
10691
+ const pointer = detail.path || detail.schema_path || "/";
10585
10692
  const [, entity, index, field] = /^\/([^/]+)(?:\/(\d+))?(?:\/(.+))?$/.exec(pointer) ?? [];
10586
10693
  return {
10587
10694
  chunk: 0,
@@ -11287,6 +11394,14 @@ init_router();
11287
11394
  init_worlds();
11288
11395
  init_shared();
11289
11396
  import * as fs30 from "fs";
11397
+ async function findTaskByName(name, options) {
11398
+ for (let page = 1; ; page++) {
11399
+ const batch = await listTasks({ page, limit: 100 }, options);
11400
+ const hit = batch.tasks.find((task) => task.name === name);
11401
+ if (hit) return hit;
11402
+ if (page >= batch.meta.totalPages) return null;
11403
+ }
11404
+ }
11290
11405
  var WORLD_FLAG = {
11291
11406
  name: "world",
11292
11407
  short: "w",
@@ -11358,20 +11473,42 @@ function registerTaskCommands(root) {
11358
11473
  },
11359
11474
  WORLD_FLAG,
11360
11475
  MESSAGE_FLAG2,
11476
+ {
11477
+ name: "replace",
11478
+ help: "A task by this name already exists: store the spec as its next version instead of refusing (409).",
11479
+ boolean: true
11480
+ },
11361
11481
  HOST_FLAG
11362
11482
  ],
11363
11483
  notes: "The same spec `worlds session open --task-file` takes, kept as a project resource so sessions open on it by id\n(`session open --task-id <id>`) and grades attribute to the task and its version. --world pins it to one world\nand checks the seed and grader entities against that world's contract.",
11364
11484
  run: async (args, ctx) => {
11365
11485
  const spec = readTaskSpec(args.positionals[0], "spec");
11366
- const created = await createTask(
11367
- {
11368
- spec,
11369
- name: arg.str(args, "name"),
11370
- world: arg.str(args, "world"),
11371
- message: arg.str(args, "message")
11372
- },
11373
- worldsOptions(credentials(args))
11374
- );
11486
+ const options = worldsOptions(credentials(args));
11487
+ const input = {
11488
+ spec,
11489
+ name: arg.str(args, "name"),
11490
+ world: arg.str(args, "world"),
11491
+ message: arg.str(args, "message")
11492
+ };
11493
+ let created;
11494
+ try {
11495
+ created = await createTask(input, options);
11496
+ } catch (error) {
11497
+ if (!arg.bool(args, "replace") || !(error instanceof ApiError2) || error.status !== 409) throw error;
11498
+ const name = input.name ?? spec.name;
11499
+ const existing = name ? await findTaskByName(name, options) : null;
11500
+ if (!existing) throw error;
11501
+ created = await updateTask(
11502
+ existing.id,
11503
+ {
11504
+ spec,
11505
+ message: input.message,
11506
+ ...input.world === void 0 ? {} : { world: input.world }
11507
+ },
11508
+ options
11509
+ );
11510
+ ctx.stderr(`task '${name}' exists (${existing.id}); stored the spec as version ${String(created.version)}`);
11511
+ }
11375
11512
  printDeprecations(ctx, created.deprecations);
11376
11513
  printJson(ctx, created);
11377
11514
  }
@@ -12706,10 +12843,10 @@ init_config();
12706
12843
  init_worlds();
12707
12844
  init_session();
12708
12845
  init_hub();
12709
- init_validate();
12710
12846
  import * as fs34 from "fs";
12711
12847
  import * as path25 from "path";
12712
12848
  import { pathToFileURL } from "url";
12849
+ init_validate();
12713
12850
  var HOST_FLAG4 = {
12714
12851
  name: "host",
12715
12852
  help: "Platform host (default: GATEWAY_HOST or the saved login).",
@@ -12935,7 +13072,19 @@ function registerRunCommands2(worlds) {
12935
13072
  }
12936
13073
  return report.ok ? 0 : 1;
12937
13074
  }
12938
- const pushed = await push(dir, { branch, force: true, message, options });
13075
+ const packaged = isConnectorWorld(dir) ? await packageApiBundle(dir, args, ctx) : null;
13076
+ const pushed = await push(packaged ?? dir, {
13077
+ ...packaged ? { slug: meta.slug ?? path25.basename(dir) } : {},
13078
+ branch,
13079
+ force: true,
13080
+ message,
13081
+ options
13082
+ });
13083
+ if (packaged) {
13084
+ const carried = readLocalMeta(packaged);
13085
+ if (carried) writeLocalMeta(dir, carried);
13086
+ fs34.rmSync(packaged, { recursive: true, force: true });
13087
+ }
12939
13088
  ctx.stderr(`pushed ${pushed.slug}@${branch} (${pushed.contentHash.slice(0, 8)})`);
12940
13089
  const agent = await loadAgent(agentFile);
12941
13090
  const world = await openWorld(`${pushed.slug}@${branch}`, options);
@@ -12988,7 +13137,7 @@ function registerServeCommand(worlds) {
12988
13137
  worlds.command({
12989
13138
  name: "serve",
12990
13139
  help: "Serve one session of the world here (bundled runtime + python3): its tools over HTTP, the vendor routes when it has them, its ui on its own port when it declares one; or open a hosted api session when no Python is installed.",
12991
- notes: "With a python3 >= 3.11 on this machine the CLI serves the world here from its bundled runtime\n(the same files the platform runs), on --port, in the foreground, as ONE session with state that\nlasts until you stop it or a client closes it. Every schema world gets the session verbs (loopback,\nno credential), the surface an outside agent acts on:\n GET /__session/task {task, prompt, tools, verifiers, worlds: {alias: [verifiers]}}\n GET /__session/tools the tools it serves (a dependency's as alias.tool)\n POST /__session/call {tool, args} -> {status, body}, as a hosted session answers\n GET /__session/state rows per entity (a dependency's under worlds.<alias>)\n POST /__session/grade {reward, rewards}: the root's verifiers by name, a dependency's as alias/name\n POST /__session/seed {entity: [rows]}; POST /__session/reset back to the start\n POST /__session/close end the session; this command returns\n--task <id> opens the session on one of the world's tasks: its prompt is in the banner and at\n/__session/task, its verifiers grade, and each dependency starts in the scenario its link's `task`\nnames. `gateway worlds call <url> <tool> [--grade] [--close]` acts on the session from another shell.\nA world with a connector.toml serves its vendor routes beside them, and with `[ui]` its page on its own\nport (--ui-port, default the port after --port) at /, the layout the host serves it in, so a frontend\nbuilt for the root works unchanged; the same page is at /__ui/ on --port. The page's api_path calls are\nanswered with the pin; the bare routes still need it. `[dependencies]` entries with\na `path` open beside the root. A --port another process holds is refused by name (its pid when lsof\ncan see it): this serve never answers from another server. The runtime closes when the process that\nstarted it is gone, so a killed CLI leaves no server on the port. Without a python3 it does what `gateway worlds session open <slug>\n--task <scenario> --surface api --no-wait` does: the platform serves the world's vendor API for one\nsession, and the session id + api url are printed. Close it with `gateway worlds session close <id>`.\nGATEWAY_RUNTIME=platform forces the hosted path.",
13140
+ notes: "With a python3 >= 3.11 on this machine the CLI serves the world here from its bundled runtime\n(the same files the platform runs), on --port, in the foreground, as ONE session with state that\nlasts until you stop it or a client closes it. Every schema world gets the session verbs (loopback,\nno credential), the surface an outside agent acts on:\n GET /__session/task {task, prompt, tools, verifiers, worlds: {alias: [verifiers]}}\n GET /__session/tools what it serves: the tools and the connector.toml operations (a dependency's tools as alias.tool)\n POST /__session/call {tool, args} -> {status, body}, as a hosted session answers; an operation by name too\n GET /__session/state rows per entity (a dependency's under worlds.<alias>)\n POST /__session/grade {reward, rewards}: the root's verifiers by name, a dependency's as alias/name\n POST /__session/seed {rows: {entity: [row, ...]}, mode?: append|replace} (a dependency's entity as alias.entity; a\n bare {entity: [row, ...]} is taken as rows); POST /__session/reset back to the start\n POST /__session/close end the session; this command returns\n--task <id> opens the session on one of the world's tasks: its prompt is in the banner and at\n/__session/task, its verifiers grade, and each dependency starts in the scenario its link's `task`\nnames. `gateway worlds call <url> <tool> [--grade] [--close]` acts on the session from another shell.\nA world with a connector.toml serves its vendor routes beside them, and with `[ui]` its page on its own\nport (--ui-port, default the port after --port) at /, the layout the host serves it in, so a frontend\nbuilt for the root works unchanged; the same page is at /__ui/ on --port. The page's api_path calls are\nanswered with the pin; the bare routes still need it. `[dependencies]` entries with\na `path` open beside the root. A --port another process holds is refused by name (its pid when lsof\ncan see it): this serve never answers from another server. The runtime closes when the process that\nstarted it is gone, so a killed CLI leaves no server on the port. Without a python3 it does what `gateway worlds session open <slug>\n--task <scenario> --surface api --no-wait` does: the platform serves the world's vendor API for one\nsession, and the session id + api url are printed. Close it with `gateway worlds session close <id>`.\nGATEWAY_RUNTIME=platform forces the hosted path.",
12992
13141
  positionals: [
12993
13142
  {
12994
13143
  name: "path",
@@ -13047,6 +13196,11 @@ function registerServeCommand(worlds) {
13047
13196
  );
13048
13197
  return localModule(argv, local);
13049
13198
  }
13199
+ if (!local && fs35.existsSync(target) && fs35.statSync(target).isDirectory())
13200
+ ctx.stderr(
13201
+ `# ${localRuntimeReason()}
13202
+ # A local directory is served here only by the bundled Python runtime; without one the CLI can only open a hosted session of a world already published (gateway worlds create <slug> --from ${target}), which needs a login (gateway auth login).`
13203
+ );
13050
13204
  const creds = resolveCredentials(arg.str(args, "host"));
13051
13205
  const options = {
13052
13206
  host: creds.host,
@@ -13065,7 +13219,7 @@ function registerServeCommand(worlds) {
13065
13219
  ctx.stderr(
13066
13220
  "`worlds serve` runs a local session with the Python runtime; opening a hosted api-surface session instead."
13067
13221
  );
13068
- if (!local) ctx.stderr(`# ${localRuntimeReason()}`);
13222
+ if (!local && !(fs35.existsSync(target) && fs35.statSync(target).isDirectory())) ctx.stderr(`# ${localRuntimeReason()}`);
13069
13223
  let scenario = arg.str(args, "scenario") ?? arg.str(args, "task");
13070
13224
  if (!scenario) {
13071
13225
  const world = await openWorld(slugRef, options);
@@ -13280,6 +13434,8 @@ function registerTestCommand(worlds) {
13280
13434
 
13281
13435
  // src/cli/runtime/call.ts
13282
13436
  init_router();
13437
+ init_session();
13438
+ init_shared();
13283
13439
  init_local();
13284
13440
  init_client();
13285
13441
  import * as fs37 from "fs";
@@ -13304,6 +13460,11 @@ function parseArgs2(raw, stdin) {
13304
13460
  return value;
13305
13461
  }
13306
13462
  var SERVED_URL = /^https?:\/\//;
13463
+ function settleStatus(report) {
13464
+ const code = report.result.status;
13465
+ report.status = code >= 200 && code < 300 ? "ok" : code >= 500 ? "error" : "refused";
13466
+ return report;
13467
+ }
13307
13468
  async function sessionVerb(base, verb, body) {
13308
13469
  let response;
13309
13470
  try {
@@ -13323,6 +13484,43 @@ async function sessionVerb(base, verb, body) {
13323
13484
  }
13324
13485
  return { status: response.status, body: parsed };
13325
13486
  }
13487
+ function isRouteAnswer(value) {
13488
+ return typeof value === "object" && value !== null && typeof value.status === "number" && "body" in value;
13489
+ }
13490
+ async function callHosted(sessionId, tool, args, wants, options) {
13491
+ const live = await attachSession(sessionId, options);
13492
+ const report = {
13493
+ status: "ok",
13494
+ tools: (await live.toolkit()).specs.map((spec) => spec.name),
13495
+ result: { status: 0, body: null }
13496
+ };
13497
+ if (wants.seed) {
13498
+ const { rows, mode } = wants.seed;
13499
+ if (!rows || typeof rows !== "object" || Array.isArray(rows))
13500
+ throw new CliError("--seed on a hosted session is the host's shape: {rows: {entity: [row, ...]}, mode?: append|replace}");
13501
+ if (mode !== void 0 && mode !== "append" && mode !== "replace")
13502
+ throw new CliError("--seed mode must be append or replace");
13503
+ const seeded = await live.seed(rows, mode ? { mode } : {});
13504
+ report.seed = seeded;
13505
+ }
13506
+ try {
13507
+ const answer = await live.call(tool, args);
13508
+ report.result = isRouteAnswer(answer) ? answer : { status: 200, body: answer };
13509
+ } catch (error) {
13510
+ if (!(error instanceof WorldSessionCallError)) throw error;
13511
+ report.result = { status: 500, body: { error: error.message } };
13512
+ }
13513
+ if (wants.state) report.state = await live.state();
13514
+ if (wants.grade) report.grade = await live.grade();
13515
+ if (wants.close) {
13516
+ await live.close();
13517
+ report.closed = true;
13518
+ }
13519
+ return settleStatus(report);
13520
+ }
13521
+ function looksLikeSessionId(target) {
13522
+ return !target.includes("/") && !target.startsWith(".") && !fs37.existsSync(target);
13523
+ }
13326
13524
  async function callServed(base, tool, args, wants) {
13327
13525
  const url = base.replace(/\/+$/, "");
13328
13526
  const tools = await sessionVerb(url, "tools");
@@ -13348,16 +13546,16 @@ async function callServed(base, tool, args, wants) {
13348
13546
  if (closed.status !== 200) throw new CliError(`POST /__session/close answered ${closed.status}`, 1);
13349
13547
  report.closed = true;
13350
13548
  }
13351
- return report;
13549
+ return settleStatus(report);
13352
13550
  }
13353
13551
  function registerCallCommand(worlds) {
13354
13552
  worlds.command({
13355
13553
  name: "call",
13356
- help: "Call one tool on a world directory here, or on a served session by URL; a dependency's tool as alias.tool.",
13554
+ help: "Call one tool on a world directory here, on a served session by url, or on a hosted session by id; a dependency's tool as alias.tool.",
13357
13555
  positionals: [
13358
13556
  {
13359
13557
  name: "path",
13360
- help: "World directory (a schema world with gateway-env.toml), or the url of a running `worlds serve` session."
13558
+ help: "World directory (a schema world with gateway-env.toml), the url of a running `worlds serve` session, or the id of a hosted session (`worlds session open`)."
13361
13559
  },
13362
13560
  { name: "tool", help: "Tool name; a dependency's tool as <alias>.<tool>." }
13363
13561
  ],
@@ -13367,13 +13565,14 @@ function registerCallCommand(worlds) {
13367
13565
  { name: "scenario", help: "Start in one of the world's scenarios (default: the base state)." },
13368
13566
  {
13369
13567
  name: "seed",
13370
- help: "Seed rows before the call, the host's shape: JSON {rows: {entity: [row, ...]}, mode?: append|replace}, @file, or -."
13568
+ help: "Seed rows before the call, the host's shape: JSON {rows: {entity: [row, ...]}, mode?: append|replace} (a dependency's entity as alias.entity), @file, or -."
13371
13569
  },
13372
13570
  { name: "state", help: "Print the world's state after the call.", boolean: true },
13373
13571
  { name: "grade", help: "Run the verifiers after the call and print the scores.", boolean: true },
13374
- { name: "close", help: "On a served session (url): end it after the call; `worlds serve` returns.", boolean: true }
13572
+ { name: "close", help: "On a served session (url) or a hosted one (id): end it after the call.", boolean: true },
13573
+ HOST_FLAG
13375
13574
  ],
13376
- notes: 'The world is opened in place, so `[dependencies]` entries with a `path` open beside it and their tools\nanswer as alias.tool; a pin without a path is refused here (add path = "../<dir>"). The world\'s handlers\nrun on this machine through the bundled runtime (a python3 >= 3.11); the platform never runs them for you.\nExit 0 when the tool answered 2xx, 1 otherwise: a refused call (unknown tool, arguments off the schema, a\ntool outside --task\'s allow-list) prints the refusal; a 500 is the handler raising, its error in the body.\nWith a url (the `url` `gateway worlds serve <dir> --task <id>` prints) the call goes to THAT session over\nPOST /__session/call, so state carries from call to call, --state/--grade read it, and --close ends it;\n--task and --scenario belong to the serve. This is the outside-agent path: any HTTP client does the same.\nExamples:\n gateway worlds call ./whatsapp list_conversations\n gateway worlds call ./whatsapp send_message --args \'{"conversation_id": "c1", "body": "hi"}\' --state\n gateway worlds call ./whatsapp slack.post_message --args @msg.json --task escalate --grade\n gateway worlds call http://127.0.0.1:8080 send_message --args \'{"conversation_id": "c1", "body": "hi"}\'\n gateway worlds call http://127.0.0.1:8080 slack.post_message --args @msg.json --grade --close',
13575
+ notes: 'The world is opened in place, so `[dependencies]` entries with a `path` open beside it and their tools\nanswer as alias.tool; a pin without a path is refused here (add path = "../<dir>"). The world\'s handlers\nrun on this machine through the bundled runtime (a python3 >= 3.11); the platform never runs them for you.\nExit 0 when the tool answered 2xx, 1 otherwise: a refused call (unknown tool, arguments off the schema, a\ntool outside --task\'s allow-list) prints the refusal; a 500 is the handler raising, its error in the body.\nWith a url (the `url` `gateway worlds serve <dir> --task <id>` prints) the call goes to THAT session over\nPOST /__session/call, so state carries from call to call, --state/--grade read it, and --close ends it;\n--task and --scenario belong to the serve. This is the outside-agent path: any HTTP client does the same.\nWith a session id (the `sessionId` `gateway worlds session open` prints) the call goes through the platform to\nthat hosted session: the World Host\'s api url takes the session\'s own bearer and serves no /__session verbs, so\nthis is the way to act on a hosted session from the CLI; --seed/--state/--grade/--close work the same.\nExamples:\n gateway worlds call ./whatsapp list_conversations\n gateway worlds call ./whatsapp send_message --args \'{"conversation_id": "c1", "body": "hi"}\' --state\n gateway worlds call ./whatsapp slack.post_message --args @msg.json --task escalate --grade\n gateway worlds call http://127.0.0.1:8080 send_message --args \'{"conversation_id": "c1", "body": "hi"}\'\n gateway worlds call http://127.0.0.1:8080 slack.post_message --args @msg.json --grade --close',
13377
13576
  run: async (args, ctx) => {
13378
13577
  const [target, tool] = args.positionals;
13379
13578
  if (SERVED_URL.test(target)) {
@@ -13391,7 +13590,28 @@ function registerCallCommand(worlds) {
13391
13590
  ctx.stdout(JSON.stringify(report2, null, 2));
13392
13591
  return report2.result.status >= 200 && report2.result.status < 300 ? 0 : 1;
13393
13592
  }
13394
- if (arg.bool(args, "close")) throw new CliError("--close ends a served session; pass its url instead of a directory");
13593
+ if (looksLikeSessionId(target)) {
13594
+ for (const flag of ["task", "scenario"])
13595
+ if (arg.str(args, flag) !== void 0)
13596
+ throw new CliError(`--${flag} belongs to \`gateway worlds session open\`; session ${target} already has its own`);
13597
+ const stdin2 = args.flags.args === "-" || args.flags.seed === "-" ? await ctx.stdin() : "";
13598
+ const seedRaw2 = arg.str(args, "seed");
13599
+ const report2 = await callHosted(
13600
+ target,
13601
+ tool,
13602
+ parseArgs2(arg.str(args, "args"), stdin2),
13603
+ {
13604
+ ...seedRaw2 === void 0 ? {} : { seed: parseArgs2(seedRaw2, stdin2) },
13605
+ state: arg.bool(args, "state"),
13606
+ grade: arg.bool(args, "grade"),
13607
+ close: arg.bool(args, "close")
13608
+ },
13609
+ worldsOptions(credentials(args))
13610
+ );
13611
+ ctx.stdout(JSON.stringify(report2, null, 2));
13612
+ return report2.result.status >= 200 && report2.result.status < 300 ? 0 : 1;
13613
+ }
13614
+ if (arg.bool(args, "close")) throw new CliError("--close ends a served or hosted session; pass its url or id instead of a directory");
13395
13615
  const dir = path28.resolve(target);
13396
13616
  if (!fs37.existsSync(dir) || !fs37.statSync(dir).isDirectory()) throw new CliError(`Not a directory: ${dir}`, 1);
13397
13617
  const local = localRuntime();
@@ -13421,7 +13641,7 @@ function registerCallCommand(worlds) {
13421
13641
  );
13422
13642
  const detail = detailFrom(payload);
13423
13643
  if (detail) throw new BridgeRejected(detail);
13424
- const report = payload;
13644
+ const report = settleStatus(payload);
13425
13645
  ctx.stdout(JSON.stringify(report, null, 2));
13426
13646
  return report.result.status >= 200 && report.result.status < 300 ? 0 : 1;
13427
13647
  }
@@ -13586,6 +13806,38 @@ function declaredOperationNames(toml) {
13586
13806
  }
13587
13807
  return names;
13588
13808
  }
13809
+ function declaredRoutes(toml) {
13810
+ const routes = [];
13811
+ let current = null;
13812
+ for (const raw of toml.split("\n")) {
13813
+ const line = raw.trim();
13814
+ if (line.startsWith("[")) {
13815
+ current = line === "[[operations]]" ? { name: "", methods: [], path: "", params: [] } : null;
13816
+ if (current) routes.push(current);
13817
+ continue;
13818
+ }
13819
+ if (!current) continue;
13820
+ const str2 = (key) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`).exec(line)?.[1];
13821
+ const list = (key) => {
13822
+ const m = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`).exec(line);
13823
+ return m ? [...m[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]) : void 0;
13824
+ };
13825
+ const name = str2("name");
13826
+ if (name !== void 0) current.name = name;
13827
+ const routePath = str2("path");
13828
+ if (routePath !== void 0) current.path = routePath;
13829
+ const method = str2("method");
13830
+ if (method !== void 0 && !current.methods.includes(method.toUpperCase())) current.methods.push(method.toUpperCase());
13831
+ const methods = list("methods");
13832
+ if (methods) {
13833
+ for (const m of methods) if (!current.methods.includes(m.toUpperCase())) current.methods.push(m.toUpperCase());
13834
+ }
13835
+ const params = list("params");
13836
+ if (params) current.params = params;
13837
+ }
13838
+ for (const route of routes) if (!route.methods.length) route.methods.push("GET");
13839
+ return routes;
13840
+ }
13589
13841
  function removeRoute(toml, name) {
13590
13842
  const lines = toml.split("\n");
13591
13843
  const kept = [];
@@ -13647,6 +13899,16 @@ function addRoute(toml, spec, declaredEntities2, options = {}) {
13647
13899
  throw new CliError("--handler only applies with --action handler");
13648
13900
  if (spec.api.status !== void 0 && (spec.api.status < 200 || spec.api.status > 299))
13649
13901
  throw new CliError("--status must be a 2xx");
13902
+ if (spec.api.action !== void 0 && ["create", "update", "delete"].includes(spec.api.action) && spec.method === "GET")
13903
+ throw new CliError(
13904
+ `--action ${spec.api.action} writes, but --method GET reads; pass --method ${spec.api.action === "create" ? "POST" : spec.api.action === "update" ? "PATCH" : "DELETE"}`
13905
+ );
13906
+ const sameParams = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
13907
+ for (const route of declaredRoutes(toml))
13908
+ if (route.name !== spec.name && route.path === spec.path && route.methods.includes(spec.method) && sameParams(route.params, spec.params))
13909
+ throw new CliError(
13910
+ `${spec.method} ${spec.path} is already answered by operation ${route.name} with the same params; a second route there would never be reached \u2014 give it another path, method or --param, or --replace that one`
13911
+ );
13650
13912
  if (spec.entity !== void 0 && declaredEntities2 && !declaredEntities2.includes(spec.entity))
13651
13913
  throw new CliError(
13652
13914
  `Entity ${spec.entity} is not declared in schema/world.json (have: ${declaredEntities2.join(", ") || "none"}); run \`gateway worlds schema entity add\` first`
@@ -13779,18 +14041,43 @@ var assertManifest = (toml) => {
13779
14041
  if (!/^\s*\[(environment|env)\]\s*$/m.test(toml))
13780
14042
  throw new CliError("gateway-env.toml has no [environment] table; it is not a schema world manifest");
13781
14043
  };
13782
- function addDependency(toml, spec, depServes) {
14044
+ function removeDependency(toml, alias) {
14045
+ const kept = [];
14046
+ let dropping = false;
14047
+ for (const raw of toml.split("\n")) {
14048
+ const line = raw.trim();
14049
+ if (line.startsWith("[")) dropping = line === `[dependencies.${alias}]` || line.startsWith(`[dependencies.${alias}.`);
14050
+ if (!dropping) kept.push(raw);
14051
+ }
14052
+ while (kept.length && kept[kept.length - 1].trim() === "") kept.pop();
14053
+ return kept.join("\n") + "\n";
14054
+ }
14055
+ function dependencyServes(depDir) {
14056
+ const manifest = path29.join(depDir, "gateway-env.toml");
14057
+ if (!fs38.existsSync(manifest)) return void 0;
14058
+ const tools = manifestServedTools(fs38.readFileSync(manifest, "utf8"));
14059
+ const connector = path29.join(depDir, "connector.toml");
14060
+ const routes = fs38.existsSync(connector) ? declaredRoutes(fs38.readFileSync(connector, "utf8")).map((r) => r.name).filter(Boolean) : [];
14061
+ return tools === void 0 ? void 0 : { tools, routes };
14062
+ }
14063
+ function addDependency(toml, spec, depServes, opts = {}) {
13783
14064
  assertManifest(toml);
13784
14065
  if (!ALIAS.test(spec.alias))
13785
14066
  throw new CliError(`Aliases match [a-z][a-z0-9_]{0,31}, got ${JSON.stringify(spec.alias)}`);
13786
- if (declaredAliases(toml).includes(spec.alias))
13787
- throw new CliError(`[dependencies.${spec.alias}] is already declared`);
14067
+ if (declaredAliases(toml).includes(spec.alias)) {
14068
+ if (!opts.replace)
14069
+ throw new CliError(`[dependencies.${spec.alias}] is already declared; pass --replace to redeclare it (pin, path, tools, task, map)`);
14070
+ toml = removeDependency(toml, spec.alias);
14071
+ }
13788
14072
  if (!PIN.test(spec.pin)) throw new CliError(`--pin is <slug>@<ref>, got ${JSON.stringify(spec.pin)}`);
13789
14073
  if (path29.isAbsolute(spec.path)) throw new CliError("The dependency path is stored relative to the world");
13790
14074
  if (depServes) {
14075
+ const serves = Array.isArray(depServes) ? { tools: depServes, routes: [] } : depServes;
13791
14076
  for (const tool of spec.tools)
13792
- if (!depServes.includes(tool))
13793
- throw new CliError(`${spec.alias} does not serve ${tool}; it serves: ${depServes.join(", ") || "nothing"}`);
14077
+ if (!serves.tools.includes(tool))
14078
+ throw new CliError(
14079
+ serves.routes.includes(tool) ? `${tool} is a route of ${spec.alias}'s connector.toml (its API surface), not a tool: a dependency's routes answer on its own session over HTTP, not as <alias>.<tool>; its tools are: ${serves.tools.join(", ") || "none (declare one under [tools] serve and tools/*.py)"}` : `${spec.alias} does not serve ${tool}; it serves: ${serves.tools.join(", ") || "nothing"}` + (serves.routes.length ? ` (its routes, ${serves.routes.join(", ")}, are its API surface, not tools)` : "")
14080
+ );
13794
14081
  }
13795
14082
  const body = toml.endsWith("\n") ? toml : toml + "\n";
13796
14083
  return body + "\n" + renderDependency(spec);
@@ -13806,7 +14093,9 @@ function addTask(toml, spec, known = {}) {
13806
14093
  if (known.verifiers) {
13807
14094
  for (const v of spec.verifiers)
13808
14095
  if (!known.verifiers.includes(v))
13809
- throw new CliError(`verifiers/${v}.sql does not exist (have: ${known.verifiers.join(", ") || "none"})`);
14096
+ throw new CliError(
14097
+ `verifiers/${v}.sql does not exist (have: ${known.verifiers.join(", ") || "none"}); scaffold it with \`gateway worlds schema verifier add <path> ${v} --entity <entity>\` \u2014 a verifier is one SQL statement over the world's tables returning one number in 0..1`
14098
+ );
13810
14099
  }
13811
14100
  const aliases = declaredAliases(toml);
13812
14101
  for (const [alias, names] of Object.entries(spec.worlds)) {
@@ -13868,8 +14157,10 @@ function declaredEntities(dir) {
13868
14157
  var WORLD_SLUG = /^[a-z0-9][a-z0-9-]*$/;
13869
14158
  function connectorTomlSkeleton(dir) {
13870
14159
  const manifest = path29.join(dir, "gateway-env.toml");
14160
+ if (!fs38.existsSync(dir))
14161
+ throw new CliError(`${dir} does not exist; run \`gateway worlds schema init ${dir} --connector custom\` to start a world there`, 1);
13871
14162
  if (!fs38.existsSync(manifest))
13872
- throw new CliError(`${dir} holds no connector.toml and no gateway-env.toml; run \`gateway worlds schema init\` first`, 1);
14163
+ throw new CliError(`${dir} holds no connector.toml and no gateway-env.toml (not a world); run \`gateway worlds schema init ${dir} --connector custom\` first`, 1);
13873
14164
  const name = /^\s*name\s*=\s*"([^"]*)"/m.exec(fs38.readFileSync(manifest, "utf8"))?.[1];
13874
14165
  const slug = name && WORLD_SLUG.test(name) ? name : path29.basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "world";
13875
14166
  return [
@@ -13888,6 +14179,26 @@ function scaffoldVerifier(entity) {
13888
14179
  SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
13889
14180
  `;
13890
14181
  }
14182
+ function verifierSql(name, entity, where) {
14183
+ if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(name)) throw new CliError(`Verifier names match [A-Za-z_][A-Za-z0-9_-]*, got ${JSON.stringify(name)}`);
14184
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(entity)) throw new CliError(`Entity names match [A-Za-z_][A-Za-z0-9_]*, got ${JSON.stringify(entity)}`);
14185
+ if (where === void 0) return scaffoldVerifier(entity);
14186
+ const clause = where.trim();
14187
+ if (!clause) throw new CliError("--where is a SQL condition over the entity's columns; it cannot be empty");
14188
+ return `-- ${name}: scores 1.0 once a ${entity} row satisfies the condition; edit for real tasks.
14189
+ -- A verifier is one SQL statement returning one number in 0..1 (0.5 is partial credit).
14190
+ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}" WHERE ${clause};
14191
+ `;
14192
+ }
14193
+ function addVerifier(dir, name, entity, where) {
14194
+ const sql = verifierSql(name, entity, where);
14195
+ const file = path29.join(dir, "verifiers", `${name}.sql`);
14196
+ if (fs38.existsSync(file))
14197
+ throw new CliError(`verifiers/${name}.sql already exists (have: ${(verifierNames2(dir) ?? []).join(", ")}); edit it, or pick another name`);
14198
+ fs38.mkdirSync(path29.dirname(file), { recursive: true });
14199
+ fs38.writeFileSync(file, sql);
14200
+ return file;
14201
+ }
13891
14202
  function repointScaffoldVerifier(dir, entity, declared) {
13892
14203
  const file = path29.join(dir, "verifiers", "state_present.sql");
13893
14204
  if (!fs38.existsSync(file)) return null;
@@ -13931,7 +14242,7 @@ function registerScaffoldCommands(worlds) {
13931
14242
  repeat: true
13932
14243
  }
13933
14244
  ],
13934
- notes: "Exactly one of --ref, --fields or --schema. The file is rewritten with two-space indentation;\nrun `gateway worlds schema check <path>` afterwards for the full contract check.",
14245
+ notes: "Exactly one of --ref, --fields or --schema. The file is rewritten with two-space indentation;\nrun `gateway worlds schema compile <path>` afterwards (the compiled contract is stale until then), then\n`gateway worlds schema check <path>` for the full contract check.",
13935
14246
  run: async (args, ctx) => {
13936
14247
  const dir = path29.resolve(args.positionals[0]);
13937
14248
  const file = path29.join(dir, "schema", "world.json");
@@ -13969,6 +14280,43 @@ function registerScaffoldCommands(worlds) {
13969
14280
  ctx.stdout(JSON.stringify(out, null, 2));
13970
14281
  }
13971
14282
  });
14283
+ schema.group("verifier", "Write verifiers/<name>.sql: the SQL that grades a task on the world's end state.").command({
14284
+ name: "add",
14285
+ help: "Scaffold one verifier: a SQL statement over an entity's table returning 1.0 when a row satisfies --where (or any row exists).",
14286
+ positionals: [
14287
+ { name: "path", help: "World directory holding schema/world.json" },
14288
+ { name: "name", help: "Verifier name, e.g. case_opened; what `schema task add --verifier` takes" }
14289
+ ],
14290
+ flags: [
14291
+ { name: "entity", help: "Entity whose table the verifier counts (from schema/world.json).", short: "e" },
14292
+ { name: "where", help: `SQL condition over the entity's columns, e.g. "status = 'open' AND wallet_id = 'W-1'"; without it any row scores.`, short: "w" }
14293
+ ],
14294
+ notes: "A verifier is one SQL statement returning one number in 0..1 (1.0 passed, 0.0 failed, in between partial\ncredit); each entity is a table named as in the catalog, each field a column. Edit the file freely, then\n`gateway worlds schema task add <path> <task> --verifier <name>` grades a task on it.",
14295
+ run: async (args, ctx) => {
14296
+ const dir = path29.resolve(args.positionals[0]);
14297
+ const name = args.positionals[1];
14298
+ const entity = arg.str(args, "entity");
14299
+ const declared = declaredEntities(dir);
14300
+ if (declared === void 0) throw new CliError(`${dir} has no schema/world.json; run \`gateway worlds schema init ${args.positionals[0]} --connector custom\` first`);
14301
+ if (!entity) throw new CliError(`--entity is required: one of ${declared.join(", ") || "(declare one with `gateway worlds schema entity add` first)"}`);
14302
+ if (!declared.includes(entity)) throw new CliError(`Unknown entity ${entity}; the world has ${declared.join(", ") || "none"}`);
14303
+ const file = addVerifier(dir, name, entity, arg.str(args, "where"));
14304
+ const rel = path29.relative(process.cwd(), dir) || ".";
14305
+ ctx.stdout(
14306
+ JSON.stringify(
14307
+ {
14308
+ status: "ok",
14309
+ verifier: name,
14310
+ entity,
14311
+ file: path29.relative(process.cwd(), file) || file,
14312
+ next: `gateway worlds schema task add ${rel} <task_id> --prompt "<what the agent is told>" --verifier ${name}`
14313
+ },
14314
+ null,
14315
+ 2
14316
+ )
14317
+ );
14318
+ }
14319
+ });
13972
14320
  schema.command({
13973
14321
  name: "link",
13974
14322
  help: "Link another local world as [dependencies.<alias>] in gateway-env.toml: its tools serve as <alias>.<tool>, its verifiers grade as <alias>/<verifier>.",
@@ -13982,7 +14330,12 @@ function registerScaffoldCommands(worlds) {
13982
14330
  ],
13983
14331
  flags: [
13984
14332
  { name: "pin", help: "<slug>@<ref> the platform resolves at push; default <dependency name>@main." },
13985
- { name: "tools", help: "Dependency tools to serve as <alias>.<tool>; comma-separated or repeatable. Default: none.", repeat: true },
14333
+ {
14334
+ name: "tools",
14335
+ help: "Dependency tools (its [tools] serve, not its routes) to serve as <alias>.<tool>; comma-separated or repeatable. Default: every tool it has.",
14336
+ repeat: true
14337
+ },
14338
+ { name: "replace", help: "Redeclare an alias already linked (pin, path, tools, task, map rewritten).", boolean: true },
13986
14339
  { name: "task", help: "Scenario the dependency starts in: scenarios/<name>/ of its tree (the shipped templates have `default`)." },
13987
14340
  {
13988
14341
  name: "map",
@@ -14023,7 +14376,7 @@ function registerScaffoldCommands(worlds) {
14023
14376
  tools: arg.list(args, "tools").flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean),
14024
14377
  entities: arg.list(args, "map").map(parseEntityMap)
14025
14378
  };
14026
- const updated = addDependency(toml, spec, manifestServedTools(depToml));
14379
+ const updated = addDependency(toml, spec, dependencyServes(depDir), { replace: arg.bool(args, "replace") });
14027
14380
  fs38.writeFileSync(file, updated);
14028
14381
  ctx.stdout(
14029
14382
  JSON.stringify(
@@ -14092,7 +14445,11 @@ function registerScaffoldCommands(worlds) {
14092
14445
  worlds: worlds2,
14093
14446
  rewards: [...spec.verifiers, ...Object.entries(worlds2).flatMap(([a, names]) => names.map((n) => `${a}/${n}`))],
14094
14447
  file: path29.relative(process.cwd(), file) || file,
14095
- next: `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14448
+ next: [
14449
+ `gateway worlds schema compile ${path29.relative(process.cwd(), dir) || "."} # a manifest edit invalidates the compiled contract`,
14450
+ `gateway worlds schema check ${path29.relative(process.cwd(), dir) || "."}`,
14451
+ `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14452
+ ]
14096
14453
  },
14097
14454
  null,
14098
14455
  2
@@ -14231,7 +14588,7 @@ function buildCli() {
14231
14588
  "schema",
14232
14589
  "Compile and check gateway-world/1 contracts (the runtime runs on the platform)."
14233
14590
  );
14234
- schema.notes = "Order of work: init \u2192 entity add (or edit schema/world.json) \u2192 tools/handlers.py \u2192 check \u2192 link \u2192 task add.\n`check` names what is missing; `gateway worlds skill connector-schema-authoring` explains the files.";
14591
+ schema.notes = "Order of work: init \u2192 entity add (or edit schema/world.json) \u2192 connector route add (the API surface) \u2192\nverifier add \u2192 task add \u2192 compile (after any edit to schema/, connector.toml or gateway-env.toml) \u2192 check \u2192\ndata import \u2192 serve. `link` joins another world in before compile.\n`check` names what is missing; `gateway worlds skill connector-schema-authoring` explains the files.";
14235
14592
  worlds.group(
14236
14593
  "connector",
14237
14594
  "Vendor connections: validate, capture, conform, ingest, publish, clone."