@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.js CHANGED
@@ -2245,7 +2245,7 @@ async function push(dir, opts = {}) {
2245
2245
  const pyproject = readPyproject(dir);
2246
2246
  const contractVersion = pyproject.version ? void 0 : readWorldContractVersion(dir).version;
2247
2247
  if (contractVersion) pyproject.version = contractVersion;
2248
- const slug = opts.slug ?? pyproject.name ?? path4.basename(path4.resolve(dir));
2248
+ const slug = opts.slug ?? localMeta.slug ?? pyproject.name ?? path4.basename(path4.resolve(dir));
2249
2249
  const resolve22 = await apiRequest(
2250
2250
  options,
2251
2251
  "POST",
@@ -3161,14 +3161,19 @@ async function importLocalWorldData(dir, rows, opts, creds) {
3161
3161
  files: readWorldFiles(dir),
3162
3162
  rows,
3163
3163
  mode: opts.mode ?? "append",
3164
+ ...opts.merge && opts.merge !== "upsert" ? { merge: opts.merge } : {},
3164
3165
  ...opts.redact && opts.redact !== "off" ? { redact: opts.redact } : {}
3165
3166
  });
3166
3167
  if (res.files?.length) writeWorldFiles(dir, res.files);
3167
- if (res.changed) dropBuildOutputs(dir);
3168
+ const dropped = res.changed ? dropBuildOutputs(dir) : [];
3168
3169
  return {
3169
3170
  kind: res.kind ?? "unknown",
3170
3171
  entity_counts: res.entity_counts ?? {},
3171
- changed: Boolean(res.changed)
3172
+ changed: Boolean(res.changed),
3173
+ ...dropped.length ? {
3174
+ dropped_build_outputs: dropped,
3175
+ next: `gateway worlds schema compile ${dir} # rebuilds the snapshots from the imported data`
3176
+ } : {}
3172
3177
  };
3173
3178
  }
