@withgateway/sdk 0.2.4 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/dist/cli.js +1798 -1713
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +2412 -2327
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +47 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +43 -27
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/index.d.mts +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.js +390 -287
  12. package/dist/index.js.map +1 -1
  13. package/dist/index.mjs +375 -271
  14. package/dist/index.mjs.map +1 -1
  15. package/dist/traces/index.js +36 -20
  16. package/dist/traces/index.js.map +1 -1
  17. package/dist/traces/index.mjs +32 -16
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +2 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +2 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +26 -22
  24. package/dist/worlds/index.d.ts +26 -22
  25. package/dist/worlds/index.js +307 -203
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +297 -193
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +2 -1
  30. package/runtime/gatewaysdk/environment/_bundle.py +14 -24
  31. package/runtime/gatewaysdk/environment/schema/api.py +37 -18
  32. package/runtime/gatewaysdk/environment/schema/data.py +21 -19
  33. package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
  34. package/runtime/gatewaysdk/environment/schema/host.py +156 -546
  35. package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
  36. package/runtime/gatewaysdk/environment/schema/local.py +32 -126
  37. package/runtime/gatewaysdk/environment/schema/platform.py +14 -22
  38. package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
  39. package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
  40. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  41. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +6 -4
  42. package/runtime/gatewaysdk/environment/schema/tools_world.py +75 -23
  43. package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
  44. package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
  45. package/runtime/gatewaysdk/environment/world.py +391 -0
  46. package/skills/hooks-getting-started/SKILL.md +6 -4
@@ -129,10 +129,12 @@ personas to people: keep it with the run key, out of version control, never besi
129
129
 
130
130
  ## Wiring
131
131
 
132
- - **Agent SDK** — `guarded = run.wrap({ lookup_email: lookupEmail })` and register the wrapped
133
- function wherever the SDK takes a tool implementation; `run.tools()` materializes the file's
134
- `[tools.*]` (a keyed web search, a connector operation) already wrapped;
135
- `verdict = run.end(report)` runs `run_end`.
132
+ - **Agent SDK** — open the file (`from gatewaysdk.hooks import HookRun; run = HookRun("gateway-hooks.toml")`
133
+ / `import { HookRun } from "@withgateway/sdk/hooks"; const run = await HookRun.fromConfig("gateway-hooks.toml")`),
134
+ then wrap the tools: Python `guarded = run.wrap({"lookup_email": lookup_email})`, TypeScript
135
+ `guarded = run.wrapTools({ lookup_email: lookupEmail })`; register the wrapped function wherever
136
+ the SDK takes a tool implementation. `run.tools()` materializes the file's `[tools.*]` (a keyed
137
+ web search, a connector operation) already wrapped; `verdict = run.end(report)` runs `run_end`.
136
138
  - **Claude Code / coding agents** — `.claude/settings.json`: `PreToolUse`, `PostToolUse` and
137
139
  `Stop` entries whose command is `gateway hooks run`. State (run key + seeds) persists under
138
140
  `--state`, `$GATEWAY_HOOKS_STATE`, else `.gateway/hooks/<session id>`. A coding agent shows the
@@ -47,10 +47,16 @@ from dataclasses import dataclass, field
47
47
  from pathlib import Path
48
48
  from typing import Any
49
49
 
50
+ try:
51
+ import tomllib
52
+ except ModuleNotFoundError: # pragma: no cover - python 3.10
53
+ import tomli as tomllib
54
+
50
55
  from .. import _bundle
51
56
  from .._materialize import materialize_template
52
57
  from .._world import World
53
58
  from ..errors import WorldStartError
59
+ from ..world import World as WorldDetector
54
60
  from . import snapshot as snapshots
55
61
  from .api import ApiSettings, WorldState, load_api_settings
56
62
  from .api import load_handlers as load_api_handlers
@@ -58,6 +64,7 @@ from .compiler import ContractError, bundle_mode, check_bundle, fail
58
64
  from .connector import SPEC, Spec, load_spec
59
65
  from .data import seed_batch
60
66
  from .dependencies import Dependency, parse_dependencies
