@withgateway/sdk 0.2.1 → 0.2.2

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.
package/dist/cli.mjs CHANGED
@@ -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) {
@@ -4932,14 +4937,15 @@ function initNextSteps(dir, shape) {
4932
4937
  );
4933
4938
  if (shape.blank)
4934
4939
  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}`
4940
+ `gateway worlds schema verifier add ${dir} <verifier> --entity <entity> --where "<sql condition>" # SQL that grades the end state; state_present.sql is the placeholder`,
4941
+ `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier <verifier>`
4937
4942
  );
4938
4943
  steps.push(
4944
+ `gateway worlds schema compile ${dir} # after any edit to schema/, connector.toml or gateway-env.toml`,
4939
4945
  `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}`
4946
+ `gateway worlds data import ${dir} <rows.json> # {"<entity>": [row, ...]}`,
4947
+ `gateway worlds serve ${dir} # then: gateway worlds call http://127.0.0.1:<port> <tool> --args '{...}'`,
4948
+ `gateway worlds create <slug> --from ${dir} # publish last`
4943
4949
  );
4944
4950
  return steps;
4945
4951
  }
@@ -5196,7 +5202,7 @@ function registerSchemaCommands(schema) {
5196
5202
  for (const [command2, help] of [
5197
5203
  [
5198
5204
  "compile",
5199
- "Compile the world's contract on the platform and write back what the compiler produced."
5205
+ "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
5206
  ],
5201
5207
  [
5202
5208
  "check",
@@ -6735,6 +6741,9 @@ function harborRunPlan(dir, taskId, logsDir = LOGS_PLACEHOLDER) {
6735
6741
  validation
6736
6742
  };
6737
6743
  }
6744
+ function notGraded(step, status) {
6745
+ 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`;
6746
+ }
6738
6747
  function dockerBin() {
6739
6748
  return process.env.GATEWAY_DOCKER || "docker";
6740
6749
  }
@@ -6766,10 +6775,12 @@ function dryRunHarbor(dir, plan) {
6766
6775
  };
6767
6776
  const image = plan.image.dockerfile ? plan.image.tag : plan.image.ref;
6768
6777
  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" };
6778
+ const buildStatus = plan.commands.build ? spawnArgv(plan.commands.build, 20 * 6e4) : 0;
6779
+ if (buildStatus !== 0)
6780
+ return { executed: true, docker: docker.version, image, exitCode: buildStatus, output: outputs.join("\n"), commands, reason: notGraded("docker build", buildStatus) };
6781
+ const pullStatus = plan.commands.pull ? spawnArgv(plan.commands.pull, 20 * 6e4) : 0;
6782
+ if (pullStatus !== 0)
6783
+ return { executed: true, docker: docker.version, image, exitCode: pullStatus, output: outputs.join("\n"), commands, reason: notGraded("docker pull", pullStatus) };
6773
6784
  const run = plan.commands.run.map((a) => a.replace(`${LOGS_PLACEHOLDER}:/logs`, `${logs}:/logs`));
6774
6785
  const exitCode = spawnArgv(run, (plan.timeouts.agent + plan.timeouts.verifier) * 1e3);
6775
6786
  const rewards = readReward(path10.join(logs, "verifier"));
@@ -6890,7 +6901,8 @@ function dryRunVerifiers(dir, plan, opts) {
6890
6901
  };
6891
6902
  commands.push(`${shellLine(plan.commands.build)} # Dockerfile on stdin: ${JSON.stringify(plan.image.dockerfile)}`);
6892
6903
  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 ?? "")) };
6904
+ if (built.status !== 0)
6905
+ return { executed: true, exitCode: built.status ?? 1, reason: notGraded("docker build", built.status ?? 1), commands, output: tail2((built.stdout ?? "") + (built.stderr ?? "")) };
6894
6906
  commands.push(shellLine(plan.commands.run));
6895
6907
  const ran = spawnSync2(plan.commands.run[0], plan.commands.run.slice(1), { encoding: "utf8", timeout: 5 * 6e4 });
6896
6908
  return { ...discoverResult(readDiscover(ran.stdout ?? ""), `${plan.image.tag} (Docker ${docker.version})`, ran.stderr ?? "", commands), docker: docker.version, image: plan.image.tag };
@@ -8038,8 +8050,9 @@ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
8038
8050
  if (arg.bool(args, "json")) printJson(ctx, { plan: plan2, result: result2 });
8039
8051
  else printDryRun(ctx, plan2, result2);
8040
8052
  if (invalid) return 2;
8053
+ if (result2.executed && result2.reward === void 0) return 2;
8041
8054
  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`);
8055
+ ctx.stderr(result2.reward === null ? "ungraded: the grader ran but wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8043
8056
  return 2;
8044
8057
  }
8045
8058
  return 0;
@@ -8823,17 +8836,23 @@ async function extractRows(input, config, opts, out) {
8823
8836
  const keys = entity.primaryKey;
8824
8837
  const summary2 = { read: 0, rows: 0, unknownFields: {}, redacted: { dropped: 0, hashed: 0 } };
8825
8838
  const held = /* @__PURE__ */ new Map();
8839
+ const skipped = {};
8840
+ const skip = (reason) => {
8841
+ skipped[reason] = (skipped[reason] ?? 0) + 1;
8842
+ };
8826
8843
  const take = (raw) => {
8827
8844
  summary2.read++;
8828
8845
  const row = clean(raw, entity.fields, summary2);
8829
- if (!keys.every((name) => row.has(name))) return;
8846
+ if (!keys.every((name) => row.has(name))) return skip(`row lacks the primary key (${keys.join(", ")})`);
8830
8847
  const key = dumps(keys.map((name) => row.get(name)));
8831
8848
  const existing = held.get(key);
8832
8849
  if (!existing) held.set(key, row);
8833
8850
  else if (opts.merge === "upsert") held.set(key, row);
8834
8851
  else for (const [name, value] of row) if (!existing.has(name)) existing.set(name, value);
8835
8852
  };
8836
- await adapters[opts.shape](input, config, keys, take);
8853
+ await adapters[opts.shape](input, config, keys, take, skip);
8854
+ if (Object.keys(skipped).length) summary2.skipped = skipped;
8855
+ if (summary2.read === 0 && Object.keys(skipped).length) summary2.hint = SHAPE_HINT[opts.shape];
8837
8856
  const policy = opts.redact ? config.redact : null;
8838
8857
  for (const row of held.values()) {
8839
8858
  let final = row;
@@ -8868,14 +8887,30 @@ function countRedaction(before, after, policy, summary2) {
8868
8887
  else if (policy.hash.includes(name) && value !== null) summary2.redacted.hashed++;
8869
8888
  }
8870
8889
  }
8871
- var toolResults = async (input, _config, keys, take) => {
8890
+ var SHAPE_HINT = {
8891
+ "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',
8892
+ "vendor-envelope": "vendor-envelope reads the vendor's own response: a bare array, or an object whose [api].envelope key holds the rows",
8893
+ "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'
8894
+ };
8895
+ var toolResults = async (input, _config, keys, take, skip) => {
8872
8896
  for await (const record of records(input)) {
8873
- if (!isObject(record)) continue;
8897
+ if (!isObject(record)) {
8898
+ skip("line is not a JSON object");
8899
+ continue;
8900
+ }
8874
8901
  const raw = record.get("raw_output");
8875
- if (!isObject(raw)) continue;
8902
+ if (!isObject(raw)) {
8903
+ skip("record has no raw_output object");
8904
+ continue;
8905
+ }
8876
8906
  let listed = raw.get("results");
8877
8907
  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);
8908
+ const items = objects(listed);
8909
+ if (items.length === 0) skip("raw_output has no results[] or items[]");
8910
+ for (const item of items) {
8911
+ if (keys.every((name) => item.has(name))) take(item);
8912
+ else skip(`row lacks the primary key (${keys.join(", ")})`);
8913
+ }
8879
8914
  }
8880
8915
  };
8881
8916
  var vendorEnvelope = async (input, config, _keys, take) => {
@@ -8914,13 +8949,21 @@ var vendorEnvelope = async (input, config, _keys, take) => {
8914
8949
  }
8915
8950
  for (const row of objects(dig(document, envelope))) take(row);
8916
8951
  };
8917
- var sessionExport = async (input, config, _keys, take) => {
8952
+ var sessionExport = async (input, config, _keys, take, skip) => {
8918
8953
  for await (const record of records(input)) {
8919
- if (!isObject(record) || record.get("kind") !== "call") continue;
8954
+ if (!isObject(record) || record.get("kind") !== "call") {
8955
+ skip('record is not {"kind": "call", ...}');
8956
+ continue;
8957
+ }
8920
8958
  const error = record.get("error");
8921
- if (error !== null && error !== void 0) continue;
8959
+ if (error !== null && error !== void 0) {
8960
+ skip("call record carries an error");
8961
+ continue;
8962
+ }
8922
8963
  const result = record.get("result") ?? null;
8923
- for (const row of objects(config.envelope ? dig(result, config.envelope) : result)) take(row);
8964
+ const rows = objects(config.envelope ? dig(result, config.envelope) : result);
8965
+ if (rows.length === 0) skip(config.envelope ? `result.${config.envelope} holds no rows` : "result is not an array of rows");
8966
+ for (const row of rows) take(row);
8924
8967
  }
8925
8968
  };
8926
8969
  var adapters = {
@@ -9264,6 +9307,13 @@ function skeleton(records2, entities, kind, opts = {}) {
9264
9307
  let select = kind === "tool-call" ? "result" : "$record";
9265
9308
  const shapeNames = Object.keys(group.shapes);
9266
9309
  if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an array of objects")) select = "result[*]";
9310
+ else if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an object")) {
9311
+ const listed = Object.entries(group.fields).filter(([, info]) => info.list && Object.keys(info.nested).length).map(([name2]) => name2);
9312
+ if (listed.length === 1) {
9313
+ select = `result.${listed[0]}[*]`;
9314
+ lines.push(`# result.${listed[0]} holds the rows: [*] selects each item of an array`);
9315
+ }
9316
+ }
9267
9317
  lines.push("[[sources]]", `name = "${name}"`, `kind = "${kind}"`, `select = "${select}"`);
