@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.js CHANGED
@@ -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) {
@@ -4944,14 +4949,15 @@ function initNextSteps(dir, shape) {
4944
4949
  );
4945
4950
  if (shape.blank)
4946
4951
  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}`
4952
+ `gateway worlds schema verifier add ${dir} <verifier> --entity <entity> --where "<sql condition>" # SQL that grades the end state; state_present.sql is the placeholder`,
4953
+ `gateway worlds schema task add ${dir} <task_id> --prompt "<what the agent is told>" --verifier <verifier>`
4949
4954
  );
4950
4955
  steps.push(
4956
+ `gateway worlds schema compile ${dir} # after any edit to schema/, connector.toml or gateway-env.toml`,
4951
4957
  `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}`
4958
+ `gateway worlds data import ${dir} <rows.json> # {"<entity>": [row, ...]}`,
4959
+ `gateway worlds serve ${dir} # then: gateway worlds call http://127.0.0.1:<port> <tool> --args '{...}'`,
4960
+ `gateway worlds create <slug> --from ${dir} # publish last`
4955
4961
  );
4956
4962
  return steps;
4957
4963
  }
@@ -5208,7 +5214,7 @@ function registerSchemaCommands(schema) {
5208
5214
  for (const [command2, help] of [
5209
5215
  [
5210
5216
  "compile",
5211
- "Compile the world's contract on the platform and write back what the compiler produced."
5217
+ "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
5218
  ],
5213
5219
  [
5214
5220
  "check",
@@ -6749,6 +6755,9 @@ function harborRunPlan(dir, taskId, logsDir = LOGS_PLACEHOLDER) {
6749
6755
  validation
6750
6756
  };
6751
6757
  }
6758
+ function notGraded(step, status) {
6759
+ 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`;
6760
+ }
6752
6761
  function dockerBin() {
6753
6762
  return process.env.GATEWAY_DOCKER || "docker";
6754
6763
  }
@@ -6780,10 +6789,12 @@ function dryRunHarbor(dir, plan) {
6780
6789
  };
6781
6790
  const image = plan.image.dockerfile ? plan.image.tag : plan.image.ref;
6782
6791
  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" };
6792
+ const buildStatus = plan.commands.build ? spawnArgv(plan.commands.build, 20 * 6e4) : 0;
6793
+ if (buildStatus !== 0)
6794
+ return { executed: true, docker: docker.version, image, exitCode: buildStatus, output: outputs.join("\n"), commands, reason: notGraded("docker build", buildStatus) };
6795
+ const pullStatus = plan.commands.pull ? spawnArgv(plan.commands.pull, 20 * 6e4) : 0;
6796
+ if (pullStatus !== 0)
6797
+ return { executed: true, docker: docker.version, image, exitCode: pullStatus, output: outputs.join("\n"), commands, reason: notGraded("docker pull", pullStatus) };
6787
6798
  const run = plan.commands.run.map((a) => a.replace(`${LOGS_PLACEHOLDER}:/logs`, `${logs}:/logs`));
6788
6799
  const exitCode = spawnArgv(run, (plan.timeouts.agent + plan.timeouts.verifier) * 1e3);
6789
6800
  const rewards = readReward(path10.join(logs, "verifier"));
@@ -6904,7 +6915,8 @@ function dryRunVerifiers(dir, plan, opts) {
6904
6915
  };
6905
6916
  commands.push(`${shellLine(plan.commands.build)} # Dockerfile on stdin: ${JSON.stringify(plan.image.dockerfile)}`);
6906
6917
  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 ?? "")) };
6918
+ if (built.status !== 0)
6919
+ return { executed: true, exitCode: built.status ?? 1, reason: notGraded("docker build", built.status ?? 1), commands, output: tail2((built.stdout ?? "") + (built.stderr ?? "")) };
6908
6920
  commands.push(shellLine(plan.commands.run));
6909
6921
  const ran = (0, import_node_child_process3.spawnSync)(plan.commands.run[0], plan.commands.run.slice(1), { encoding: "utf8", timeout: 5 * 6e4 });
6910
6922
  return { ...discoverResult(readDiscover(ran.stdout ?? ""), `${plan.image.tag} (Docker ${docker.version})`, ran.stderr ?? "", commands), docker: docker.version, image: plan.image.tag };
@@ -8052,8 +8064,9 @@ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
8052
8064
  if (arg.bool(args, "json")) printJson(ctx, { plan: plan2, result: result2 });
8053
8065
  else printDryRun(ctx, plan2, result2);
8054
8066
  if (invalid) return 2;
8067
+ if (result2.executed && result2.reward === void 0) return 2;
8055
8068
  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`);
8069
+ ctx.stderr(result2.reward === null ? "ungraded: the grader ran but wrote no reward" : `the reference solution scored ${result2.reward}, not 1.0`);
8057
8070
  return 2;
8058
8071
  }
8059
8072
  return 0;
@@ -8837,17 +8850,23 @@ async function extractRows(input, config, opts, out) {
8837
8850
  const keys = entity.primaryKey;
8838
8851
  const summary2 = { read: 0, rows: 0, unknownFields: {}, redacted: { dropped: 0, hashed: 0 } };
8839
8852
  const held = /* @__PURE__ */ new Map();
8853
+ const skipped = {};
8854
+ const skip = (reason) => {
8855
+ skipped[reason] = (skipped[reason] ?? 0) + 1;
8856
+ };
8840
8857
  const take = (raw) => {
8841
8858
  summary2.read++;
8842
8859
  const row = clean(raw, entity.fields, summary2);
8843
- if (!keys.every((name) => row.has(name))) return;
8860
+ if (!keys.every((name) => row.has(name))) return skip(`row lacks the primary key (${keys.join(", ")})`);
8844
8861
  const key = dumps(keys.map((name) => row.get(name)));
8845
8862
  const existing = held.get(key);
8846
8863
  if (!existing) held.set(key, row);
8847
8864
  else if (opts.merge === "upsert") held.set(key, row);
8848
8865
  else for (const [name, value] of row) if (!existing.has(name)) existing.set(name, value);
8849
8866
  };
8850
- await adapters[opts.shape](input, config, keys, take);
8867
+ await adapters[opts.shape](input, config, keys, take, skip);
8868
+ if (Object.keys(skipped).length) summary2.skipped = skipped;
8869
+ if (summary2.read === 0 && Object.keys(skipped).length) summary2.hint = SHAPE_HINT[opts.shape];
8851
8870
  const policy = opts.redact ? config.redact : null;
8852
8871
  for (const row of held.values()) {
8853
8872
  let final = row;
@@ -8882,14 +8901,30 @@ function countRedaction(before, after, policy, summary2) {
8882
8901
  else if (policy.hash.includes(name) && value !== null) summary2.redacted.hashed++;
8883
8902
  }
8884
8903
  }
8885
- var toolResults = async (input, _config, keys, take) => {
8904
+ var SHAPE_HINT = {
8905
+ "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',
8906
+ "vendor-envelope": "vendor-envelope reads the vendor's own response: a bare array, or an object whose [api].envelope key holds the rows",
8907
+ "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'
8908
+ };
8909
+ var toolResults = async (input, _config, keys, take, skip) => {
8886
8910
  for await (const record of records(input)) {
8887
- if (!isObject(record)) continue;
8911
+ if (!isObject(record)) {
8912
+ skip("line is not a JSON object");
8913
+ continue;
8914
+ }
8888
8915
  const raw = record.get("raw_output");
8889
- if (!isObject(raw)) continue;
8916
+ if (!isObject(raw)) {
8917
+ skip("record has no raw_output object");
8918
+ continue;
8919
+ }
8890
8920
  let listed = raw.get("results");
8891
8921
  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);
8922
+ const items = objects(listed);
8923
+ if (items.length === 0) skip("raw_output has no results[] or items[]");
8924
+ for (const item of items) {
8925
+ if (keys.every((name) => item.has(name))) take(item);
8926
+ else skip(`row lacks the primary key (${keys.join(", ")})`);
8927
+ }
8893
8928
  }
8894
8929
  };
8895
8930
  var vendorEnvelope = async (input, config, _keys, take) => {
@@ -8928,13 +8963,21 @@ var vendorEnvelope = async (input, config, _keys, take) => {
8928
8963
  }
8929
8964
  for (const row of objects(dig(document, envelope))) take(row);
8930
8965
  };
8931
- var sessionExport = async (input, config, _keys, take) => {
8966
+ var sessionExport = async (input, config, _keys, take, skip) => {
8932
8967
  for await (const record of records(input)) {
8933
- if (!isObject(record) || record.get("kind") !== "call") continue;
8968
+ if (!isObject(record) || record.get("kind") !== "call") {
8969
+ skip('record is not {"kind": "call", ...}');
8970
+ continue;
8971
+ }
8934
8972
  const error = record.get("error");
8935
- if (error !== null && error !== void 0) continue;
8973
+ if (error !== null && error !== void 0) {
8974
+ skip("call record carries an error");
8975
+ continue;
8976
+ }
8936
8977
  const result = record.get("result") ?? null;
8937
- for (const row of objects(config.envelope ? dig(result, config.envelope) : result)) take(row);
8978
+ const rows = objects(config.envelope ? dig(result, config.envelope) : result);
8979
+ if (rows.length === 0) skip(config.envelope ? `result.${config.envelope} holds no rows` : "result is not an array of rows");
8980
+ for (const row of rows) take(row);
8938
8981
  }
8939
8982
  };
8940
8983
  var adapters = {
@@ -9278,6 +9321,13 @@ function skeleton(records2, entities, kind, opts = {}) {
9278
9321
  let select = kind === "tool-call" ? "result" : "$record";
9279
9322
  const shapeNames = Object.keys(group.shapes);
9280
9323
  if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an array of objects")) select = "result[*]";
9324
+ else if (kind === "tool-call" && shapeNames.length && shapeNames.every((shape) => shape === "an object")) {
9325
+ const listed = Object.entries(group.fields).filter(([, info]) => info.list && Object.keys(info.nested).length).map(([name2]) => name2);
9326
+ if (listed.length === 1) {
9327
+ select = `result.${listed[0]}[*]`;
9328
+ lines.push(`# result.${listed[0]} holds the rows: [*] selects each item of an array`);
9329
+ }
9330
+ }
9281
9331
  lines.push("[[sources]]", `name = "${name}"`, `kind = "${kind}"`, `select = "${select}"`);