3174
3179
  function dropBuildOutputs(dir) {
@@ -4023,6 +4028,7 @@ var init_ingest = __esm({
4023
4028
  // src/worlds/index.ts
4024
4029
  var worlds_exports = {};
4025
4030
  __export(worlds_exports, {
4031
+ ApiError: () => ApiError2,
4026
4032
  BrowserActionRecorder: () => BrowserActionRecorder,
4027
4033
  COMPUTER_USE_SPECS: () => COMPUTER_USE_SPECS,
4028
4034
  DEFAULT_BRANCH: () => DEFAULT_BRANCH,
@@ -4131,11 +4137,7 @@ async function apiRequest(options, method, path30, body) {
4131
4137
  ...body === void 0 ? {} : { body: JSON.stringify(body) }
4132
4138
  });
4133
4139
  const text2 = await res.text();
4134
- if (!res.ok) {
4135
- throw new Error(
4136
- `${method} ${path30} -> ${res.status}: ${text2.slice(0, 400)}`
4137
- );
4138
- }
4140
+ if (!res.ok) throw new ApiError2(res.status, method, path30, text2.slice(0, 400));
4139
4141
  return JSON.parse(text2);
4140
4142
  }
4141
4143
  async function setEnvSecret(slug, key, value, options = {}) {
@@ -4287,7 +4289,7 @@ async function openWorld(slugRef, options = {}) {
4287
4289
  }
4288
4290
  return world;
4289
4291
  }
4290
- var WorldTask, WorldSet;
4292
+ var ApiError2, WorldTask, WorldSet;
4291
4293
  var init_worlds = __esm({
4292
4294
  "src/worlds/index.ts"() {
4293
4295
  "use strict";
@@ -4302,6 +4304,13 @@ var init_worlds = __esm({
4302
4304
  init_query();
4303
4305
  init_migrate();
4304
4306
  init_ingest();
4307
+ ApiError2 = class extends Error {
4308
+ constructor(status, method, path30, body) {
4309
+ super(`${method} ${path30} -> ${status}: ${body}`);
4310
+ this.status = status;
4311
+ this.name = "ApiError";
4312
+ }
4313
+ };
4305
4314
  WorldTask = class {
4306
4315
  constructor(world, name, variant) {
4307
4316
  this.world = world;
@@ -4944,14 +4953,15 @@ function initNextSteps(dir, shape) {
4944
4953
  );
4945
4954
  if (shape.blank)
4946
4955
  steps.push(
4947
- `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier state_present`,
4948
- `gateway worlds schema compile ${dir}`
4956
+ `gateway worlds schema verifier add ${dir} <verifier> --entity <entity> --where "<sql condition>" # SQL that grades the end state; state_present.sql is the placeholder`,
4957
+ `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier <verifier>`
4949
4958
  );
4950
4959
  steps.push(
4960
+ `gateway worlds schema compile ${dir} # after any edit to schema/, connector.toml or gateway-env.toml`,
4951
4961
  `gateway worlds schema check ${dir}`,
4952
- `gateway worlds data import ${dir} <rows.json>`,
4953
- `gateway worlds serve ${dir}`,
4954
- `gateway worlds create <slug> --from ${dir}`
4962
+ `gateway worlds data import ${dir} <rows.json> # {"<entity>": [row, ...]}`,
4963
+ `gateway worlds serve ${dir} # then: gateway worlds call http://127.0.0.1:<port> <tool> --args '{...}'`,
4964
+ `gateway worlds create <slug> --from ${dir} # publish last`
4955
4965
  );
4956
4966
  return steps;
4957
4967
  }
@@ -5208,7 +5218,7 @@ function registerSchemaCommands(schema) {
5208
5218
  for (const [command2, help] of [
5209
5219
  [
5210
5220
  "compile",
5211
- "Compile the world's contract on the platform and write back what the compiler produced."
5221
+ "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."
5212
5222
  ],
5213
5223
  [
5214
5224
  "check",
@@ -6749,6 +6759,9 @@ function harborRunPlan(dir, taskId, logsDir = LOGS_PLACEHOLDER) {
6749
6759
  validation
6750
6760
  };
6751
6761
  }
6762
+ function notGraded(step, status) {
6763
+ 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`;
6764
+ }
6752
6765
  function dockerBin() {
6753
6766
  return process.env.GATEWAY_DOCKER || "docker";
6754
6767
  }
@@ -6780,10 +6793,12 @@ function dryRunHarbor(dir, plan) {
6780
6793
  };
6781
6794
  const image = plan.image.dockerfile ? plan.image.tag : plan.image.ref;
6782
6795
  if (!image) return { executed: false, reason: "the task names no image", commands };
6783
- if (plan.commands.build && spawnArgv(plan.commands.build, 20 * 6e4) !== 0)
6784
- return { executed: true, docker: docker.version, image, exitCode: 1, reward: null, output: outputs.join("\n"), commands, reason: "the image build failed" };
6785
- if (plan.commands.pull && spawnArgv(plan.commands.pull, 20 * 6e4) !== 0)
6786
- return { executed: true, docker: docker.version, image, exitCode: 1, reward: null, output: outputs.join("\n"), commands, reason: "the image pull failed" };
6796
+ const buildStatus = plan.commands.build ? spawnArgv(plan.commands.build, 20 * 6e4) : 0;
6797
+ if (buildStatus !== 0)
6798
+ return { executed: true, docker: docker.version, image, exitCode: buildStatus, output: outputs.join("\n"), commands, reason: notGraded("docker build", buildStatus) };
6799
+ const pullStatus = plan.commands.pull ? spawnArgv(plan.commands.pull, 20 * 6e4) : 0;
6800
+ if (pullStatus !== 0)
6801
+ return { executed: true, docker: docker.version, image, exitCode: pullStatus, output: outputs.join("\n"), commands, reason: notGraded("docker pull", pullStatus) };
6787
6802
  const run = plan.commands.run.map((a) => a.replace(`${LOGS_PLACEHOLDER}:/logs`, `${logs}:/logs`));
6788
6803
  const exitCode = spawnArgv(run, (plan.timeouts.agent + plan.timeouts.verifier) * 1e3);
6789
6804
  const rewards = readReward(path10.join(logs, "verifier"));
@@ -6904,7 +6919,8 @@ function dryRunVerifiers(dir, plan, opts) {
6904
6919
  };
6905
6920
  commands.push(`${shellLine(plan.commands.build)} # Dockerfile on stdin: ${JSON.stringify(plan.image.dockerfile)}`);
6906
6921
  const built = (0, import_node_child_process3.spawnSync)(plan.commands.build[0], plan.commands.build.slice(1), { encoding: "utf8", timeout: 20 * 6e4, input: plan.image.dockerfile });
6907
- 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 ?? "")) };
6922
+ if (built.status !== 0)
6923
+ return { executed: true, exitCode: built.status ?? 1, reason: notGraded("docker build", built.status ?? 1), commands, output: tail2((built.stdout ?? "") + (built.stderr ?? "")) };
6908
6924
  commands.push(shellLine(plan.commands.run));
6909
6925
  const ran = (0, import_node_child_process3.spawnSync)(plan.commands.run[0], plan.commands.run.slice(1), { encoding: "utf8", timeout: 5 * 6e4 });
6910
6926
  return { ...discoverResult(readDiscover(ran.stdout ?? ""), `${plan.image.tag} (Docker ${docker.version})`, ran.stderr ?? "", commands), docker: docker.version, image: plan.image.tag };
@@ -8052,8 +8068,9 @@ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
8052
8068
  if (arg.bool(args, "json")) printJson(ctx, { plan: plan2, result: result2 });
8053
8069
  else printDryRun(ctx, plan2, result2);
8054
8070
  if (invalid) return 2;
8071
+ if (result2.executed && result2.reward === void 0) return 2;
8055
8072
  if (result2.executed && result2.reward !== 1) {
8056
- ctx.stderr(result2.reward === null ? "ungraded: the grader wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8073
+ ctx.stderr(result2.reward === null ? "ungraded: the grader ran but wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8057
8074
  return 2;
8058
8075
  }
8059
8076
  return 0;
@@ -8837,17 +8854,23 @@ async function extractRows(input, config, opts, out) {
8837
8854
  const keys = entity.primaryKey;
8838
8855
  const summary2 = { read: 0, rows: 0, unknownFields: {}, redacted: { dropped: 0, hashed: 0 } };
8839
8856
  const held = /* @__PURE__ */ new Map();
8857
+ const skipped = {};
8858
+ const skip = (reason) => {
8859
+ skipped[reason] = (skipped[reason] ?? 0) + 1;
8860
+ };
8840
8861
  const take = (raw) => {
8841
8862
  summary2.read++;
8842
8863
  const row = clean(raw, entity.fields, summary2);
8843
- if (!keys.every((name) => row.has(name))) return;
8864
+ if (!keys.every((name) => row.has(name))) return skip(`row lacks the primary key (${keys.join(", ")})`);
8844
8865
  const key = dumps(keys.map((name) => row.get(name)));
8845
8866
  const existing = held.get(key);
8846
8867
  if (!existing) held.set(key, row);
8847
8868
  else if (opts.merge === "upsert") held.set(key, row);
8848
8869
  else for (const [name, value] of row) if (!existing.has(name)) existing.set(name, value);
8849
8870
  };
8850
- await adapters[opts.shape](input, config, keys, take);
8871
+ await adapters[opts.shape](input, config, keys, take, skip);
8872
+ if (Object.keys(skipped).length) summary2.skipped = skipped;
8873
+ if (summary2.read === 0 && Object.keys(skipped).length) summary2.hint = SHAPE_HINT[opts.shape];
8851
8874
  const policy = opts.redact ? config.redact : null;
8852
8875
  for (const row of held.values()) {
8853
8876
  let final = row;
@@ -8882,14 +8905,30 @@ function countRedaction(before, after, policy, summary2) {
8882
8905
  else if (policy.hash.includes(name) && value !== null) summary2.redacted.hashed++;
8883
8906
  }
8884
8907
  }
8885
- var toolResults = async (input, _config, keys, take) => {
8908
+ var SHAPE_HINT = {
8909
+ "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',
8910
+ "vendor-envelope": "vendor-envelope reads the vendor's own response: a bare array, or an object whose [api].envelope key holds the rows",
8911
+ "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'
8912
+ };
8913
+ var toolResults = async (input, _config, keys, take, skip) => {
8886
8914
  for await (const record of records(input)) {
8887
- if (!isObject(record)) continue;
8915
+ if (!isObject(record)) {
8916
+ skip("line is not a JSON object");
8917
+ continue;
8918
+ }
8888
8919
  const raw = record.get("raw_output");
8889
- if (!isObject(raw)) continue;
8920
+ if (!isObject(raw)) {
8921
+ skip("record has no raw_output object");
8922
+ continue;
8923
+ }
8890
8924
  let listed = raw.get("results");
8891
8925
  if (listed === void 0 || listed === null) listed = raw.get("items");
8892
- for (const item of objects(listed)) if (keys.every((name) => item.has(name))) take(item);
8926
+ const items = objects(listed);
8927
+ if (items.length === 0) skip("raw_output has no results[] or items[]");
8928
+ for (const item of items) {
8929
+ if (keys.every((name) => item.has(name))) take(item);
8930
+ else skip(`row lacks the primary key (${keys.join(", ")})`);
8931
+ }
8893
8932
  }
8894
8933
  };
8895
8934
  var vendorEnvelope = async (input, config, _keys, take) => {
@@ -8928,13 +8967,21 @@ var vendorEnvelope = async (input, config, _keys, take) => {
8928
8967
  }
8929
8968
  for (const row of objects(dig(document, envelope))) take(row);
8930
8969
  };
8931
- var sessionExport = async (input, config, _keys, take) => {
8970
+ var sessionExport = async (input, config, _keys, take, skip) => {
8932
8971
  for await (const record of records(input)) {
8933
- if (!isObject(record) || record.get("kind") !== "call") continue;
8972
+ if (!isObject(record) || record.get("kind") !== "call") {
8973
+ skip('record is not {"kind": "call", ...}');
8974
+ continue;
8975
+ }
8934
8976
  const error = record.get("error");
8935
- if (error !== null && error !== void 0) continue;
8977
+ if (error !== null && error !== void 0) {
8978
+ skip("call record carries an error");
8979
+ continue;
8980
+ }
8936
8981
  const result = record.get("result") ?? null;
8937
- for (const row of objects(config.envelope ? dig(result, config.envelope) : result)) take(row);
8982
+ const rows = objects(config.envelope ? dig(result, config.envelope) : result);
8983
+ if (rows.length === 0) skip(config.envelope ? `result.${config.envelope} holds no rows` : "result is not an array of rows");
8984
+ for (const row of rows) take(row);
8938
8985
  }
8939
8986
  };
8940
8987
  var adapters = {
@@ -9278,6 +9325,13 @@ function skeleton(records2, entities, kind, opts = {}) {
9278
9325
  let select = kind === "tool-call" ? "result" : "$record";
9279
9326
  const shapeNames = Object.keys(group.shapes);
9280
9327
  if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an array of objects")) select = "result[*]";
9328
+ else if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an object")) {
9329
+ const listed = Object.entries(group.fields).filter(([, info]) => info.list && Object.keys(info.nested).length).map(([name2]) => name2);
9330
+ if (listed.length === 1) {
9331
+ select = `result.${listed[0]}[*]`;
9332
+ lines.push(`# result.${listed[0]} holds the rows: [*] selects each item of an array`);
9333
+ }
9334
+ }
9281
9335
  lines.push("[[sources]]", `name = "${name}"`, `kind = "${kind}"`, `select = "${select}"`);
9282
9336
  lines.push(chosen ? `entity = "${chosen}"` : `entity = "" # one of: ${names.join(", ")}`);
9283
9337
  lines.push("[sources.fields]");
@@ -9770,7 +9824,7 @@ var ENTITY_FLAG = { name: "entity", help: "The entity bare-row files hold." };
9770
9824
  var REPORT_FLAG = { name: "report", help: "Write the refusals as JSONL here." };
9771
9825
  var MESSAGE_FLAG = { name: "message", short: "m", help: "Change reason for the version." };
9772
9826
  function registerDataCommands(root) {
9773
- 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");
9827
+ 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`.");
9774
9828
  data.command({
9775
9829
  name: "import",
9776
9830
  help: "Put rows into a world through its own gate.",
@@ -9933,7 +9987,7 @@ primary key, the world's [redact] policy applied. Summary on stderr:
9933
9987
  { name: "session", help: "With --from traces: every trace of this session (GET /api/public/sessions/{id}?includeIO=true)." },
9934
9988
  { name: "since", help: "With --from traces: only calls that started at or after this ISO time." },
9935
9989
  { name: "tool", help: "Keep only calls of this tool; repeat for more.", repeat: true },
9936
- { name: "entity", help: "With --from rows and no map: the entity bare-row files hold. With map init: the entity to fill in." },
9990
+ { 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." },
9937
9991
  { name: "out", help: "With map init: where the skeleton goes (default ingest.toml in the world, or stdout for a slug)." },
9938
9992
  { name: "mode", help: "append (upsert by primary key) | replace (named entities).", default: "append" },
9939
9993
  REDACT_FLAG,
@@ -10366,7 +10420,8 @@ async function mapInitCommand(world, samples, args, ctx) {
10366
10420
  }
10367
10421
  if (fs27.existsSync(out) && !arg.bool(args, "dry-run")) throw new CliError(`${out} exists; pass --out for another path, or move it first`, 1);
10368
10422
  fs27.writeFileSync(out, text2);
10369
- ctx.stderr(`wrote ${out}: fill in the entity and fields, then run \`gateway worlds data ingest ${world} ${samples[0]} --map ${out} --dry-run\``);
10423
+ const fromFlag = from === "tool-calls" ? "" : ` --from ${from}`;
10424
+ ctx.stderr(`wrote ${out}: fill in the entity and fields, then run \`gateway worlds data ingest ${world} ${samples[0]}${fromFlag} --map ${out} --dry-run\``);
10370
10425
  return 0;
10371
10426
  }
10372
10427
  async function ingestCommand(world, inputs, args, ctx, labels = {}) {
@@ -10392,7 +10447,12 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10392
10447
  if (local) return dryRun ? checkLocalDirectory(world, inputs, args, ctx, labels) : importLocalDirectory(world, inputs, args, ctx, labels);
10393
10448
  return importBatch(world, inputs, args, ctx, dryRun ? "check" : "import", void 0, labels);
10394
10449
  }
10395
- 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");
10450
+ const bareCsv = from === "csv" && transform === void 0 && mapFile === void 0 && !(local && worldMapping(world));
10451
+ const csvEntity = bareCsv ? arg.str(args, "entity") : void 0;
10452
+ if (bareCsv && csvEntity === void 0)
10453
+ throw new CliError(
10454
+ "--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"
10455
+ );
10396
10456
  const mapText = mapFile !== void 0 ? readMapping(mapFile) : void 0;
10397
10457
  const { toolCallsFromObservations: toolCallsFromObservations2 } = await Promise.resolve().then(() => (init_ingest(), ingest_exports));
10398
10458
  const dir = local ? world : await pullWorld(world, credentials(args));
@@ -10430,7 +10490,23 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10430
10490
  const runtimeCreds = credentialsForRuntime2(arg.str(args, "host"));
10431
10491
  let projected = {};
10432
10492
  try {
10433
- if (transform !== void 0) {
10493
+ if (csvEntity !== void 0) {
10494
+ projected = { [csvEntity]: records2.filter((r) => typeof r === "object" && r !== null) };
10495
+ const landed = local && !dryRun ? await importLocalWorldData2(dir, projected, { mode, redact: redact2 }, runtimeCreds) : await checkLocalWorldData2(dir, projected, runtimeCreds, local ? { redact: redact2 } : {});
10496
+ Object.assign(out, {
10497
+ via: "rows",
10498
+ records: records2.length,
10499
+ ingested: records2.length,
10500
+ skipped: {},
10501
+ refusals: [],
10502
+ rows: { [csvEntity]: projected[csvEntity].length },
10503
+ dryRun,
10504
+ redact: redact2,
10505
+ changed: local && !dryRun ? landed.changed : false,
10506
+ kind: landed.kind,
10507
+ entityCounts: landed.entity_counts
10508
+ });
10509
+ } else if (transform !== void 0) {
10434
10510
  const ran = await runTransform(transform, records2, { timeoutMs: timeoutSeconds * 1e3 });
10435
10511
  for (const line of ran.stderr.split("\n")) if (line.trim()) ctx.stderr(`transform: ${line}`);
10436
10512
  projected = ran.rows;
@@ -10533,10 +10609,11 @@ function worldSlug(dir) {
10533
10609
  const slug = readLocalMeta(dir)?.slug;
10534
10610
  return typeof slug === "string" && slug ? slug : path21.basename(path21.resolve(dir));
10535
10611
  }
10536
- async function inlineRows(dir, files, args, ctx) {
10612
+ async function inlineRows(dir, files, args, ctx, opts = {}) {
10537
10613
  const entity = arg.str(args, "entity");
10538
- const tooLarge = () => new CliError(
10539
- `${files.length} file(s) exceed the inline cap (${INLINE_ROWS} rows / ${INLINE_BYTES} bytes) for a directory; import into the platform world \`${worldSlug(dir)}\``,
10614
+ const capped = opts.cap ?? true;
10615
+ const tooLarge = (what) => new CliError(
10616
+ `${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`,
10540
10617
  1
10541
10618
  );
10542
10619
  const paths = [];
@@ -10555,9 +10632,11 @@ async function inlineRows(dir, files, args, ctx) {
10555
10632
  size += fs27.statSync(file).size;
10556
10633
  paths.push(file);
10557
10634
  }
10558
- if (size > INLINE_BYTES) throw tooLarge();
10559
- let count = 0;
10560
- for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge();
10635
+ if (capped) {
10636
+ if (size > INLINE_BYTES) throw tooLarge(`${size} bytes`);
10637
+ let count = 0;
10638
+ for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge(`more than ${INLINE_ROWS} rows`);
10639
+ }
10561
10640
  return parseRows(paths, entity);
10562
10641
  } finally {
10563
10642
  if (scratch) fs27.rmSync(scratch, { recursive: true, force: true });
@@ -10565,16 +10644,39 @@ async function inlineRows(dir, files, args, ctx) {
10565
10644
  }
10566
10645
  async function importLocalDirectory(dir, files, args, ctx, labels = {}) {
10567
10646
  const mode = rowsMode(arg.str(args, "mode"));
10647
+ const merge = arg.str(args, "merge") ?? "upsert";
10648
+ if (merge !== "upsert" && merge !== "fill") throw new CliError("--merge is upsert|fill", 1);
10568
10649
  const redact2 = rowsRedact(arg.str(args, "redact"));
10569
10650
  const rows = await inlineRows(dir, files, args, ctx);
10651
+ const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10570
10652
  const { importLocalWorldData: importLocalWorldData2 } = await runtimeData();
10571
10653
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
10654
+ const { BridgeRejected: BridgeRejected2 } = await Promise.resolve().then(() => (init_client(), client_exports));
10572
10655
  const creds = credentialsForRuntime2(arg.str(args, "host"));
10573
- printJson(ctx, { world: dir, ...inputsField(files, labels), ...await importLocalWorldData2(dir, rows, { mode, redact: redact2 }, creds) });
10574
- return 0;
10656
+ const report = arg.str(args, "report");
10657
+ try {
10658
+ const imported = await importLocalWorldData2(dir, rows, { mode, ...merge === "fill" ? { merge } : {}, redact: redact2 }, creds);
10659
+ if (report !== void 0) fs27.writeFileSync(report, "");
10660
+ printJson(ctx, {
10661
+ world: dir,
10662
+ ...inputsField(files, labels),
10663
+ rows: count,
10664
+ refusalCount: 0,
10665
+ refusals: [],
10666
+ ...imported,
10667
+ ...imported.entity_counts ? { entityCounts: imported.entity_counts } : {}
10668
+ });
10669
+ return 0;
10670
+ } catch (error) {
10671
+ if (!(error instanceof BridgeRejected2)) throw error;
10672
+ const refusals = refusalsFromBridge(error.detail);
10673
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10674
+ printJson(ctx, { world: dir, ...inputsField(files, labels), rows: count, refusalCount: refusals.length, refusals, entityCounts: {}, changed: false });
10675
+ return 2;
10676
+ }
10575
10677
  }
10576
10678
  async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10577
- const rows = await inlineRows(dir, files, args, ctx);
10679
+ const rows = await inlineRows(dir, files, args, ctx, { cap: false });
10578
10680
  const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10579
10681
  const { checkLocalWorldData: checkLocalWorldData2 } = await runtimeData();
10580
10682
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
@@ -10588,14 +10690,19 @@ async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10588
10690
  return 0;
10589
10691
  } catch (error) {
10590
10692
  if (!(error instanceof BridgeRejected2)) throw error;
10591
- const refusal = refusalFromBridge(error.detail);
10592
- if (report !== void 0) fs27.writeFileSync(report, JSON.stringify(refusal) + "\n");
10593
- printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: 1, refusals: [refusal], entityCounts: {} });
10693
+ const refusals = refusalsFromBridge(error.detail);
10694
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10695
+ printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: refusals.length, refusals, entityCounts: {} });
10594
10696
  return 2;
10595
10697
  }
10596
10698
  }
10699
+ function refusalsFromBridge(detail) {
10700
+ if (Array.isArray(detail.refusals) && detail.refusals.length && detail.refusals.every((r) => typeof r === "object" && r !== null))
10701
+ return detail.refusals;
10702
+ return [refusalFromBridge(detail)];
10703
+ }
10597
10704
  function refusalFromBridge(detail) {
10598
- const pointer = detail.path ?? "/";
10705
+ const pointer = detail.path || detail.schema_path || "/";
10599
10706
  const [, entity, index, field] = /^\/([^/]+)(?:\/(\d+))?(?:\/(.+))?$/.exec(pointer) ?? [];
10600
10707
  return {
10601
10708
  chunk: 0,
@@ -11301,6 +11408,14 @@ init_config();
11301
11408
  init_router();
11302
11409
  init_worlds();
11303
11410
  init_shared();
11411
+ async function findTaskByName(name, options) {
11412
+ for (let page = 1; ; page++) {
11413
+ const batch = await listTasks({ page, limit: 100 }, options);
11414
+ const hit = batch.tasks.find((task) => task.name === name);
11415
+ if (hit) return hit;
11416
+ if (page >= batch.meta.totalPages) return null;
11417
+ }
11418
+ }
11304
11419
  var WORLD_FLAG = {
11305
11420
  name: "world",
11306
11421
  short: "w",
@@ -11372,20 +11487,42 @@ function registerTaskCommands(root) {
11372
11487
  },
11373
11488
  WORLD_FLAG,
11374
11489
  MESSAGE_FLAG2,
11490
+ {
11491
+ name: "replace",
11492
+ help: "A task by this name already exists: store the spec as its next version instead of refusing (409).",
11493
+ boolean: true
11494
+ },
11375
11495
  HOST_FLAG
11376
11496
  ],
11377
11497
  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.",
11378
11498
  run: async (args, ctx) => {
11379
11499
  const spec = readTaskSpec(args.positionals[0], "spec");
11380
- const created = await createTask(
11381
- {
11382
- spec,
11383
- name: arg.str(args, "name"),
11384
- world: arg.str(args, "world"),
11385
- message: arg.str(args, "message")
11386
- },
11387
- worldsOptions(credentials(args))
11388
- );
11500
+ const options = worldsOptions(credentials(args));
11501
+ const input = {
11502
+ spec,
11503
+ name: arg.str(args, "name"),
11504
+ world: arg.str(args, "world"),
11505
+ message: arg.str(args, "message")
11506
+ };
11507
+ let created;
11508
+ try {
11509
+ created = await createTask(input, options);
11510
+ } catch (error) {
11511
+ if (!arg.bool(args, "replace") || !(error instanceof ApiError2) || error.status !== 409) throw error;
11512
+ const name = input.name ?? spec.name;
11513
+ const existing = name ? await findTaskByName(name, options) : null;
11514
+ if (!existing) throw error;
11515
+ created = await updateTask(
11516
+ existing.id,
11517
+ {
11518
+ spec,
11519
+ message: input.message,
11520
+ ...input.world === void 0 ? {} : { world: input.world }
11521
+ },
11522
+ options
11523
+ );
11524
+ ctx.stderr(`task '${name}' exists (${existing.id}); stored the spec as version ${String(created.version)}`);
11525
+ }
11389
11526
  printDeprecations(ctx, created.deprecations);
11390
11527
  printJson(ctx, created);
11391
11528
  }
@@ -12949,7 +13086,19 @@ function registerRunCommands2(worlds) {
12949
13086
  }
12950
13087
  return report.ok ? 0 : 1;
12951
13088
  }
12952
- const pushed = await push(dir, { branch, force: true, message, options });
13089
+ const packaged = isConnectorWorld(dir) ? await packageApiBundle(dir, args, ctx) : null;
13090
+ const pushed = await push(packaged ?? dir, {
13091
+ ...packaged ? { slug: meta.slug ?? path25.basename(dir) } : {},
13092
+ branch,
13093
+ force: true,
13094
+ message,
13095
+ options
13096
+ });
13097
+ if (packaged) {
13098
+ const carried = readLocalMeta(packaged);
13099
+ if (carried) writeLocalMeta(dir, carried);
13100
+ fs34.rmSync(packaged, { recursive: true, force: true });
13101
+ }
12953
13102
  ctx.stderr(`pushed ${pushed.slug}@${branch} (${pushed.contentHash.slice(0, 8)})`);
12954
13103
  const agent = await loadAgent(agentFile);
12955
13104
  const world = await openWorld(`${pushed.slug}@${branch}`, options);
@@ -13002,7 +13151,7 @@ function registerServeCommand(worlds) {
13002
13151
  worlds.command({
13003
13152
  name: "serve",
13004
13153
  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.",
13005
- 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.",
13154
+ 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.",
13006
13155
  positionals: [
13007
13156
  {
13008
13157
  name: "path",
@@ -13061,6 +13210,11 @@ function registerServeCommand(worlds) {
13061
13210
  );
13062
13211
  return localModule(argv, local);
13063
13212
  }
13213
+ if (!local && fs35.existsSync(target) && fs35.statSync(target).isDirectory())
13214
+ ctx.stderr(
13215
+ `# ${localRuntimeReason()}
13216
+ # 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).`
13217
+ );
13064
13218
  const creds = resolveCredentials(arg.str(args, "host"));
13065
13219
  const options = {
13066
13220
  host: creds.host,
@@ -13079,7 +13233,7 @@ function registerServeCommand(worlds) {
13079
13233
  ctx.stderr(
13080
13234
  "`worlds serve` runs a local session with the Python runtime; opening a hosted api-surface session instead."
13081
13235
  );
13082
- if (!local) ctx.stderr(`# ${localRuntimeReason()}`);
13236
+ if (!local && !(fs35.existsSync(target) && fs35.statSync(target).isDirectory())) ctx.stderr(`# ${localRuntimeReason()}`);
13083
13237
  let scenario = arg.str(args, "scenario") ?? arg.str(args, "task");
13084
13238
  if (!scenario) {
13085
13239
  const world = await openWorld(slugRef, options);
@@ -13296,6 +13450,8 @@ function registerTestCommand(worlds) {
13296
13450
  var fs37 = __toESM(require("fs"));
13297
13451
  var path28 = __toESM(require("path"));
13298
13452
  init_router();
13453
+ init_session();
13454
+ init_shared();
13299
13455
  init_local();
13300
13456
  init_client();
13301
13457
  function parseArgs2(raw, stdin) {
@@ -13318,6 +13474,11 @@ function parseArgs2(raw, stdin) {
13318
13474
  return value;
13319
13475
  }
13320
13476
  var SERVED_URL = /^https?:\/\//;
13477
+ function settleStatus(report) {
13478
+ const code = report.result.status;
13479
+ report.status = code >= 200 && code < 300 ? "ok" : code >= 500 ? "error" : "refused";
13480
+ return report;
13481
+ }
13321
13482
  async function sessionVerb(base, verb, body) {
13322
13483
  let response;
13323
13484
  try {
@@ -13337,6 +13498,43 @@ async function sessionVerb(base, verb, body) {
13337
13498
  }
13338
13499
  return { status: response.status, body: parsed };
13339
13500
  }
13501
+ function isRouteAnswer(value) {
13502
+ return typeof value === "object" && value !== null && typeof value.status === "number" && "body" in value;
13503
+ }
13504
+ async function callHosted(sessionId, tool, args, wants, options) {
13505
+ const live = await attachSession(sessionId, options);
13506
+ const report = {
13507
+ status: "ok",
13508
+ tools: (await live.toolkit()).specs.map((spec) => spec.name),
13509
+ result: { status: 0, body: null }
13510
+ };
13511
+ if (wants.seed) {
13512
+ const { rows, mode } = wants.seed;
13513
+ if (!rows || typeof rows !== "object" || Array.isArray(rows))
13514
+ throw new CliError("--seed on a hosted session is the host's shape: {rows: {entity: [row, ...]}, mode?: append|replace}");
13515
+ if (mode !== void 0 && mode !== "append" && mode !== "replace")
13516
+ throw new CliError("--seed mode must be append or replace");
13517
+ const seeded = await live.seed(rows, mode ? { mode } : {});
13518
+ report.seed = seeded;
13519
+ }
13520
+ try {
13521
+ const answer = await live.call(tool, args);
13522
+ report.result = isRouteAnswer(answer) ? answer : { status: 200, body: answer };
13523
+ } catch (error) {
13524
+ if (!(error instanceof WorldSessionCallError)) throw error;
13525
+ report.result = { status: 500, body: { error: error.message } };
13526
+ }
13527
+ if (wants.state) report.state = await live.state();
13528
+ if (wants.grade) report.grade = await live.grade();
13529
+ if (wants.close) {
13530
+ await live.close();
13531
+ report.closed = true;
13532
+ }
13533
+ return settleStatus(report);
13534
+ }
13535
+ function looksLikeSessionId(target) {
13536
+ return !target.includes("/") && !target.startsWith(".") && !fs37.existsSync(target);
13537
+ }
13340
13538
  async function callServed(base, tool, args, wants) {
13341
13539
  const url = base.replace(/\/+$/, "");
13342
13540
  const tools = await sessionVerb(url, "tools");
@@ -13362,16 +13560,16 @@ async function callServed(base, tool, args, wants) {
13362
13560
  if (closed.status !== 200) throw new CliError(`POST /__session/close answered ${closed.status}`, 1);
13363
13561
  report.closed = true;
13364
13562
  }
13365
- return report;
13563
+ return settleStatus(report);
13366
13564
  }
13367
13565
  function registerCallCommand(worlds) {
13368
13566
  worlds.command({
13369
13567
  name: "call",
13370
- help: "Call one tool on a world directory here, or on a served session by URL; a dependency's tool as alias.tool.",
13568
+ 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.",
13371
13569
  positionals: [
13372
13570
  {
13373
13571
  name: "path",
13374
- help: "World directory (a schema world with gateway-env.toml), or the url of a running `worlds serve` session."
13572
+ 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`)."
13375
13573
  },
13376
13574
  { name: "tool", help: "Tool name; a dependency's tool as <alias>.<tool>." }
13377
13575
  ],
@@ -13381,13 +13579,14 @@ function registerCallCommand(worlds) {
13381
13579
  { name: "scenario", help: "Start in one of the world's scenarios (default: the base state)." },
13382
13580
  {
13383
13581
  name: "seed",
13384
- help: "Seed rows before the call, the host's shape: JSON {rows: {entity: [row, ...]}, mode?: append|replace}, @file, or -."
13582
+ 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 -."
13385
13583
  },
13386
13584
  { name: "state", help: "Print the world's state after the call.", boolean: true },
13387
13585
  { name: "grade", help: "Run the verifiers after the call and print the scores.", boolean: true },
13388
- { name: "close", help: "On a served session (url): end it after the call; `worlds serve` returns.", boolean: true }
13586
+ { name: "close", help: "On a served session (url) or a hosted one (id): end it after the call.", boolean: true },
13587
+ HOST_FLAG
13389
13588
  ],
13390
- 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',
13589
+ 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',
13391
13590
  run: async (args, ctx) => {
13392
13591
  const [target, tool] = args.positionals;
13393
13592
  if (SERVED_URL.test(target)) {
@@ -13405,7 +13604,28 @@ function registerCallCommand(worlds) {
13405
13604
  ctx.stdout(JSON.stringify(report2, null, 2));
13406
13605
  return report2.result.status >= 200 && report2.result.status < 300 ? 0 : 1;
13407
13606
  }
13408
- if (arg.bool(args, "close")) throw new CliError("--close ends a served session; pass its url instead of a directory");
13607
+ if (looksLikeSessionId(target)) {
13608
+ for (const flag of ["task", "scenario"])
13609
+ if (arg.str(args, flag) !== void 0)
13610
+ throw new CliError(`--${flag} belongs to \`gateway worlds session open\`; session ${target} already has its own`);
13611
+ const stdin2 = args.flags.args === "-" || args.flags.seed === "-" ? await ctx.stdin() : "";
13612
+ const seedRaw2 = arg.str(args, "seed");
13613
+ const report2 = await callHosted(
13614
+ target,
13615
+ tool,
13616
+ parseArgs2(arg.str(args, "args"), stdin2),
13617
+ {
13618
+ ...seedRaw2 === void 0 ? {} : { seed: parseArgs2(seedRaw2, stdin2) },
13619
+ state: arg.bool(args, "state"),
13620
+ grade: arg.bool(args, "grade"),
13621
+ close: arg.bool(args, "close")
13622
+ },
13623
+ worldsOptions(credentials(args))
13624
+ );
13625
+ ctx.stdout(JSON.stringify(report2, null, 2));
13626
+ return report2.result.status >= 200 && report2.result.status < 300 ? 0 : 1;
13627
+ }
13628
+ if (arg.bool(args, "close")) throw new CliError("--close ends a served or hosted session; pass its url or id instead of a directory");
13409
13629
  const dir = path28.resolve(target);
13410
13630
  if (!fs37.existsSync(dir) || !fs37.statSync(dir).isDirectory()) throw new CliError(`Not a directory: ${dir}`, 1);
13411
13631
  const local = localRuntime();
@@ -13435,7 +13655,7 @@ function registerCallCommand(worlds) {
13435
13655
  );
13436
13656
  const detail = detailFrom(payload);
13437
13657
  if (detail) throw new BridgeRejected(detail);
13438
- const report = payload;
13658
+ const report = settleStatus(payload);
13439
13659
  ctx.stdout(JSON.stringify(report, null, 2));
13440
13660
  return report.result.status >= 200 && report.result.status < 300 ? 0 : 1;
13441
13661
  }
@@ -13600,6 +13820,38 @@ function declaredOperationNames(toml) {
13600
13820
  }
13601
13821
  return names;
13602
13822
  }
13823
+ function declaredRoutes(toml) {
13824
+ const routes = [];
13825
+ let current = null;
13826
+ for (const raw of toml.split("\n")) {
13827
+ const line = raw.trim();
13828
+ if (line.startsWith("[")) {
13829
+ current = line === "[[operations]]" ? { name: "", methods: [], path: "", params: [] } : null;
13830
+ if (current) routes.push(current);
13831
+ continue;
13832
+ }
13833
+ if (!current) continue;
13834
+ const str2 = (key) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`).exec(line)?.[1];
13835
+ const list = (key) => {
13836
+ const m = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`).exec(line);
13837
+ return m ? [...m[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]) : void 0;
13838
+ };
13839
+ const name = str2("name");
13840
+ if (name !== void 0) current.name = name;
13841
+ const routePath = str2("path");
13842
+ if (routePath !== void 0) current.path = routePath;
13843
+ const method = str2("method");
13844
+ if (method !== void 0 && !current.methods.includes(method.toUpperCase())) current.methods.push(method.toUpperCase());
13845
+ const methods = list("methods");
13846
+ if (methods) {
13847
+ for (const m of methods) if (!current.methods.includes(m.toUpperCase())) current.methods.push(m.toUpperCase());
13848
+ }
13849
+ const params = list("params");
13850
+ if (params) current.params = params;
13851
+ }
13852
+ for (const route of routes) if (!route.methods.length) route.methods.push("GET");
13853
+ return routes;
13854
+ }
13603
13855
  function removeRoute(toml, name) {
13604
13856
  const lines = toml.split("\n");
13605
13857
  const kept = [];
@@ -13661,6 +13913,16 @@ function addRoute(toml, spec, declaredEntities2, options = {}) {
13661
13913
  throw new CliError("--handler only applies with --action handler");
13662
13914
  if (spec.api.status !== void 0 && (spec.api.status < 200 || spec.api.status > 299))
13663
13915
  throw new CliError("--status must be a 2xx");
13916
+ if (spec.api.action !== void 0 && ["create", "update", "delete"].includes(spec.api.action) && spec.method === "GET")
13917
+ throw new CliError(
13918
+ `--action ${spec.api.action} writes, but --method GET reads; pass --method ${spec.api.action === "create" ? "POST" : spec.api.action === "update" ? "PATCH" : "DELETE"}`
13919
+ );
13920
+ const sameParams = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
13921
+ for (const route of declaredRoutes(toml))
13922
+ if (route.name !== spec.name && route.path === spec.path && route.methods.includes(spec.method) && sameParams(route.params, spec.params))
13923
+ throw new CliError(
13924
+ `${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`
13925
+ );
13664
13926
  if (spec.entity !== void 0 && declaredEntities2 && !declaredEntities2.includes(spec.entity))
13665
13927
  throw new CliError(
13666
13928
  `Entity ${spec.entity} is not declared in schema/world.json (have: ${declaredEntities2.join(", ") || "none"}); run \`gateway worlds schema entity add\` first`
@@ -13793,18 +14055,43 @@ var assertManifest = (toml) => {
13793
14055
  if (!/^\s*\[(environment|env)\]\s*$/m.test(toml))
13794
14056
  throw new CliError("gateway-env.toml has no [environment] table; it is not a schema world manifest");
13795
14057
  };
13796
- function addDependency(toml, spec, depServes) {
14058
+ function removeDependency(toml, alias) {
14059
+ const kept = [];
14060
+ let dropping = false;
14061
+ for (const raw of toml.split("\n")) {
14062
+ const line = raw.trim();
14063
+ if (line.startsWith("[")) dropping = line === `[dependencies.${alias}]` || line.startsWith(`[dependencies.${alias}.`);
14064
+ if (!dropping) kept.push(raw);
14065
+ }
14066
+ while (kept.length && kept[kept.length - 1].trim() === "") kept.pop();
14067
+ return kept.join("\n") + "\n";
14068
+ }
14069
+ function dependencyServes(depDir) {
14070
+ const manifest = path29.join(depDir, "gateway-env.toml");
14071
+ if (!fs38.existsSync(manifest)) return void 0;
14072
+ const tools = manifestServedTools(fs38.readFileSync(manifest, "utf8"));
14073
+ const connector = path29.join(depDir, "connector.toml");
14074
+ const routes = fs38.existsSync(connector) ? declaredRoutes(fs38.readFileSync(connector, "utf8")).map((r) => r.name).filter(Boolean) : [];
14075
+ return tools === void 0 ? void 0 : { tools, routes };
14076
+ }
14077
+ function addDependency(toml, spec, depServes, opts = {}) {
13797
14078
  assertManifest(toml);
13798
14079
  if (!ALIAS.test(spec.alias))
13799
14080
  throw new CliError(`Aliases match [a-z][a-z0-9_]{0,31}, got ${JSON.stringify(spec.alias)}`);
13800
- if (declaredAliases(toml).includes(spec.alias))
13801
- throw new CliError(`[dependencies.${spec.alias}] is already declared`);
14081
+ if (declaredAliases(toml).includes(spec.alias)) {
14082
+ if (!opts.replace)
14083
+ throw new CliError(`[dependencies.${spec.alias}] is already declared; pass --replace to redeclare it (pin, path, tools, task, map)`);
14084
+ toml = removeDependency(toml, spec.alias);
14085
+ }
13802
14086
  if (!PIN.test(spec.pin)) throw new CliError(`--pin is <slug>@<ref>, got ${JSON.stringify(spec.pin)}`);
13803
14087
  if (path29.isAbsolute(spec.path)) throw new CliError("The dependency path is stored relative to the world");
13804
14088
  if (depServes) {
14089
+ const serves = Array.isArray(depServes) ? { tools: depServes, routes: [] } : depServes;
13805
14090
  for (const tool of spec.tools)
13806
- if (!depServes.includes(tool))
13807
- throw new CliError(`${spec.alias} does not serve ${tool}; it serves: ${depServes.join(", ") || "nothing"}`);
14091
+ if (!serves.tools.includes(tool))
14092
+ throw new CliError(
14093
+ 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)` : "")
14094
+ );
13808
14095
  }
13809
14096
  const body = toml.endsWith("\n") ? toml : toml + "\n";
13810
14097
  return body + "\n" + renderDependency(spec);
@@ -13820,7 +14107,9 @@ function addTask(toml, spec, known = {}) {
13820
14107
  if (known.verifiers) {
13821
14108
  for (const v of spec.verifiers)
13822
14109
  if (!known.verifiers.includes(v))
13823
- throw new CliError(`verifiers/${v}.sql does not exist (have: ${known.verifiers.join(", ") || "none"})`);
14110
+ throw new CliError(
14111
+ `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`
14112
+ );
13824
14113
  }
13825
14114
  const aliases = declaredAliases(toml);
13826
14115
  for (const [alias, names] of Object.entries(spec.worlds)) {
@@ -13882,8 +14171,10 @@ function declaredEntities(dir) {
13882
14171
  var WORLD_SLUG = /^[a-z0-9][a-z0-9-]*$/;
13883
14172
  function connectorTomlSkeleton(dir) {
13884
14173
  const manifest = path29.join(dir, "gateway-env.toml");
14174
+ if (!fs38.existsSync(dir))
14175
+ throw new CliError(`${dir} does not exist; run \`gateway worlds schema init ${dir} --connector custom\` to start a world there`, 1);
13885
14176
  if (!fs38.existsSync(manifest))
13886
- throw new CliError(`${dir} holds no connector.toml and no gateway-env.toml; run \`gateway worlds schema init\` first`, 1);
14177
+ 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);
13887
14178
  const name = /^\s*name\s*=\s*"([^"]*)"/m.exec(fs38.readFileSync(manifest, "utf8"))?.[1];
13888
14179
  const slug = name && WORLD_SLUG.test(name) ? name : path29.basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "world";
13889
14180
  return [
@@ -13902,6 +14193,26 @@ function scaffoldVerifier(entity) {
13902
14193
  SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
13903
14194
  `;
13904
14195
  }
14196
+ function verifierSql(name, entity, where) {
14197
+ 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)}`);
14198
+ 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)}`);
14199
+ if (where === void 0) return scaffoldVerifier(entity);
14200
+ const clause = where.trim();
14201
+ if (!clause) throw new CliError("--where is a SQL condition over the entity's columns; it cannot be empty");
14202
+ return `-- ${name}: scores 1.0 once a ${entity} row satisfies the condition; edit for real tasks.
14203
+ -- A verifier is one SQL statement returning one number in 0..1 (0.5 is partial credit).
14204
+ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}" WHERE ${clause};
14205
+ `;
14206
+ }
14207
+ function addVerifier(dir, name, entity, where) {
14208
+ const sql = verifierSql(name, entity, where);
14209
+ const file = path29.join(dir, "verifiers", `${name}.sql`);
14210
+ if (fs38.existsSync(file))
14211
+ throw new CliError(`verifiers/${name}.sql already exists (have: ${(verifierNames2(dir) ?? []).join(", ")}); edit it, or pick another name`);
14212
+ fs38.mkdirSync(path29.dirname(file), { recursive: true });
14213
+ fs38.writeFileSync(file, sql);
14214
+ return file;
14215
+ }
13905
14216
  function repointScaffoldVerifier(dir, entity, declared) {
13906
14217
  const file = path29.join(dir, "verifiers", "state_present.sql");
13907
14218
  if (!fs38.existsSync(file)) return null;
@@ -13945,7 +14256,7 @@ function registerScaffoldCommands(worlds) {
13945
14256
  repeat: true
13946
14257
  }
13947
14258
  ],
13948
- 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.",
14259
+ 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.",
13949
14260
  run: async (args, ctx) => {
13950
14261
  const dir = path29.resolve(args.positionals[0]);
13951
14262
  const file = path29.join(dir, "schema", "world.json");
@@ -13983,6 +14294,43 @@ function registerScaffoldCommands(worlds) {
13983
14294
  ctx.stdout(JSON.stringify(out, null, 2));
13984
14295
  }
13985
14296
  });
14297
+ schema.group("verifier", "Write verifiers/<name>.sql: the SQL that grades a task on the world's end state.").command({
14298
+ name: "add",
14299
+ help: "Scaffold one verifier: a SQL statement over an entity's table returning 1.0 when a row satisfies --where (or any row exists).",
14300
+ positionals: [
14301
+ { name: "path", help: "World directory holding schema/world.json" },
14302
+ { name: "name", help: "Verifier name, e.g. case_opened; what `schema task add --verifier` takes" }
14303
+ ],
14304
+ flags: [
14305
+ { name: "entity", help: "Entity whose table the verifier counts (from schema/world.json).", short: "e" },
14306
+ { 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" }
14307
+ ],
14308
+ 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.",
14309
+ run: async (args, ctx) => {
14310
+ const dir = path29.resolve(args.positionals[0]);
14311
+ const name = args.positionals[1];
14312
+ const entity = arg.str(args, "entity");
14313
+ const declared = declaredEntities(dir);
14314
+ if (declared === void 0) throw new CliError(`${dir} has no schema/world.json; run \`gateway worlds schema init ${args.positionals[0]} --connector custom\` first`);
14315
+ if (!entity) throw new CliError(`--entity is required: one of ${declared.join(", ") || "(declare one with `gateway worlds schema entity add` first)"}`);
14316
+ if (!declared.includes(entity)) throw new CliError(`Unknown entity ${entity}; the world has ${declared.join(", ") || "none"}`);
14317
+ const file = addVerifier(dir, name, entity, arg.str(args, "where"));
14318
+ const rel = path29.relative(process.cwd(), dir) || ".";
14319
+ ctx.stdout(
14320
+ JSON.stringify(
14321
+ {
14322
+ status: "ok",
14323
+ verifier: name,
14324
+ entity,
14325
+ file: path29.relative(process.cwd(), file) || file,
14326
+ next: `gateway worlds schema task add ${rel} <task_id> --prompt "<what the agent is told>" --verifier ${name}`
14327
+ },
14328
+ null,
14329
+ 2
14330
+ )
14331
+ );
14332
+ }
14333
+ });
13986
14334
  schema.command({
13987
14335
  name: "link",
13988
14336
  help: "Link another local world as [dependencies.<alias>] in gateway-env.toml: its tools serve as <alias>.<tool>, its verifiers grade as <alias>/<verifier>.",
@@ -13996,7 +14344,12 @@ function registerScaffoldCommands(worlds) {
13996
14344
  ],
13997
14345
  flags: [
13998
14346
  { name: "pin", help: "<slug>@<ref> the platform resolves at push; default <dependency name>@main." },
13999
- { name: "tools", help: "Dependency tools to serve as <alias>.<tool>; comma-separated or repeatable. Default: none.", repeat: true },
14347
+ {
14348
+ name: "tools",
14349
+ help: "Dependency tools (its [tools] serve, not its routes) to serve as <alias>.<tool>; comma-separated or repeatable. Default: every tool it has.",
14350
+ repeat: true
14351
+ },
14352
+ { name: "replace", help: "Redeclare an alias already linked (pin, path, tools, task, map rewritten).", boolean: true },
14000
14353
  { name: "task", help: "Scenario the dependency starts in: scenarios/<name>/ of its tree (the shipped templates have `default`)." },
14001
14354
  {
14002
14355
  name: "map",
@@ -14037,7 +14390,7 @@ function registerScaffoldCommands(worlds) {
14037
14390
  tools: arg.list(args, "tools").flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean),
14038
14391
  entities: arg.list(args, "map").map(parseEntityMap)
14039
14392
  };
14040
- const updated = addDependency(toml, spec, manifestServedTools(depToml));
14393
+ const updated = addDependency(toml, spec, dependencyServes(depDir), { replace: arg.bool(args, "replace") });
14041
14394
  fs38.writeFileSync(file, updated);
14042
14395
  ctx.stdout(
14043
14396
  JSON.stringify(
@@ -14106,7 +14459,11 @@ function registerScaffoldCommands(worlds) {
14106
14459
  worlds: worlds2,
14107
14460
  rewards: [...spec.verifiers, ...Object.entries(worlds2).flatMap(([a, names]) => names.map((n) => `${a}/${n}`))],
14108
14461
  file: path29.relative(process.cwd(), file) || file,
14109
- next: `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14462
+ next: [
14463
+ `gateway worlds schema compile ${path29.relative(process.cwd(), dir) || "."} # a manifest edit invalidates the compiled contract`,
14464
+ `gateway worlds schema check ${path29.relative(process.cwd(), dir) || "."}`,
14465
+ `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14466
+ ]
14110
14467
  },
14111
14468
  null,
14112
14469
  2
@@ -14245,7 +14602,7 @@ function buildCli() {
14245
14602
  "schema",
14246
14603
  "Compile and check gateway-world/1 contracts (the runtime runs on the platform)."
14247
14604
  );
14248
- 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.";
14605
+ 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.";
14249
14606
  worlds.group(
14250
14607
  "connector",
14251
14608
  "Vendor connections: validate, capture, conform, ingest, publish, clone."