67
+ from .grading import world_state
61
68
  from .tasks import TaskSpec
62
69
 
63
70
  Handler = Callable[..., Any]
@@ -84,6 +91,12 @@ class ToolsTask:
84
91
  #: verifiers; ``None`` (a task that names no worlds) grades with all of every
85
92
  #: dependency's, the way it grades with all of the root's.
86
93
  worlds: dict[str, tuple[str, ...]] | None = None
94
+ #: An authored ``scenarios/<id>/`` task: its seed overlay replaces whole
95
+ #: entities of the template at open and reset (None: the template alone).
96
+ scenario: dict[str, list] | None = None
97
+ #: The scenario's ``checks/verify.py``, when it grades by one instead of
98
+ #: the world's SQL verifiers (the runtime's :class:`TaskGrader` runs it).
99
+ verify: Path | None = None
87
100
 
88
101
  def selected(self, all_verifiers: list[str]) -> list[str]:
89
102
  """The verifiers this task grades with: its own list, else the
@@ -106,19 +119,12 @@ INLINE_TASK_ID = "session"
106
119
 
107
120
 
108
121
  def inline_task(spec: TaskSpec) -> ToolsTask:
109
- """A session task (:mod:`tasks`) as a mock-tools task: the spec's
110
- instruction as the prompt, graded by every verifier the bundle ships. The
111
- spec's grader vocabulary (assertions, python, rubric) is an api world's —
112
- a mock-tools world's checks are its ``verifiers/*.sql``, and a task cannot
113
- bring others — so a task that carries a grader is refused rather than
114
- graded by something the world never had. The seed is applied by
115
- :class:`ToolsWorld` once the template copy exists."""
116
- if spec.grader is not None:
117
- fail(
118
- "task",
119
- "a mock-tools world grades with its bundled verifiers; give the task no grader, or open an api world",
120
- "/task/grader",
121
- )
122
+ """A session task (:mod:`tasks`) as a schema-world task: the spec's
123
+ instruction as the prompt. Without a grader of its own the task is graded
124
+ by every verifier the bundle ships (:meth:`ToolsWorld.grade`); with one
125
+ (assertions, python, rubric) the host grades it the way it grades an api
126
+ world's session task, over :meth:`ToolsWorld.grader_state`. The seed is
127
+ applied by :class:`ToolsWorld` once the template copy exists."""
122
128
  return ToolsTask(id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata))
123
129
 
124
130
 
@@ -218,7 +224,9 @@ def served_with_dependencies(version: ToolsVersion, dependencies: dict[str, Depe
218
224
 
219
225
 
220
226
  def is_tools_bundle(bundle: Path) -> bool:
221
- return (bundle / "gateway-env.toml").is_file() and not (bundle / "gateway-api-world.toml").is_file()
227
+ """The tree runs on the tools engine (a schema or legacy tools world stored
228
+ as itself; an api bundle does not)."""
229
+ return WorldDetector.from_dir(bundle).tools_engine
222
230
 
223
231
 
224
232
  def verifier_names(bundle: Path) -> list[str]:
@@ -263,14 +271,37 @@ def _tasks_from_rows(rows: list) -> list[ToolsTask]:
263
271
  return out
264
272
 
265
273
 
274
+ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
275
+ """A task from an authored scenario dir (what an api bundle carried and
276
+ ``worlds migrate`` keeps): ``instruction.md`` or the toml's ``instruction``
277
+ is the prompt, ``seed/*.json`` the overlay, ``checks/verify.py`` the grader."""
278
+ table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
279
+ instruction = scenario / "instruction.md"
280
+ prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
281
+ verify = scenario / "checks" / "verify.py"
282
+ return ToolsTask(
283
+ id=name,
284
+ prompt=prompt.strip() or f"Drive the world into the state the scenario '{name}' checks.",
285
+ metadata={"scenario_id": name},
286
+ scenario=snapshots.scenario_overlay(scenario) or None,
287
+ verify=verify if verify.is_file() else None,
288
+ )
289
+
290
+
291
+ def scenario_tasks(bundle: Path) -> list[ToolsTask]:
292
+ """One task per ``scenarios/<name>/scenario.toml`` of the tree."""
293
+ return [_scenario_task(name, path) for name, path in snapshots.scenario_dirs(bundle).items()]
294
+
295
+
266
296
  def load_tasks(
267
297
  bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str], *, required: bool = True
268
298
  ) -> dict[str, ToolsTask]:
269
299
  """The bundle's tasks, in the runner's precedence: ``[[tasks]]`` in the
270
300
  manifest, else ``tasks.jsonl`` / ``tasks.json``, else one task per
271
- verifier. A bundle with neither has nothing to grade and is refused when
272
- ``required`` (the host opens it to grade); a local session that only calls
273
- tools opens it with none."""
301
+ verifier; plus one per authored ``scenarios/<name>/`` the declared tasks
302
+ do not already name. A bundle with none has nothing to grade and is
303
+ refused when ``required`` (the host opens it to grade); a local session
304
+ that only calls tools opens it with none."""
274
305
  declared = manifest.raw.get("tasks")
275
306
  tasks = _tasks_from_rows(declared) if isinstance(declared, list) else []
276
307
  if not tasks:
@@ -296,16 +327,18 @@ def load_tasks(
296
327
  )
297
328
  for name in verifiers
298
329
  ]
299
- if not tasks and required:
300
- fail(
301
- "host",
302
- "mock-tools bundle declares no tasks and ships no verifiers/*.sql: nothing to grade",
303
- )
304
330
  by_id: dict[str, ToolsTask] = {}
305
331
  for task in tasks:
306
332
  if task.id in by_id:
307
333
  fail("host", f"task id '{task.id}' is declared twice")
308
334
  by_id[task.id] = task
335
+ for task in scenario_tasks(bundle):
336
+ by_id.setdefault(task.id, task)
337
+ if not by_id and required:
338
+ fail(
339
+ "host",
340
+ "mock-tools bundle declares no tasks and ships no verifiers/*.sql: nothing to grade",
341
+ )
309
342
  return by_id
310
343
 
311
344
 
@@ -459,7 +492,10 @@ class ToolsWorld:
459
492
 
460
493
  def _apply_task_seed(self) -> None:
461
494
  """Start the session in its task's state: the template with the task's
462
- rows on top. A task without a seed starts on the template alone."""
495
+ rows on top — a scenario task's overlay replacing whole entities, then
496
+ the session task's seed. A task without either starts on the template."""
497
+ if self.task.scenario is not None:
498
+ self.seed({"rows": self.task.scenario, "mode": "replace"})
463
499
  if self._task_seed is not None:
464
500
  self.seed({"rows": self._task_seed["rows"], "mode": self._task_seed["mode"]})
465
501
 
@@ -606,6 +642,10 @@ class ToolsWorld:
606
642
  counts[f"{prefix}.{entity}" if prefix else entity] = len(store.list(entity))
607
643
  return {"seeded": seeded, "mode": mode, "entity_counts": counts}
608
644
 
645
+ @property
646
+ def session_dir(self) -> Path:
647
+ return self._dir
648
+
609
649
  def state(self) -> dict:
610
650
  """The root's rows by entity, and under ``worlds`` each dependency's."""
611
651
  out: dict[str, Any] = {"entities": _entities_of(self.world)}
@@ -613,6 +653,18 @@ class ToolsWorld:
613
653
  out["worlds"] = {alias: {"entities": _entities_of(world)} for alias, world in self.worlds.items()}
614
654
  return out
615
655
 
656
+ def entity_names(self) -> list[str]:
657
+ """Every entity name :meth:`grader_state` reports, rows or not."""
658
+ names = list(self.world.contract.entities) if self.world.contract is not None else []
659
+ for alias, world in self.worlds.items():
660
+ if world.contract is not None:
661
+ names.extend(f"{alias}.{entity}" for entity in world.contract.entities)
662
+ return names
663
+
664
+ def grader_state(self) -> dict:
665
+ """The rows as a session task's grader reads them (:func:`world_state`)."""
666
+ return world_state(self.world, self.worlds)
667
+
616
668
  def close(self) -> None:
617
669
  world = getattr(self, "world", None)
618
670
  if world is not None:
@@ -0,0 +1,136 @@
1
+ """The session protocol, once: every verb a world session answers, with the
2
+ method it takes and how its body is read. Both HTTP transports dispatch
3
+ through this table — the local session (``local.py``, ``/__session/<verb>``)
4
+ and the World Host control plane (``host.py``, ``/__host/sessions/<sid>/
5
+ <verb>``) — so the two cannot drift: a verb added here is served by both, a
6
+ body shape accepted here is accepted by both. The transports stay distinct
7
+ (loopback with no secret against a fleet with leases, workers and exports);
8
+ only the verbs are shared.
9
+
10
+ A verb marked ``hosted`` is the platform's rendezvous with a session it keeps
11
+ alive across hosts (the lease, the state export, DELETE as the platform's
12
+ close); the local session, which lives as long as the process serving it,
13
+ refuses them by name."""
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Callable
18
+ from dataclasses import dataclass
19
+ from typing import Any
20
+
21
+ from .redaction import parse_mode
22
+ from .validation import ContractError, fail
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class SessionVerb:
27
+ """One row of the protocol: ``method`` and ``name`` are the route (``name``
28
+ None addresses the session itself, as ``DELETE`` does); ``read`` turns the
29
+ request body into the keyword arguments the session operation takes, or
30
+ refuses the shape (a :class:`ContractError` the transport answers 400)."""
31
+
32
+ method: str
33
+ name: str | None
34
+ read: Callable[[dict], dict[str, Any]]
35
+ hosted: bool = False
36
+
37
+ @property
38
+ def route(self) -> str:
39
+ return f"{self.method} {self.name}" if self.name is not None else f"{self.method} <session>"
40
+
41
+ def matches(self, method: str, name: str | None) -> bool:
42
+ return self.method == method and self.name == (name or None)
43
+
44
+
45
+ def read_nothing(_body: dict) -> dict[str, Any]:
46
+ return {}
47
+
48
+
49
+ def read_seed(body: dict) -> dict[str, Any]:
50
+ """``{rows, mode, redact}``, the same under ``args`` (the platform wraps
51
+ the seed it forwards), or bare ``{entity: [row, ...]}`` — the shape a rows
52
+ file has — taken as the rows of an append."""
53
+ args = body["args"] if isinstance(body.get("args"), dict) else body
54
+ if "rows" not in args and "mode" not in args and args and all(isinstance(v, list) for v in args.values()):
55
+ args = {"rows": args}
56
+ rows = args.get("rows")
57
+ if not isinstance(rows, dict):
58
+ fail(
59
+ "host",
60
+ 'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
61
+ "a dependency's entity is named alias.entity",
62
+ )
63
+ mode = args.get("mode", "append")
64
+ if mode not in ("append", "replace"):
65
+ fail("host", 'seed mode must be "append" or "replace"', "/args/mode")
66
+ return {"rows": rows, "mode": mode, "redact": parse_mode(args.get("redact"), "/args/redact")}
67
+
68
+
69
+ def read_grade(body: dict) -> dict[str, Any]:
70
+ """``report`` is the agent's own account of the run, read by a rubric
71
+ judge or put beside the state for a deterministic grader; absent is fine,
72
+ anything but a string is not."""
73
+ report = body.get("report")
74
+ if report is not None and not isinstance(report, str):
75
+ fail("input", "report must be a string", "/report")
76
+ return {"report": report}
77
+
78
+
79
+ def read_call(body: dict) -> dict[str, Any]:
80
+ tool = body.get("tool")
81
+ if not isinstance(tool, str) or not tool:
82
+ fail("input", "tool must be a tool name (root) or alias.tool (a dependency's)", "/tool")
83
+ args = body.get("args") or {}
84
+ if not isinstance(args, dict):
85
+ fail("input", "args must be an object of the tool's arguments", "/args")
86
+ return {"tool": tool, "args": args}
87
+
88
+
89
+ def read_export(body: dict) -> dict[str, Any]:
90
+ known = body.get("knownSha256")
91
+ return {"known_sha256": known if isinstance(known, str) else None}
92
+
93
+
94
+ SESSION_VERBS: tuple[SessionVerb, ...] = (
95
+ SessionVerb("GET", "tools", read_nothing),
96
+ SessionVerb("GET", "task", read_nothing),
97
+ SessionVerb("GET", "state", read_nothing),
98
+ SessionVerb("POST", "grade", read_grade),
99
+ SessionVerb("POST", "reset", read_nothing),
100
+ SessionVerb("POST", "seed", read_seed),
101
+ SessionVerb("POST", "call", read_call),
102
+ SessionVerb("POST", "close", read_nothing),
103
+ SessionVerb("POST", "renew", read_nothing, hosted=True),
104
+ SessionVerb("POST", "export", read_export, hosted=True),
105
+ SessionVerb("DELETE", None, read_nothing, hosted=True),
106
+ )
107
+
108
+
109
+ def session_verb(method: str, name: str | None) -> SessionVerb | None:
110
+ return next((verb for verb in SESSION_VERBS if verb.matches(method, name)), None)
111
+
112
+
113
+ def served_verbs(*, hosted: bool) -> tuple[SessionVerb, ...]:
114
+ """The rows a transport answers: every one on the host, the session's own
115
+ (not the lease's) locally."""
116
+ return tuple(verb for verb in SESSION_VERBS if hosted or not verb.hosted)
117
+
118
+
119
+ def unknown_verb(method: str, name: str | None, *, hosted: bool, prefix: str) -> dict:
120
+ """The 404 body for a route off the table, naming what is on it. A hosted
121
+ verb sent to the local session is refused by name, not as unknown."""
122
+ verb = session_verb(method, name)
123
+ if verb is not None and verb.hosted and not hosted:
124
+ return {"error": f"{verb.route} is a hosted session's verb (the platform's lease); the local session has none"}
125
+ known = ", ".join(
126
+ f"{v.method} {prefix}{v.name}" if v.name else f"{v.method} {prefix.rstrip('/')}"
127
+ for v in served_verbs(hosted=hosted)
128
+ )
129
+ return {"error": f"unknown session route {method} {prefix}{name or ''}; one of {known}"}
130
+
131
+
132
+ def refusal(error: ContractError) -> dict:
133
+ """A refused call as the answer a session gives it: an unknown tool,
134
+ arguments off the schema, a tool outside the task's allow-list, a write the
135
+ store will not take, all ``{status: 400, body: {error, detail}}``."""
136
+ return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
@@ -51,6 +51,8 @@ from dataclasses import dataclass, field
51
51
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
52
52
  from pathlib import Path
53
53
 
54
+ from .grading import VerifierSandbox
55
+
54
56
  #: Address space a worker may use, in MiB, unless ``WORLDS_WORKER_MEMORY_MB`` says otherwise.
55
57
  DEFAULT_WORKER_MEMORY_MB = 2048
56
58
  #: Memory every worker together may use, in MiB, unless
@@ -281,6 +283,18 @@ def confined_command(script: Path, python: str = sys.executable) -> list[str]:
281
283
  return [python, "-c", _CONFINED_PRELUDE, str(script)]
282
284
 
283
285
 
286
+ class ConfinedVerifierSandbox(VerifierSandbox):
287
+ """How the host runs a task's ``verify.py``: confined like a worker, with a
288
+ scrubbed environment and a home under the session. World-authored code
289
+ sees no secret of this process, be it the host's or a worker's."""
290
+
291
+ def command(self, script: Path) -> list[str]:
292
+ return confined_command(script)
293
+
294
+ def environment(self, home: Path) -> dict[str, str]:
295
+ return verifier_environment(home=home)
296
+
297
+
284
298
  # --------------------------------------------------------------------------- #
285
299
  # The supervisor's side: start, reach and stop workers.
286
300
  # --------------------------------------------------------------------------- #