9282
9332
  lines.push(chosen ? `entity = "${chosen}"` : `entity = "" # one of: ${names.join(", ")}`);
9283
9333
  lines.push("[sources.fields]");
@@ -9770,7 +9820,7 @@ var ENTITY_FLAG = { name: "entity", help: "The entity bare-row files hold." };
9770
9820
  var REPORT_FLAG = { name: "report", help: "Write the refusals as JSONL here." };
9771
9821
  var MESSAGE_FLAG = { name: "message", short: "m", help: "Change reason for the version." };
9772
9822
  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");
9823
+ 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
9824
  data.command({
9775
9825
  name: "import",
9776
9826
  help: "Put rows into a world through its own gate.",
@@ -9933,7 +9983,7 @@ primary key, the world's [redact] policy applied. Summary on stderr:
9933
9983
  { name: "session", help: "With --from traces: every trace of this session (GET /api/public/sessions/{id}?includeIO=true)." },
9934
9984
  { name: "since", help: "With --from traces: only calls that started at or after this ISO time." },
9935
9985
  { 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." },
9986
+ { 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
9987
  { name: "out", help: "With map init: where the skeleton goes (default ingest.toml in the world, or stdout for a slug)." },
9938
9988
  { name: "mode", help: "append (upsert by primary key) | replace (named entities).", default: "append" },
9939
9989
  REDACT_FLAG,
@@ -10366,7 +10416,8 @@ async function mapInitCommand(world, samples, args, ctx) {
10366
10416
  }
10367
10417
  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
10418
  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\``);
10419
+ const fromFlag = from === "tool-calls" ? "" : ` --from ${from}`;
10420
+ 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
10421
  return 0;
10371
10422
  }
10372
10423
  async function ingestCommand(world, inputs, args, ctx, labels = {}) {
@@ -10392,7 +10443,12 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10392
10443
  if (local) return dryRun ? checkLocalDirectory(world, inputs, args, ctx, labels) : importLocalDirectory(world, inputs, args, ctx, labels);
10393
10444
  return importBatch(world, inputs, args, ctx, dryRun ? "check" : "import", void 0, labels);
10394
10445
  }
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");
10446
+ const bareCsv = from === "csv" && transform === void 0 && mapFile === void 0 && !(local && worldMapping(world));
10447
+ const csvEntity = bareCsv ? arg.str(args, "entity") : void 0;
10448
+ if (bareCsv && csvEntity === void 0)
10449
+ throw new CliError(
10450
+ "--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"
10451
+ );
10396
10452
  const mapText = mapFile !== void 0 ? readMapping(mapFile) : void 0;
10397
10453
  const { toolCallsFromObservations: toolCallsFromObservations2 } = await Promise.resolve().then(() => (init_ingest(), ingest_exports));
10398
10454
  const dir = local ? world : await pullWorld(world, credentials(args));
@@ -10430,7 +10486,23 @@ async function ingestCommand(world, inputs, args, ctx, labels = {}) {
10430
10486
  const runtimeCreds = credentialsForRuntime2(arg.str(args, "host"));
10431
10487
  let projected = {};
10432
10488
  try {
10433
- if (transform !== void 0) {
10489
+ if (csvEntity !== void 0) {
10490
+ projected = { [csvEntity]: records2.filter((r) => typeof r === "object" && r !== null) };
10491
+ const landed = local && !dryRun ? await importLocalWorldData2(dir, projected, { mode, redact: redact2 }, runtimeCreds) : await checkLocalWorldData2(dir, projected, runtimeCreds, local ? { redact: redact2 } : {});
10492
+ Object.assign(out, {
10493
+ via: "rows",
10494
+ records: records2.length,
10495
+ ingested: records2.length,
10496
+ skipped: {},
10497
+ refusals: [],
10498
+ rows: { [csvEntity]: projected[csvEntity].length },
10499
+ dryRun,
10500
+ redact: redact2,
10501
+ changed: local && !dryRun ? landed.changed : false,
10502
+ kind: landed.kind,
10503
+ entityCounts: landed.entity_counts
10504
+ });
10505
+ } else if (transform !== void 0) {
10434
10506
  const ran = await runTransform(transform, records2, { timeoutMs: timeoutSeconds * 1e3 });
10435
10507
  for (const line of ran.stderr.split("\n")) if (line.trim()) ctx.stderr(`transform: ${line}`);
10436
10508
  projected = ran.rows;
@@ -10533,10 +10605,11 @@ function worldSlug(dir) {
10533
10605
  const slug = readLocalMeta(dir)?.slug;
10534
10606
  return typeof slug === "string" && slug ? slug : path21.basename(path21.resolve(dir));
10535
10607
  }
10536
- async function inlineRows(dir, files, args, ctx) {
10608
+ async function inlineRows(dir, files, args, ctx, opts = {}) {
10537
10609
  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)}\``,
10610
+ const capped = opts.cap ?? true;
10611
+ const tooLarge = (what) => new CliError(
10612
+ `${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
10613
  1
10541
10614
  );
10542
10615
  const paths = [];
@@ -10555,9 +10628,11 @@ async function inlineRows(dir, files, args, ctx) {
10555
10628
  size += fs27.statSync(file).size;
10556
10629
  paths.push(file);
10557
10630
  }
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();
10631
+ if (capped) {
10632
+ if (size > INLINE_BYTES) throw tooLarge(`${size} bytes`);
10633
+ let count = 0;
10634
+ for await (const _ of readRows(paths.map(fileInput), entity)) if (++count > INLINE_ROWS) throw tooLarge(`more than ${INLINE_ROWS} rows`);
10635
+ }
10561
10636
  return parseRows(paths, entity);
10562
10637
  } finally {
10563
10638
  if (scratch) fs27.rmSync(scratch, { recursive: true, force: true });
@@ -10565,16 +10640,39 @@ async function inlineRows(dir, files, args, ctx) {
10565
10640
  }
10566
10641
  async function importLocalDirectory(dir, files, args, ctx, labels = {}) {
10567
10642
  const mode = rowsMode(arg.str(args, "mode"));
10643
+ const merge = arg.str(args, "merge") ?? "upsert";
10644
+ if (merge !== "upsert" && merge !== "fill") throw new CliError("--merge is upsert|fill", 1);
10568
10645
  const redact2 = rowsRedact(arg.str(args, "redact"));
10569
10646
  const rows = await inlineRows(dir, files, args, ctx);
10647
+ const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10570
10648
  const { importLocalWorldData: importLocalWorldData2 } = await runtimeData();
10571
10649
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
10650
+ const { BridgeRejected: BridgeRejected2 } = await Promise.resolve().then(() => (init_client(), client_exports));
10572
10651
  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;
10652
+ const report = arg.str(args, "report");
10653
+ try {
10654
+ const imported = await importLocalWorldData2(dir, rows, { mode, ...merge === "fill" ? { merge } : {}, redact: redact2 }, creds);
10655
+ if (report !== void 0) fs27.writeFileSync(report, "");
10656
+ printJson(ctx, {
10657
+ world: dir,
10658
+ ...inputsField(files, labels),
10659
+ rows: count,
10660
+ refusalCount: 0,
10661
+ refusals: [],
10662
+ ...imported,
10663
+ ...imported.entity_counts ? { entityCounts: imported.entity_counts } : {}
10664
+ });
10665
+ return 0;
10666
+ } catch (error) {
10667
+ if (!(error instanceof BridgeRejected2)) throw error;
10668
+ const refusals = refusalsFromBridge(error.detail);
10669
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10670
+ printJson(ctx, { world: dir, ...inputsField(files, labels), rows: count, refusalCount: refusals.length, refusals, entityCounts: {}, changed: false });
10671
+ return 2;
10672
+ }
10575
10673
  }
10576
10674
  async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10577
- const rows = await inlineRows(dir, files, args, ctx);
10675
+ const rows = await inlineRows(dir, files, args, ctx, { cap: false });
10578
10676
  const count = Object.values(rows).reduce((n, listed) => n + listed.length, 0);
10579
10677
  const { checkLocalWorldData: checkLocalWorldData2 } = await runtimeData();
10580
10678
  const { credentialsForRuntime: credentialsForRuntime2 } = await Promise.resolve().then(() => (init_local(), local_exports));
@@ -10588,14 +10686,19 @@ async function checkLocalDirectory(dir, files, args, ctx, labels = {}) {
10588
10686
  return 0;
10589
10687
  } catch (error) {
10590
10688
  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: {} });
10689
+ const refusals = refusalsFromBridge(error.detail);
10690
+ if (report !== void 0) fs27.writeFileSync(report, refusals.map((r) => JSON.stringify(r) + "\n").join(""));
10691
+ printJson(ctx, { world: dir, ...inputsField(files, labels), dryRun: true, rows: count, refusalCount: refusals.length, refusals, entityCounts: {} });
10594
10692
  return 2;
10595
10693
  }
10596
10694
  }
10695
+ function refusalsFromBridge(detail) {
10696
+ if (Array.isArray(detail.refusals) && detail.refusals.length && detail.refusals.every((r) => typeof r === "object" && r !== null))
10697
+ return detail.refusals;
10698
+ return [refusalFromBridge(detail)];
10699
+ }
10597
10700
  function refusalFromBridge(detail) {
10598
- const pointer = detail.path ?? "/";
10701
+ const pointer = detail.path || detail.schema_path || "/";
10599
10702
  const [, entity, index, field] = /^\/([^/]+)(?:\/(\d+))?(?:\/(.+))?$/.exec(pointer) ?? [];
10600
10703
  return {
10601
10704
  chunk: 0,
@@ -13002,7 +13105,7 @@ function registerServeCommand(worlds) {
13002
13105
  worlds.command({
13003
13106
  name: "serve",
13004
13107
  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.",
13108
+ 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
13109
  positionals: [
13007
13110
  {
13008
13111
  name: "path",
@@ -13061,6 +13164,11 @@ function registerServeCommand(worlds) {
13061
13164
  );
13062
13165
  return localModule(argv, local);
13063
13166
  }
13167
+ if (!local && fs35.existsSync(target) && fs35.statSync(target).isDirectory())
13168
+ ctx.stderr(
13169
+ `# ${localRuntimeReason()}
13170
+ # 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).`
13171
+ );
13064
13172
  const creds = resolveCredentials(arg.str(args, "host"));
13065
13173
  const options = {
13066
13174
  host: creds.host,
@@ -13079,7 +13187,7 @@ function registerServeCommand(worlds) {
13079
13187
  ctx.stderr(
13080
13188
  "`worlds serve` runs a local session with the Python runtime; opening a hosted api-surface session instead."
13081
13189
  );
13082
- if (!local) ctx.stderr(`# ${localRuntimeReason()}`);
13190
+ if (!local && !(fs35.existsSync(target) && fs35.statSync(target).isDirectory())) ctx.stderr(`# ${localRuntimeReason()}`);
13083
13191
  let scenario = arg.str(args, "scenario") ?? arg.str(args, "task");
13084
13192
  if (!scenario) {
13085
13193
  const world = await openWorld(slugRef, options);
@@ -13318,6 +13426,11 @@ function parseArgs2(raw, stdin) {
13318
13426
  return value;
13319
13427
  }
13320
13428
  var SERVED_URL = /^https?:\/\//;
13429
+ function settleStatus(report) {
13430
+ const code = report.result.status;
13431
+ report.status = code >= 200 && code < 300 ? "ok" : code >= 500 ? "error" : "refused";
13432
+ return report;
13433
+ }
13321
13434
  async function sessionVerb(base, verb, body) {
13322
13435
  let response;
13323
13436
  try {
@@ -13362,7 +13475,7 @@ async function callServed(base, tool, args, wants) {
13362
13475
  if (closed.status !== 200) throw new CliError(`POST /__session/close answered ${closed.status}`, 1);
13363
13476
  report.closed = true;
13364
13477
  }
13365
- return report;
13478
+ return settleStatus(report);
13366
13479
  }
13367
13480
  function registerCallCommand(worlds) {
13368
13481
  worlds.command({
@@ -13381,7 +13494,7 @@ function registerCallCommand(worlds) {
13381
13494
  { name: "scenario", help: "Start in one of the world's scenarios (default: the base state)." },
13382
13495
  {
13383
13496
  name: "seed",
13384
- help: "Seed rows before the call, the host's shape: JSON {rows: {entity: [row, ...]}, mode?: append|replace}, @file, or -."
13497
+ 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
13498
  },
13386
13499
  { name: "state", help: "Print the world's state after the call.", boolean: true },
13387
13500
  { name: "grade", help: "Run the verifiers after the call and print the scores.", boolean: true },
@@ -13435,7 +13548,7 @@ function registerCallCommand(worlds) {
13435
13548
  );
13436
13549
  const detail = detailFrom(payload);
13437
13550
  if (detail) throw new BridgeRejected(detail);
13438
- const report = payload;
13551
+ const report = settleStatus(payload);
13439
13552
  ctx.stdout(JSON.stringify(report, null, 2));
13440
13553
  return report.result.status >= 200 && report.result.status < 300 ? 0 : 1;
13441
13554
  }
@@ -13600,6 +13713,38 @@ function declaredOperationNames(toml) {
13600
13713
  }
13601
13714
  return names;
13602
13715
  }
13716
+ function declaredRoutes(toml) {
13717
+ const routes = [];
13718
+ let current = null;
13719
+ for (const raw of toml.split("\n")) {
13720
+ const line = raw.trim();
13721
+ if (line.startsWith("[")) {
13722
+ current = line === "[[operations]]" ? { name: "", methods: [], path: "", params: [] } : null;
13723
+ if (current) routes.push(current);
13724
+ continue;
13725
+ }
13726
+ if (!current) continue;
13727
+ const str2 = (key) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`).exec(line)?.[1];
13728
+ const list = (key) => {
13729
+ const m = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`).exec(line);
13730
+ return m ? [...m[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]) : void 0;
13731
+ };
13732
+ const name = str2("name");
13733
+ if (name !== void 0) current.name = name;
13734
+ const routePath = str2("path");
13735
+ if (routePath !== void 0) current.path = routePath;
13736
+ const method = str2("method");
13737
+ if (method !== void 0 && !current.methods.includes(method.toUpperCase())) current.methods.push(method.toUpperCase());
13738
+ const methods = list("methods");
13739
+ if (methods) {
13740
+ for (const m of methods) if (!current.methods.includes(m.toUpperCase())) current.methods.push(m.toUpperCase());
13741
+ }
13742
+ const params = list("params");
13743
+ if (params) current.params = params;
13744
+ }
13745
+ for (const route of routes) if (!route.methods.length) route.methods.push("GET");
13746
+ return routes;
13747
+ }
13603
13748
  function removeRoute(toml, name) {
13604
13749
  const lines = toml.split("\n");
13605
13750
  const kept = [];
@@ -13661,6 +13806,16 @@ function addRoute(toml, spec, declaredEntities2, options = {}) {
13661
13806
  throw new CliError("--handler only applies with --action handler");
13662
13807
  if (spec.api.status !== void 0 && (spec.api.status < 200 || spec.api.status > 299))
13663
13808
  throw new CliError("--status must be a 2xx");
13809
+ if (spec.api.action !== void 0 && ["create", "update", "delete"].includes(spec.api.action) && spec.method === "GET")
13810
+ throw new CliError(
13811
+ `--action ${spec.api.action} writes, but --method GET reads; pass --method ${spec.api.action === "create" ? "POST" : spec.api.action === "update" ? "PATCH" : "DELETE"}`
13812
+ );
13813
+ const sameParams = (a, b) => a.length === b.length && [...a].sort().every((v, i) => v === [...b].sort()[i]);
13814
+ for (const route of declaredRoutes(toml))
13815
+ if (route.name !== spec.name && route.path === spec.path && route.methods.includes(spec.method) && sameParams(route.params, spec.params))
13816
+ throw new CliError(
13817
+ `${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`
13818
+ );
13664
13819
  if (spec.entity !== void 0 && declaredEntities2 && !declaredEntities2.includes(spec.entity))
13665
13820
  throw new CliError(
13666
13821
  `Entity ${spec.entity} is not declared in schema/world.json (have: ${declaredEntities2.join(", ") || "none"}); run \`gateway worlds schema entity add\` first`
@@ -13793,18 +13948,43 @@ var assertManifest = (toml) => {
13793
13948
  if (!/^\s*\[(environment|env)\]\s*$/m.test(toml))
13794
13949
  throw new CliError("gateway-env.toml has no [environment] table; it is not a schema world manifest");
13795
13950
  };
13796
- function addDependency(toml, spec, depServes) {
13951
+ function removeDependency(toml, alias) {
13952
+ const kept = [];
13953
+ let dropping = false;
13954
+ for (const raw of toml.split("\n")) {
13955
+ const line = raw.trim();
13956
+ if (line.startsWith("[")) dropping = line === `[dependencies.${alias}]` || line.startsWith(`[dependencies.${alias}.`);
13957
+ if (!dropping) kept.push(raw);
13958
+ }
13959
+ while (kept.length && kept[kept.length - 1].trim() === "") kept.pop();
13960
+ return kept.join("\n") + "\n";
13961
+ }
13962
+ function dependencyServes(depDir) {
13963
+ const manifest = path29.join(depDir, "gateway-env.toml");
13964
+ if (!fs38.existsSync(manifest)) return void 0;
13965
+ const tools = manifestServedTools(fs38.readFileSync(manifest, "utf8"));
13966
+ const connector = path29.join(depDir, "connector.toml");
13967
+ const routes = fs38.existsSync(connector) ? declaredRoutes(fs38.readFileSync(connector, "utf8")).map((r) => r.name).filter(Boolean) : [];
13968
+ return tools === void 0 ? void 0 : { tools, routes };
13969
+ }
13970
+ function addDependency(toml, spec, depServes, opts = {}) {
13797
13971
  assertManifest(toml);
13798
13972
  if (!ALIAS.test(spec.alias))
13799
13973
  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`);
13974
+ if (declaredAliases(toml).includes(spec.alias)) {
13975
+ if (!opts.replace)
13976
+ throw new CliError(`[dependencies.${spec.alias}] is already declared; pass --replace to redeclare it (pin, path, tools, task, map)`);
13977
+ toml = removeDependency(toml, spec.alias);
13978
+ }
13802
13979
  if (!PIN.test(spec.pin)) throw new CliError(`--pin is <slug>@<ref>, got ${JSON.stringify(spec.pin)}`);
13803
13980
  if (path29.isAbsolute(spec.path)) throw new CliError("The dependency path is stored relative to the world");
13804
13981
  if (depServes) {
13982
+ const serves = Array.isArray(depServes) ? { tools: depServes, routes: [] } : depServes;
13805
13983
  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"}`);
13984
+ if (!serves.tools.includes(tool))
13985
+ throw new CliError(
13986
+ 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)` : "")
13987
+ );
13808
13988
  }
13809
13989
  const body = toml.endsWith("\n") ? toml : toml + "\n";
13810
13990
  return body + "\n" + renderDependency(spec);
@@ -13820,7 +14000,9 @@ function addTask(toml, spec, known = {}) {
13820
14000
  if (known.verifiers) {
13821
14001
  for (const v of spec.verifiers)
13822
14002
  if (!known.verifiers.includes(v))
13823
- throw new CliError(`verifiers/${v}.sql does not exist (have: ${known.verifiers.join(", ") || "none"})`);
14003
+ throw new CliError(
14004
+ `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`
14005
+ );
13824
14006
  }
13825
14007
  const aliases = declaredAliases(toml);
13826
14008
  for (const [alias, names] of Object.entries(spec.worlds)) {
@@ -13882,8 +14064,10 @@ function declaredEntities(dir) {
13882
14064
  var WORLD_SLUG = /^[a-z0-9][a-z0-9-]*$/;
13883
14065
  function connectorTomlSkeleton(dir) {
13884
14066
  const manifest = path29.join(dir, "gateway-env.toml");
14067
+ if (!fs38.existsSync(dir))
14068
+ throw new CliError(`${dir} does not exist; run \`gateway worlds schema init ${dir} --connector custom\` to start a world there`, 1);
13885
14069
  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);
14070
+ 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
14071
  const name = /^\s*name\s*=\s*"([^"]*)"/m.exec(fs38.readFileSync(manifest, "utf8"))?.[1];
13888
14072
  const slug = name && WORLD_SLUG.test(name) ? name : path29.basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "world";
13889
14073
  return [
@@ -13902,6 +14086,26 @@ function scaffoldVerifier(entity) {
13902
14086
  SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}";
13903
14087
  `;
13904
14088
  }
14089
+ function verifierSql(name, entity, where) {
14090
+ 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)}`);
14091
+ 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)}`);
14092
+ if (where === void 0) return scaffoldVerifier(entity);
14093
+ const clause = where.trim();
14094
+ if (!clause) throw new CliError("--where is a SQL condition over the entity's columns; it cannot be empty");
14095
+ return `-- ${name}: scores 1.0 once a ${entity} row satisfies the condition; edit for real tasks.
14096
+ -- A verifier is one SQL statement returning one number in 0..1 (0.5 is partial credit).
14097
+ SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "${entity}" WHERE ${clause};
14098
+ `;
14099
+ }
14100
+ function addVerifier(dir, name, entity, where) {
14101
+ const sql = verifierSql(name, entity, where);
14102
+ const file = path29.join(dir, "verifiers", `${name}.sql`);
14103
+ if (fs38.existsSync(file))
14104
+ throw new CliError(`verifiers/${name}.sql already exists (have: ${(verifierNames2(dir) ?? []).join(", ")}); edit it, or pick another name`);
14105
+ fs38.mkdirSync(path29.dirname(file), { recursive: true });
14106
+ fs38.writeFileSync(file, sql);
14107
+ return file;
14108
+ }
13905
14109
  function repointScaffoldVerifier(dir, entity, declared) {
13906
14110
  const file = path29.join(dir, "verifiers", "state_present.sql");
13907
14111
  if (!fs38.existsSync(file)) return null;
@@ -13945,7 +14149,7 @@ function registerScaffoldCommands(worlds) {
13945
14149
  repeat: true
13946
14150
  }
13947
14151
  ],
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.",
14152
+ 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
14153
  run: async (args, ctx) => {
13950
14154
  const dir = path29.resolve(args.positionals[0]);
13951
14155
  const file = path29.join(dir, "schema", "world.json");
@@ -13983,6 +14187,43 @@ function registerScaffoldCommands(worlds) {
13983
14187
  ctx.stdout(JSON.stringify(out, null, 2));
13984
14188
  }
13985
14189
  });
14190
+ schema.group("verifier", "Write verifiers/<name>.sql: the SQL that grades a task on the world's end state.").command({
14191
+ name: "add",
14192
+ help: "Scaffold one verifier: a SQL statement over an entity's table returning 1.0 when a row satisfies --where (or any row exists).",
14193
+ positionals: [
14194
+ { name: "path", help: "World directory holding schema/world.json" },
14195
+ { name: "name", help: "Verifier name, e.g. case_opened; what `schema task add --verifier` takes" }
14196
+ ],
14197
+ flags: [
14198
+ { name: "entity", help: "Entity whose table the verifier counts (from schema/world.json).", short: "e" },
14199
+ { 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" }
14200
+ ],
14201
+ 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.",
14202
+ run: async (args, ctx) => {
14203
+ const dir = path29.resolve(args.positionals[0]);
14204
+ const name = args.positionals[1];
14205
+ const entity = arg.str(args, "entity");
14206
+ const declared = declaredEntities(dir);
14207
+ if (declared === void 0) throw new CliError(`${dir} has no schema/world.json; run \`gateway worlds schema init ${args.positionals[0]} --connector custom\` first`);
14208
+ if (!entity) throw new CliError(`--entity is required: one of ${declared.join(", ") || "(declare one with `gateway worlds schema entity add` first)"}`);
14209
+ if (!declared.includes(entity)) throw new CliError(`Unknown entity ${entity}; the world has ${declared.join(", ") || "none"}`);
14210
+ const file = addVerifier(dir, name, entity, arg.str(args, "where"));
14211
+ const rel = path29.relative(process.cwd(), dir) || ".";
14212
+ ctx.stdout(
14213
+ JSON.stringify(
14214
+ {
14215
+ status: "ok",
14216
+ verifier: name,
14217
+ entity,
14218
+ file: path29.relative(process.cwd(), file) || file,
14219
+ next: `gateway worlds schema task add ${rel} <task_id> --prompt "<what the agent is told>" --verifier ${name}`
14220
+ },
14221
+ null,
14222
+ 2
14223
+ )
14224
+ );
14225
+ }
14226
+ });
13986
14227
  schema.command({
13987
14228
  name: "link",
13988
14229
  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 +14237,12 @@ function registerScaffoldCommands(worlds) {
13996
14237
  ],
13997
14238
  flags: [
13998
14239
  { 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 },
14240
+ {
14241
+ name: "tools",
14242
+ help: "Dependency tools (its [tools] serve, not its routes) to serve as <alias>.<tool>; comma-separated or repeatable. Default: every tool it has.",
14243
+ repeat: true
14244
+ },
14245
+ { name: "replace", help: "Redeclare an alias already linked (pin, path, tools, task, map rewritten).", boolean: true },
14000
14246
  { name: "task", help: "Scenario the dependency starts in: scenarios/<name>/ of its tree (the shipped templates have `default`)." },
14001
14247
  {
14002
14248
  name: "map",
@@ -14037,7 +14283,7 @@ function registerScaffoldCommands(worlds) {
14037
14283
  tools: arg.list(args, "tools").flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean),
14038
14284
  entities: arg.list(args, "map").map(parseEntityMap)
14039
14285
  };
14040
- const updated = addDependency(toml, spec, manifestServedTools(depToml));
14286
+ const updated = addDependency(toml, spec, dependencyServes(depDir), { replace: arg.bool(args, "replace") });
14041
14287
  fs38.writeFileSync(file, updated);
14042
14288
  ctx.stdout(
14043
14289
  JSON.stringify(
@@ -14106,7 +14352,11 @@ function registerScaffoldCommands(worlds) {
14106
14352
  worlds: worlds2,
14107
14353
  rewards: [...spec.verifiers, ...Object.entries(worlds2).flatMap(([a, names]) => names.map((n) => `${a}/${n}`))],
14108
14354
  file: path29.relative(process.cwd(), file) || file,
14109
- next: `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14355
+ next: [
14356
+ `gateway worlds schema compile ${path29.relative(process.cwd(), dir) || "."} # a manifest edit invalidates the compiled contract`,
14357
+ `gateway worlds schema check ${path29.relative(process.cwd(), dir) || "."}`,
14358
+ `gateway worlds serve ${path29.relative(process.cwd(), dir) || "."} --task ${spec.id}`
14359
+ ]
14110
14360
  },
14111
14361
  null,
14112
14362
  2
@@ -14245,7 +14495,7 @@ function buildCli() {
14245
14495
  "schema",
14246
14496
  "Compile and check gateway-world/1 contracts (the runtime runs on the platform)."
14247
14497
  );
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.";
14498
+ 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
14499
  worlds.group(
14250
14500
  "connector",
14251
14501
  "Vendor connections: validate, capture, conform, ingest, publish, clone."