9268
9318
  lines.push(chosen ? `entity = "${chosen}"` : `entity = "" # one of: ${names.join(", ")}`);
9269
9319
  lines.push("[sources.fields]");
@@ -9756,7 +9806,7 @@ var ENTITY_FLAG = { name: "entity", help: "The entity bare-row files hold." };
9756
9806
  var REPORT_FLAG = { name: "report", help: "Write the refusals as JSONL here." };
9757
9807
  var MESSAGE_FLAG = { name: "message", short: "m", help: "Change reason for the version." };
9758
9808
  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");
9809
+ 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
9810
  data.command({
9761
9811
  name: "import",
9762
9812
  help: "Put rows into a world through its own gate.",
@@ -9919,7 +9969,7 @@ primary key, the world's [redact] policy applied. Summary on stderr:
9919
9969
  { name: "session", help: "With --from traces: every trace of this session (GET /api/public/sessions/{id}?includeIO=true)." },
9920
9970
  { name: "since", help: "With --from traces: only calls that started at or after this ISO time." },
9921
9971
  { 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." },
9972
+ { 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
9973
  { name: "out", help: "With map init: where the skeleton goes (default ingest.toml in the world, or stdout for a slug)." },
9924
9974
  { name: "mode", help: "append (upsert by primary key) | replace (named entities).", default: "append" },
9925
9975
  REDACT_FLAG,
@@ -10352,7 +10402,8 @@ async function mapInitCommand(world, samples, args, ctx) {
10352
10402
  }
10353
10403
  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
10404
  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\``);
10405
+ const fromFlag = from === "tool-calls" ? "" : ` --from ${from}`;
10406
+ 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
10407
  return 0;
10357
10408
  }
10358
10409
  async function ingestCommand(world, inputs, args, ctx, labels = {}) {
@@ -10378,7 +10429,12 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10378
10429
  if (local) return dryRun ? checkLocalDirectory(world, inputs, args, ctx, labels) : importLocalDirectory(world, inputs, args, ctx, labels);
10379
10430
  return importBatch(world, inputs, args, ctx, dryRun ? "check" : "import", void 0, labels);
10380
10431
  }
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");
10432
+ const bareCsv = from === "csv" && transform === void 0 && mapFile === void 0 && !(local && worldMapping(world));
10433
+ const csvEntity = bareCsv ? arg.str(args, "entity") : void 0;
10434
+ if (bareCsv && csvEntity === void 0)
10435
+ throw new CliError(
10436
+ "--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"
10437
+ );
10382
10438
  const mapText = mapFile !== void 0 ? readMapping(mapFile) : void 0;
10383
10439
  const { toolCallsFromObservations: toolCallsFromObservations2 } = await Promise.resolve().then(() => (init_ingest(), ingest_exports));
10384
10440
  const dir = local ? world : await pullWorld(world, credentials(args));
@@ -10416,7 +10472,23 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10416
10472
  const runtimeCreds = credentialsForRuntime2(arg.str(args, "host"));
10417
10473
  let projected = {};
10418
10474
  try {
10419
- if (transform !== void 0) {
10475
+ if (csvEntity !== void 0) {
10476
+ projected = { [csvEntity]: records2.filter((r) => typeof r === "object" && r !== null) };
10477
+ const landed = local && !dryRun ? await importLocalWorldData2(dir, projected, { mode, redact: redact2 }, runtimeCreds) : await checkLocalWorldData2(dir, projected, runtimeCreds, local ? { redact: redact2 } : {});
10478
+ Object.assign(out, {
10479
+ via: "rows",
10480
+ records: records2.length,
10481
+ ingested: records2.length,
10482
+ skipped: {},
10483
+ refusals: [],
10484
+ rows: { [csvEntity]: projected[csvEntity].length },
10485
+ dryRun,
10486
+ redact: redact2,
10487
+ changed: local && !dryRun ? landed.changed : false,
10488
+ kind: landed.kind,
10489
+ entityCounts: landed.entity_counts
10490
+ });
10491
+ } else if (transform !== void 0) {
10420
10492
  const ran = await runTransform(transform, records2, { timeoutMs: timeoutSeconds * 1e3 });
10421
10493
  for (const line of ran.stderr.split("\n")) if (line.trim()) ctx.stderr(`transform: ${line}`);
10422
10494
  projected = ran.rows;
@@ -10519,10 +10591,11 @@ function worldSlug(dir) {
10519
10591
  const slug = readLocalMeta(dir)?.slug;
10520
10592
  return typeof slug === "string" && slug ? slug : path21.basename(path21.resolve(dir));
10521
10593
  }
10522
- async function inlineRows(dir, files, args, ctx) {
10594
+ async function inlineRows(dir, files, args, ctx, opts = {}) {
10523
10595
  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)}\``,
10596
+ const capped = opts.cap ?? true;
10597
+ const tooLarge = (what) => new CliError(
10598
+ `${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
10599
  1
10527
10600
  );
10528
10601
  const paths = [];
@@ -10541,9 +10614,11 @@ async function inlineRows(dir, files, args, ctx) {
10541
10614
  size += fs27.statSync(file).size;
10542
10615
  paths.push(file);
10543
10616
  }
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();
10617
+ if (capped) {
10618
+ if (size > INLINE_BYTES) throw tooLarge(`${size} bytes`);
10619
+ let count = 0;
10620
+ for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge(`more than ${INLINE_ROWS} rows`);
10621
+ }
10547
10622
  return parseRows(paths, entity);
10548
10623
  } finally {
10549
10624
  if (scratch) fs27.rmSync(scratch, { recursive: true, force: true });
@@ -10551,16 +10626,39 @@ async function inlineRows(dir, files, args, ctx) {
10551
10626
  }
10552
10627
  async function importLocalDirectory(dir, files, args, ctx, labels = {}) {
10553
10628
  const mode = rowsMode(arg.str(args, "mode"));
10629
+ const merge = arg.str(args, "merge") ?? "upsert";
10630
+ if (merge !== "upsert" && merge !== "fill") throw new CliError("--merge is upsert|fill", 1);
10554
10631
  const redact2 = rowsRedact(arg.str(args, "redact"));
10555
10632
  const rows = await inlineRows(dir, files, args, ctx);
10633
+ const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10556
10634
  const { importLocalWorldData: importLocalWorldData2 } = await runtimeData();
10557
10635
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
10636
+ const { BridgeRejected: BridgeRejected2 } = await Promise.resolve().then(() => (init_client(), client_exports));
10558
10637
  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;
10638
+ const report = arg.str(args, "report");
10639
+ try {
10640
+ const imported = await importLocalWorldData2(dir, rows, { mode, ...merge === "fill" ? { merge } : {}, redact: redact2 }, creds);
10641
+ if (report !== void 0) fs27.writeFileSync(report, "");
10642
+ printJson(ctx, {
10643
+ world: dir,
10644
+ ...inputsField(files, labels),
10645
+ rows: count,
10646
+ refusalCount: 0,
10647
+ refusals: [],
10648
+ ...imported,
10649
+ ...imported.entity_counts ? { entityCounts: imported.entity_counts } : {}
10650
+ });
10651
+ return 0;
10652
+ } catch (error) {
10653
+ if (!(error instanceof BridgeRejected2)) throw error;
10654
+ const refusals = refusalsFromBridge(error.detail);
10655
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10656
+ printJson(ctx, { world: dir, ...inputsField(files, labels), rows: count, refusalCount: refusals.length, refusals, entityCounts: {}, changed: false });
10657
+ return 2;
10658
+ }
10561
10659
  }
10562
10660
  async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10563
- const rows = await inlineRows(dir, files, args, ctx);
10661
+ const rows = await inlineRows(dir, files, args, ctx, { cap: false });
10564
10662
  const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10565
10663
  const { checkLocalWorldData: checkLocalWorldData2 } = await runtimeData();
10566
10664
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
@@ -10574,14 +10672,19 @@ async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10574
10672
  return 0;
10575
10673
  } catch (error) {
10576
10674
  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: {} });
10675
+ const refusals = refusalsFromBridge(error.detail);
10676
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10677
+ printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: refusals.length, refusals, entityCounts: {} });
10580
10678
  return 2;
10581
10679
  }
10582
10680
  }
10681
+ function refusalsFromBridge(detail) {
10682
+ if (Array.isArray(detail.refusals) && detail.refusals.length && detail.refusals.every((r) => typeof r === "object" && r !== null))
10683
+ return detail.refusals;
10684
+ return [refusalFromBridge(detail)];
10685
+ }
10583
10686
  function refusalFromBridge(detail) {
10584
- const pointer = detail.path ?? "/";
10687
+ const pointer = detail.path || detail.schema_path || "/";
10585
10688
  const [, entity, index, field] = /^\/([^/]+)(?:\/(\d+))?(?:\/(.+))?$/.exec(pointer) ?? [];
10586
10689
  return {
10587
10690
  chunk: 0,
@@ -12988,7 +13091,7 @@ function registerServeCommand(worlds) {
12988
13091
  worlds.command({
12989
13092
  name: "serve",
12990
13093
  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.",
13094
+ 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
13095
  positionals: [
12993
13096
  {
12994
13097
  name: "path",
@@ -13047,6 +13150,11 @@ function registerServeCommand(worlds) {
13047
13150
  );
13048
13151
  return localModule(argv, local);
13049
13152
  }
13153
+ if (!local && fs35.existsSync(target) && fs35.statSync(target).isDirectory())
13154
+ ctx.stderr(
13155
+ `# ${localRuntimeReason()}
13156
+ # 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).`
13157
+ );
13050
13158
  const creds = resolveCredentials(arg.str(args, "host"));
13051
13159
  const options = {
13052
13160
  host: creds.host,
@@ -13065,7 +13173,7 @@ function registerServeCommand(worlds) {
13065
13173
  ctx.stderr(
13066
13174
  "`worlds serve` runs a local session with the Python runtime; opening a hosted api-surface session instead."
13067
13175
  );
13068
- if (!local) ctx.stderr(`# ${localRuntimeReason()}`);
13176
+ if (!local && !(fs35.existsSync(target) && fs35.statSync(target).isDirectory())) ctx.stderr(`# ${localRuntimeReason()}`);
13069
13177
  let scenario = arg.str(args, "scenario") ?? arg.str(args, "task");
13070
13178
  if (!scenario) {
13071
13179
  const world = await openWorld(slugRef, options);
@@ -13304,6 +13412,11 @@ function parseArgs2(raw, stdin) {
13304
13412
  return value;
13305
13413
  }
13306
13414
  var SERVED_URL = /^https?:\/\//;
13415
+ function settleStatus(report) {
13416
+ const code = report.result.status;
13417
+ report.status = code >= 200 && code < 300 ? "ok" : code >= 500 ? "error" : "refused";
13418
+ return report;
13419
+ }
13307
13420
  async function sessionVerb(base, verb, body) {
13308
13421
  let response;
13309
13422
  try {
@@ -13348,7 +13461,7 @@ async function callServed(base, tool, args, wants) {
13348
13461
  if (closed.status !== 200) throw new CliError(`POST /__session/close answered ${closed.status}`, 1);
13349
13462
  report.closed = true;
13350
13463
  }
13351
- return report;
13464
+ return settleStatus(report);
13352
13465
  }
13353
13466
  function registerCallCommand(worlds) {
13354
13467
  worlds.command({
@@ -13367,7 +13480,7 @@ function registerCallCommand(worlds) {
13367
13480
  { name: "scenario", help: "Start in one of the world's scenarios (default: the base state)." },
13368
13481
  {
13369
13482
  name: "seed",
13370
- help: "Seed rows before the call, the host's shape: JSON {rows: {entity: [row, ...]}, mode?: append|replace}, @file, or -."
13483
+ 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
13484
  },
13372
13485
  { name: "state", help: "Print the world's state after the call.", boolean: true },
13373
13486
  { name: "grade", help: "Run the verifiers after the call and print the scores.", boolean: true },
@@ -13421,7 +13534,7 @@ function registerCallCommand(worlds) {
13421
13534
  );
13422
13535
  const detail = detailFrom(payload);
13423
13536
  if (detail) throw new BridgeRejected(detail);
13424
- const report = payload;
13537
+ const report = settleStatus(payload);
13425
13538
  ctx.stdout(JSON.stringify(report, null, 2));
13426
13539
  return report.result.status >= 200 && report.result.status < 300 ? 0 : 1;
13427
13540
  }
@@ -13586,6 +13699,38 @@ function declaredOperationNames(toml) {
13586
13699
  }
13587
13700
  return names;
13588
13701
  }
13702
+ function declaredRoutes(toml) {
13703
+ const routes = [];
13704
+ let current = null;
13705
+ for (const raw of toml.split("\n")) {
13706
+ const line = raw.trim();
13707
+ if (line.startsWith("[")) {
13708
+ current = line === "[[operations]]" ? { name: "", methods: [], path: "", params: [] } : null;
13709
+ if (current) routes.push(current);
13710
+ continue;
13711
+ }
13712
+ if (!current) continue;
13713
+ const str2 = (key) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`).exec(line)?.[1];
13714
+ const list = (key) => {
13715
+ const m = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`).exec(line);
13716
+ return m ? [...m[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]) : void 0;
13717
+ };
13718
+ const name = str2("name");
13719
+ if (name !== void 0) current.name = name;
13720
+ const routePath = str2("path");
13721
+ if (routePath !== void 0) current.path = routePath;
13722
+ const method = str2("method");
13723
+ if (method !== void 0 && !current.methods.includes(method.toUpperCase())) current.methods.push(method.toUpperCase());
13724
+ const methods = list("methods");
13725
+ if (methods) {
13726
+ for (const m of methods) if (!current.methods.includes(m.toUpperCase())) current.methods.push(m.toUpperCase());
13727
+ }
13728
+ const params = list("params");
13729
+ if (params) current.params = params;
13730
+ }
13731
+ for (const route of routes) if (!route.methods.length) route.methods.push("GET");
13732
+ return routes;
13733
+ }
13589
13734
  function removeRoute(toml, name) {
13590
13735
  const lines = toml.split("\n");
13591
13736
  const kept = [];
@@ -13647,6 +13792,16 @@ function addRoute(toml, spec, declaredEntities2, options = {}) {
13647
13792
  throw new CliError("--handler only applies with --action handler");
13648
13793
  if (spec.api.status !== void 0 && (spec.api.status < 200 || spec.api.status > 299))
13649
13794
  throw new CliError("--status must be a 2xx");
13795
+ if (spec.api.action !== void 0 && ["create", "update", "delete"].includes(spec.api.action) && spec.method === "GET")
13796
+ throw new CliError(
13797
+ `--action ${spec.api.action} writes, but --method GET reads; pass --method ${spec.api.action === "create" ? "POST" : spec.api.action === "update" ? "PATCH" : "DELETE"}`
13798
+ );
13799
+ const sameParams = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
13800
+ for (const route of declaredRoutes(toml))
13801
+ if (route.name !== spec.name && route.path === spec.path && route.methods.includes(spec.method) && sameParams(route.params, spec.params))
13802
+ throw new CliError(
13803
+ `${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`
13804
+ );
13650
13805
  if (spec.entity !== void 0 && declaredEntities2 && !declaredEntities2.includes(spec.entity))
13651
13806
  throw new CliError(
13652
13807
  `Entity ${spec.entity} is not declared in schema/world.json (have: ${declaredEntities2.join(", ") || "none"}); run \`gateway worlds schema entity add\` first`
@@ -13779,18 +13934,43 @@ var assertManifest = (toml) => {
13779
13934
  if (!/^\s*\[(environment|env)\]\s*$/m.test(toml))
13780
13935
  throw new CliError("gateway-env.toml has no [environment] table; it is not a schema world manifest");
13781
13936
  };
13782
- function addDependency(toml, spec, depServes) {
13937
+ function removeDependency(toml, alias) {
13938
+ const kept = [];
13939
+ let dropping = false;
13940
+ for (const raw of toml.split("\n")) {
13941
+ const line = raw.trim();
13942
+ if (line.startsWith("[")) dropping = line === `[dependencies.${alias}]` || line.startsWith(`[dependencies.${alias}.`);
13943
+ if (!dropping) kept.push(raw);
13944
+ }
13945
+ while (kept.length && kept[kept.length - 1].trim() === "") kept.pop();
13946
+ return kept.join("\n") + "\n";
13947
+ }
13948
+ function dependencyServes(depDir) {
13949
+ const manifest = path29.join(depDir, "gateway-env.toml");
13950
+ if (!fs38.existsSync(manifest)) return void 0;
13951
+ const tools = manifestServedTools(fs38.readFileSync(manifest, "utf8"));
13952
+ const connector = path29.join(depDir, "connector.toml");
13953
+ const routes = fs38.existsSync(connector) ? declaredRoutes(fs38.readFileSync(connector, "utf8")).map((r) => r.name).filter(Boolean) : [];
13954
+ return tools === void 0 ? void 0 : { tools, routes };
13955
+ }
13956
+ function addDependency(toml, spec, depServes, opts = {}) {
13783
13957
  assertManifest(toml);
13784
13958
  if (!ALIAS.test(spec.alias))
13785
13959
  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`);
13960
+ if (declaredAliases(toml).includes(spec.alias)) {
13961
+ if (!opts.replace)
13962
+ throw new CliError(`[dependencies.${spec.alias}] is already declared; pass --replace to redeclare it (pin, path, tools, task, map)`);
13963
+ toml = removeDependency(toml, spec.alias);
13964
+ }
13788
13965
  if (!PIN.test(spec.pin)) throw new CliError(`--pin is <slug>@<ref>, got ${JSON.stringify(spec.pin)}`);
13789
13966
  if (path29.isAbsolute(spec.path)) throw new CliError("The dependency path is stored relative to the world");
13790
13967
  if (depServes) {
13968
+ const serves = Array.isArray(depServes) ? { tools: depServes, routes: [] } : depServes;
13791
13969
  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"}`);
13970
+ if (!serves.tools.includes(tool))
13971
+ throw new CliError(
13972
+ 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)` : "")
13973
+ );
13794
13974
  }
13795
13975
  const body = toml.endsWith("\n") ? toml : toml + "\n";
13796
13976
  return body + "\n" + renderDependency(spec);
@@ -13806,7 +13986,9 @@ function addTask(toml, spec, known = {}) {
13806
13986
  if (known.verifiers) {
13807
13987
  for (const v of spec.verifiers)
13808
13988
  if (!known.verifiers.includes(v))
13809
- throw new CliError(`verifiers/${v}.sql does not exist (have: ${known.verifiers.join(", ") || "none"})`);
13989
+ throw new CliError(
13990
+ `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`
13991
+ );
13810
13992
  }
13811
13993
  const aliases = declaredAliases(toml);
13812
13994
  for (const [alias, names] of Object.entries(spec.worlds)) {
@@ -13868,8 +14050,10 @@ function declaredEntities(dir) {
13868
14050
  var WORLD_SLUG = /^[a-z0-9][a-z0-9-]*$/;
13869
14051
  function connectorTomlSkeleton(dir) {
13870
14052
  const manifest = path29.join(dir, "gateway-env.toml");
14053
+ if (!fs38.existsSync(dir))
14054
+ throw new CliError(`${dir} does not exist; run \`gateway worlds schema init ${dir} --connector custom\` to start a world there`, 1);
13871
14055
  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);
14056
+ 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
14057
  const name = /^\s*name\s*=\s*"([^"]*)"/m.exec(fs38.readFileSync(manifest, "utf8"))?.[1];
13874
14058
  const slug = name && WORLD_SLUG.test(name) ? name : path29.basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "world";
13875
14059
  return [
@@ -13888,6 +14072,26 @@ function scaffoldVerifier(entity) {
13888
14072
  SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
13889
14073
  `;
13890
14074
  }
14075
+ function verifierSql(name, entity, where) {
14076
+ 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)}`);
14077
+ 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)}`);
14078
+ if (where === void 0) return scaffoldVerifier(entity);
14079
+ const clause = where.trim();
14080
+ if (!clause) throw new CliError("--where is a SQL condition over the entity's columns; it cannot be empty");
14081
+ return `-- ${name}: scores 1.0 once a ${entity} row satisfies the condition; edit for real tasks.
14082
+ -- A verifier is one SQL statement returning one number in 0..1 (0.5 is partial credit).
14083
+ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}" WHERE ${clause};
14084
+ `;
14085
+ }
14086
+ function addVerifier(dir, name, entity, where) {
14087
+ const sql = verifierSql(name, entity, where);
14088
+ const file = path29.join(dir, "verifiers", `${name}.sql`);
14089
+ if (fs38.existsSync(file))
14090
+ throw new CliError(`verifiers/${name}.sql already exists (have: ${(verifierNames2(dir) ?? []).join(", ")}); edit it, or pick another name`);
14091
+ fs38.mkdirSync(path29.dirname(file), { recursive: true });
14092
+ fs38.writeFileSync(file, sql);
14093
+ return file;
14094
+ }
13891
14095
  function repointScaffoldVerifier(dir, entity, declared) {
13892
14096
  const file = path29.join(dir, "verifiers", "state_present.sql");
13893
14097
  if (!fs38.existsSync(file)) return null;
@@ -13931,7 +14135,7 @@ function registerScaffoldCommands(worlds) {
13931
14135
  repeat: true
13932
14136
  }
13933
14137
  ],
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.",
14138
+ 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
14139
  run: async (args, ctx) => {
13936
14140
  const dir = path29.resolve(args.positionals[0]);
13937
14141
  const file = path29.join(dir, "schema", "world.json");
@@ -13969,6 +14173,43 @@ function registerScaffoldCommands(worlds) {
13969
14173
  ctx.stdout(JSON.stringify(out, null, 2));
13970
14174
  }
13971
14175
  });
14176
+ schema.group("verifier", "Write verifiers/<name>.sql: the SQL that grades a task on the world's end state.").command({
14177
+ name: "add",
14178
+ help: "Scaffold one verifier: a SQL statement over an entity's table returning 1.0 when a row satisfies --where (or any row exists).",
14179
+ positionals: [
14180
+ { name: "path", help: "World directory holding schema/world.json" },
14181
+ { name: "name", help: "Verifier name, e.g. case_opened; what `schema task add --verifier` takes" }
14182
+ ],
14183
+ flags: [
14184
+ { name: "entity", help: "Entity whose table the verifier counts (from schema/world.json).", short: "e" },
14185
+ { 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" }
14186
+ ],
14187
+ 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.",
14188
+ run: async (args, ctx) => {
14189
+ const dir = path29.resolve(args.positionals[0]);
14190
+ const name = args.positionals[1];
14191
+ const entity = arg.str(args, "entity");
14192
+ const declared = declaredEntities(dir);
14193
+ if (declared === void 0) throw new CliError(`${dir} has no schema/world.json; run \`gateway worlds schema init ${args.positionals[0]} --connector custom\` first`);
14194
+ if (!entity) throw new CliError(`--entity is required: one of ${declared.join(", ") || "(declare one with `gateway worlds schema entity add` first)"}`);
14195
+ if (!declared.includes(entity)) throw new CliError(`Unknown entity ${entity}; the world has ${declared.join(", ") || "none"}`);
14196
+ const file = addVerifier(dir, name, entity, arg.str(args, "where"));
14197
+ const rel = path29.relative(process.cwd(), dir) || ".";
14198
+ ctx.stdout(
14199
+ JSON.stringify(
14200
+ {
14201
+ status: "ok",
14202
+ verifier: name,
14203
+ entity,
14204
+ file: path29.relative(process.cwd(), file) || file,
14205
+ next: `gateway worlds schema task add ${rel} <task_id> --prompt "<what the agent is told>" --verifier ${name}`
14206
+ },
14207
+ null,
14208
+ 2
14209
+ )
14210
+ );
14211
+ }
14212
+ });
13972
14213
  schema.command({
13973
14214
  name: "link",
13974
14215
  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 +14223,12 @@ function registerScaffoldCommands(worlds) {
13982
14223
  ],
13983
14224
  flags: [
13984
14225
  { 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 },
14226
+ {
14227
+ name: "tools",
14228
+ help: "Dependency tools (its [tools] serve, not its routes) to serve as <alias>.<tool>; comma-separated or repeatable. Default: every tool it has.",
14229
+ repeat: true
14230
+ },
14231
+ { name: "replace", help: "Redeclare an alias already linked (pin, path, tools, task, map rewritten).", boolean: true },
13986
14232
  { name: "task", help: "Scenario the dependency starts in: scenarios/<name>/ of its tree (the shipped templates have `default`)." },
13987
14233
  {
13988
14234
  name: "map",
@@ -14023,7 +14269,7 @@ function registerScaffoldCommands(worlds) {
14023
14269
  tools: arg.list(args, "tools").flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean),
14024
14270
  entities: arg.list(args, "map").map(parseEntityMap)
14025
14271
  };
14026
- const updated = addDependency(toml, spec, manifestServedTools(depToml));
14272
+ const updated = addDependency(toml, spec, dependencyServes(depDir), { replace: arg.bool(args, "replace") });
14027
14273
  fs38.writeFileSync(file, updated);
14028
14274
  ctx.stdout(
14029
14275
  JSON.stringify(
@@ -14092,7 +14338,11 @@ function registerScaffoldCommands(worlds) {
14092
14338
  worlds: worlds2,
14093
14339
  rewards: [...spec.verifiers, ...Object.entries(worlds2).flatMap(([a, names]) => names.map((n) => `${a}/${n}`))],
14094
14340
  file: path29.relative(process.cwd(), file) || file,
14095
- next: `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14341
+ next: [
14342
+ `gateway worlds schema compile ${path29.relative(process.cwd(), dir) || "."} # a manifest edit invalidates the compiled contract`,
14343
+ `gateway worlds schema check ${path29.relative(process.cwd(), dir) || "."}`,
14344
+ `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14345
+ ]
14096
14346
  },
14097
14347
  null,
14098
14348
  2
@@ -14231,7 +14481,7 @@ function buildCli() {
14231
14481
  "schema",
14232
14482
  "Compile and check gateway-world/1 contracts (the runtime runs on the platform)."
14233
14483
  );
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.";
14484
+ 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
14485
  worlds.group(
14236
14486
  "connector",
14237
14487
  "Vendor connections: validate, capture, conform, ingest, publish, clone."