@withgateway/sdk 0.2.2 → 0.2.4

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 (52) hide show
  1. package/dist/cli.js +11992 -4572
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +11998 -4578
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +71 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +59 -20
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/hooks/index.d.mts +1 -0
  10. package/dist/hooks/index.d.ts +1 -0
  11. package/dist/hooks/index.js +4355 -0
  12. package/dist/hooks/index.js.map +1 -0
  13. package/dist/hooks/index.mjs +4243 -0
  14. package/dist/hooks/index.mjs.map +1 -0
  15. package/dist/{index-Dpo-t8iO.d.ts → index-1xnxt0Cc.d.ts} +58 -2
  16. package/dist/index-B0R3IgsV.d.mts +1279 -0
  17. package/dist/index-B0R3IgsV.d.ts +1279 -0
  18. package/dist/{index-B5HUQQDE.d.mts → index-C1wDEwH4.d.mts} +58 -2
  19. package/dist/index.d.mts +4 -3
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +6547 -1552
  22. package/dist/index.js.map +1 -1
  23. package/dist/index.mjs +6636 -1655
  24. package/dist/index.mjs.map +1 -1
  25. package/dist/traces/index.js +60 -20
  26. package/dist/traces/index.js.map +1 -1
  27. package/dist/traces/index.mjs +51 -12
  28. package/dist/traces/index.mjs.map +1 -1
  29. package/dist/tracing/index.d.mts +1 -1
  30. package/dist/tracing/index.d.ts +1 -1
  31. package/dist/tracing/index.js +46 -3
  32. package/dist/tracing/index.js.map +1 -1
  33. package/dist/tracing/index.mjs +41 -2
  34. package/dist/tracing/index.mjs.map +1 -1
  35. package/dist/worlds/index.d.mts +371 -6
  36. package/dist/worlds/index.d.ts +371 -6
  37. package/dist/worlds/index.js +2061 -235
  38. package/dist/worlds/index.js.map +1 -1
  39. package/dist/worlds/index.mjs +2050 -224
  40. package/dist/worlds/index.mjs.map +1 -1
  41. package/package.json +6 -1
  42. package/runtime/gatewaysdk/environment/_materialize.py +3 -3
  43. package/runtime/gatewaysdk/environment/schema/api.py +116 -2
  44. package/runtime/gatewaysdk/environment/schema/compiler.py +14 -0
  45. package/runtime/gatewaysdk/environment/schema/host.py +37 -11
  46. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +154 -0
  47. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +5 -5
  48. package/runtime/gatewaysdk/environment/schema/snapshot.py +6 -5
  49. package/runtime/gatewaysdk/environment/schema/tasks.py +12 -2
  50. package/runtime/gatewaysdk/environment/schema/workers.py +30 -13
  51. package/skills/hooks-getting-started/SKILL.md +154 -0
  52. package/skills/worlds-getting-started/SKILL.md +5 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.2.2",
3
+ "version": "0.2.4",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -76,6 +76,11 @@
76
76
  "import": "./dist/traces/index.mjs",
77
77
  "require": "./dist/traces/index.js"
78
78
  },
79
+ "./hooks": {
80
+ "types": "./dist/hooks/index.d.ts",
81
+ "import": "./dist/hooks/index.mjs",
82
+ "require": "./dist/hooks/index.js"
83
+ },
79
84
  "./cli": {
80
85
  "types": "./dist/cli.d.ts",
81
86
  "import": "./dist/cli.mjs",
@@ -37,9 +37,9 @@ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool =
37
37
 
38
38
  raise ContractError(
39
39
  "snapshot_pinned",
40
- "db/snapshot.json pins a hosted snapshot that is not in the tree: fetch the world "
41
- "with its snapshot (load_world_to_sandbox, gateway worlds pull) instead of "
42
- "materializing from its data files",
40
+ "db/snapshot.json pins a hosted snapshot that is not in the tree: run the world on "
41
+ "the platform (`gateway worlds session open <slug>`, load_world_to_sandbox), which "
42
+ "serves that snapshot, or remove db/snapshot.json to rebuild from the data files",
43
43
  schema_path="/db/state.sqlite",
44
44
  )
45
45
  initial = read_json(bundle / "data/initial.json")
@@ -84,6 +84,7 @@ served beside the vendor routes.
84
84
  from __future__ import annotations
85
85
 
86
86
  import base64
87
+ import collections
87
88
  import importlib.util
88
89
  import json
89
90
  import os
@@ -109,7 +110,20 @@ from .connector import DEFAULT_TOKEN_PATH, SPEC, Operation, Spec, load_spec, sto
109
110
  from .store import SQLiteStore
110
111
  from .validation import ContractError, fail, read_json
111
112
 
112
- ADMIN = {"seed": "/__world/seed", "reset": "/__world/reset", "state": "/__world/state", "health": "/healthz"}
113
+ ADMIN = {
114
+ "seed": "/__world/seed",
115
+ "reset": "/__world/reset",
116
+ "state": "/__world/state",
117
+ "calls": "/__world/calls",
118
+ "health": "/healthz",
119
+ }
120
+
121
+ #: How many vendor-route requests a world keeps in its call log, unless
122
+ #: ``WORLDS_CALL_LOG_MAX`` says otherwise; the oldest are dropped past it and
123
+ #: ``total`` still counts every one. ``0`` keeps none. The log is what a grader
124
+ #: reads to know what the agent ASKED (an investigation reads and never writes,
125
+ #: so its rows tell nothing) and what ``/__world/calls`` serves.
126
+ DEFAULT_CALL_LOG_MAX = 5000
113
127
  #: How many events :meth:`WorldState.emit` keeps for a page polling ``since``.
114
128
  EVENT_LOG_SIZE = 500
115
129
  PORT = 8080
@@ -1342,6 +1356,95 @@ def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str
1342
1356
  Response = tuple[int, Any, dict[str, str] | None]
1343
1357
 
1344
1358
 
1359
+ def _strings_in(node: Any, out: list[str] | None = None) -> list[str]:
1360
+ """Every string in a JSON value, however nested, once each, in document order."""
1361
+ if out is None:
1362
+ out = []
1363
+ if isinstance(node, str):
1364
+ if node not in out:
1365
+ out.append(node)
1366
+ elif isinstance(node, dict):
1367
+ for value in node.values():
1368
+ _strings_in(value, out)
1369
+ elif isinstance(node, (list, tuple)):
1370
+ for value in node:
1371
+ _strings_in(value, out)
1372
+ return out
1373
+
1374
+
1375
+ class CallLog:
1376
+ """The vendor-route requests one session answered, in order: what the agent
1377
+ asked (operation, method, path, path args, query, body) and what came back
1378
+ (status, ``rows`` = the length of the operation's ``results`` list when the
1379
+ answer carries one, elapsed). Bounded; ``total`` counts past the bound.
1380
+ ``/__world/calls`` serves it and a task's ``verify.py`` is handed it as
1381
+ ``calls`` beside the rows, because a read-only investigation leaves no row
1382
+ behind and its calls are the only evidence of what it did."""
1383
+
1384
+ def __init__(self, maximum: int | None = None):
1385
+ if maximum is None:
1386
+ raw = os.environ.get("WORLDS_CALL_LOG_MAX")
1387
+ maximum = int(raw) if raw else DEFAULT_CALL_LOG_MAX
1388
+ self.maximum = max(0, int(maximum))
1389
+ self.entries: collections.deque[dict] = collections.deque(maxlen=self.maximum or None)
1390
+ self.total = 0
1391
+ self._lock = threading.Lock()
1392
+
1393
+ def record(
1394
+ self,
1395
+ operation: Operation,
1396
+ method: str,
1397
+ path: str,
1398
+ args: dict,
1399
+ query_all: dict,
1400
+ body: Any,
1401
+ status: int,
1402
+ answer: Any,
1403
+ elapsed_s: float,
1404
+ ) -> None:
1405
+ if self.maximum == 0:
1406
+ return
1407
+ rows = None
1408
+ if isinstance(answer, dict) and isinstance(answer.get(operation.results), list):
1409
+ rows = len(answer[operation.results])
1410
+ elif isinstance(answer, list):
1411
+ rows = len(answer)
1412
+ query = {k: (v[0] if len(v) == 1 else list(v)) for k, v in query_all.items()}
1413
+ entry = {
1414
+ "seq": self.total + 1,
1415
+ "at": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
1416
+ "operation": operation.name,
1417
+ "method": method,
1418
+ "path": path,
1419
+ "args": dict(args),
1420
+ "query": query,
1421
+ "body": body if isinstance(body, (dict, list)) and body else None,
1422
+ # Every string the request carried, wherever it sat (a path segment, a
1423
+ # query value, a body list of lists), so a grader can ask "was X searched"
1424
+ # with one `contains` and no knowledge of the vendor's request shape.
1425
+ "selectors": _strings_in([args, query, body]),
1426
+ "status": status,
1427
+ "rows": rows,
1428
+ # `found`: the request was answered and returned rows. A grader's `where`
1429
+ # takes scalars, and "asked and got something back" is the question an
1430
+ # investigation's grader asks most.
1431
+ "found": status < 400 and rows is not None and rows > 0,
1432
+ "elapsed_ms": round(elapsed_s * 1000, 1),
1433
+ }
1434
+ with self._lock:
1435
+ self.total += 1
1436
+ self.entries.append(entry)
1437
+
1438
+ def describe(self) -> dict:
1439
+ with self._lock:
1440
+ return {"total": self.total, "kept": len(self.entries), "max": self.maximum, "calls": list(self.entries)}
1441
+
1442
+ def clear(self) -> None:
1443
+ with self._lock:
1444
+ self.entries.clear()
1445
+ self.total = 0
1446
+
1447
+
1345
1448
  class WorldApp:
1346
1449
  """One world's HTTP behaviour as a function of the request.
1347
1450
 
@@ -1359,6 +1462,7 @@ class WorldApp:
1359
1462
  key: str | None,
1360
1463
  handlers: dict[str, Handler] | None = None,
1361
1464
  allowed: frozenset[str] | None = None,
1465
+ call_log_max: int | None = None,
1362
1466
  ):
1363
1467
  self.state = state
1364
1468
  self.router = router
@@ -1370,6 +1474,7 @@ class WorldApp:
1370
1474
  #: A route outside the list answers 403 before any handler runs, so the
1371
1475
  #: list holds against a client that talks to the vendor API directly.
1372
1476
  self.allowed = allowed
1477
+ self.calls = CallLog(call_log_max)
1373
1478
 
1374
1479
  # ------------------------------------------------------------ helpers
1375
1480
 
@@ -1431,7 +1536,9 @@ class WorldApp:
1431
1536
  if url.path == ADMIN["health"]:
1432
1537
  return 200, {"ok": True, "world": router.spec.slug}, None
1433
1538
  if url.path == ADMIN["state"]:
1434
- return 200, {**state.dump(), "snapshot": state.describe_snapshot()}, None
1539
+ return 200, {**state.dump(), "snapshot": state.describe_snapshot(), "calls": self.calls.describe()["calls"]}, None
1540
+ if url.path == ADMIN["calls"]:
1541
+ return 200, self.calls.describe(), None
1435
1542
  if method == "POST":
1436
1543
  if url.path == ADMIN["reset"]:
1437
1544
  state.reset()
@@ -1477,6 +1584,13 @@ class WorldApp:
1477
1584
  body = self._body(raw, headers) if method in ("POST", "PUT", "PATCH") else {}
1478
1585
  if body is None:
1479
1586
  return settings.invalid_status, settings.invalid, None
1587
+ started = time.monotonic()
1588
+ status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
1589
+ self.calls.record(operation, method, path, args, query_all, body, status, answer, time.monotonic() - started)
1590
+ return status, answer, extra
1591
+
1592
+ def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
1593
+ settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
1480
1594
  host = headers.get("host") or default_host
1481
1595
  forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
1482
1596
  ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
@@ -44,6 +44,13 @@ RESERVED = ("_", "sqlite_", "gateway_", "benchmark_")
44
44
  FIELD_RESERVED = ("sqlite_", "gateway_", "benchmark_")
45
45
 
46
46
 
47
+ #: Keys a state dump carries beside its entities: ``snapshot`` (which snapshot the
48
+ #: rows came from), ``calls`` (the vendor-route requests the session answered, what
49
+ #: a grader reads when the rows say nothing) and ``report`` (the agent's own account
50
+ #: of the run, handed to the grade call, for a grader to check against the calls).
51
+ #: An entity may not take them.
52
+ RESERVED_STATE_KEYS = frozenset({"snapshot", "calls", "report"})
53
+
47
54
  def identifier(value: Any, location: str) -> str:
48
55
  if (
49
56
  not isinstance(value, str)
@@ -291,6 +298,13 @@ def build(bundle: Path) -> Contract:
291
298
  for name, entity in sorted(entities.items()):
292
299
  location = f"world.json#/x-gateway/entities/{name}"
293
300
  identifier(name, location)
301
+ if name.lower() in RESERVED_STATE_KEYS:
302
+ fail(
303
+ "identity",
304
+ f"'{name}' is a reserved key of the state dump (beside the rows it carries "
305
+ f"{', '.join(sorted(RESERVED_STATE_KEYS))}); name the entity something else",
306
+ location,
307
+ )
294
308
  if name.lower() in seen:
295
309
  fail("identity", "Entity names collide under SQLite case folding", location)
296
310
  seen.add(name.lower())
@@ -69,7 +69,7 @@ from contextlib import contextmanager
69
69
  from dataclasses import dataclass, field
70
70
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
71
71
  from pathlib import Path
72
- from typing import Any, Protocol
72
+ from typing import Any, Optional, Protocol
73
73
 
74
74
  from .._tar import safe_tar_extract
75
75
  from . import snapshot as snapshots
@@ -125,6 +125,7 @@ from .tools_world import (
125
125
  from .validation import ContractError, fail
126
126
  from .workers import (
127
127
  DEFAULT_WORKER_BUDGET_MB,
128
+ DEFAULT_WORKER_FOOTPRINT_MB,
128
129
  DEFAULT_WORKER_MEMORY_MB,
129
130
  Worker,
130
131
  WorkerCapacity,
@@ -1421,6 +1422,7 @@ class WorldHost:
1421
1422
  "capacity": self.max_sessions,
1422
1423
  "draining": self.draining,
1423
1424
  "workers": self.worker_count(),
1425
+ "maxWorkers": self.workers.max_workers if self.workers is not None else 0,
1424
1426
  "versions": self.cache.version_ids(),
1425
1427
  "versionsInUse": versions_in_use,
1426
1428
  "uptimeSeconds": time.time() - self.started_at,
@@ -1653,19 +1655,35 @@ class WorldHost:
1653
1655
  if session.tools is not None:
1654
1656
  return session.tools.state()
1655
1657
  assert session.state is not None
1656
- return {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1657
-
1658
- def grade(self, session_id: str) -> dict:
1658
+ state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1659
+ if session.app is not None:
1660
+ state["calls"] = session.app.calls.describe()["calls"]
1661
+ return state
1662
+
1663
+ def grade(self, session_id: str, report: Optional[str] = None) -> dict:
1664
+ """Grade the session. ``report`` is the agent's own account of the run — the
1665
+ text a rubric judge reads; here it is put beside the state as ``report`` so a
1666
+ deterministic grader (assertions, verify.py) can check what the agent CLAIMED
1667
+ against what the calls show, without a judge."""
1659
1668
  with self.using(session_id) as session:
1660
1669
  if session.worker is not None:
1661
- return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/grade", {})
1670
+ body = {"report": report} if report is not None else {}
1671
+ return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/grade", body)
1662
1672
  if session.tools is not None:
1663
1673
  return session.tools.grade()
1664
- return self._grade(session)
1674
+ return self._grade(session, report)
1665
1675
 
1666
- def _grade(self, session: Session) -> dict:
1676
+ def _grade(self, session: Session, report: Optional[str] = None) -> dict:
1667
1677
  assert session.state is not None
1668
1678
  state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1679
+ if session.app is not None:
1680
+ # What the agent asked, beside what it left: a read-only investigation
1681
+ # writes nothing, so its calls are the evidence a grader reads.
1682
+ state["calls"] = session.app.calls.describe()["calls"]
1683
+ if report is not None:
1684
+ # The agent's claim, beside the evidence. A reserved key like ``calls``
1685
+ # and ``snapshot``: no world entity may be named ``report``.
1686
+ state["report"] = report
1669
1687
  spec = session.task_spec
1670
1688
  if spec is not None:
1671
1689
  # The session's own task: its assertions are evaluated here, pure
@@ -2124,7 +2142,10 @@ def make_host_handler(
2124
2142
  if method == "GET" and verb == "state":
2125
2143
  return self._reply(200, host.state(sid))
2126
2144
  if method == "POST" and verb == "grade":
2127
- return self._reply(200, host.grade(sid))
2145
+ report = body.get("report")
2146
+ if report is not None and not isinstance(report, str):
2147
+ return self._reply(400, {"error": "report must be a string"})
2148
+ return self._reply(200, host.grade(sid, report))
2128
2149
  if method == "POST" and verb == "call":
2129
2150
  tool = body.get("tool")
2130
2151
  if not isinstance(tool, str):
@@ -2476,9 +2497,11 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
2476
2497
  ``WORLDS_HOST_HEARTBEAT_S`` is how often it reports to the platform (with
2477
2498
  ``WORLDS_PLATFORM_URL`` and an advertised address, else no heartbeat);
2478
2499
  ``WORLDS_HOST_DRAIN_S`` is how long a SIGTERM waits for sessions to close;
2479
- ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space and
2480
- ``WORLDS_WORKER_BUDGET_MB`` all of them together (their count is the
2481
- quotient; one more version answers 503 ``at_capacity``),
2500
+ ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space,
2501
+ ``WORLDS_WORKER_BUDGET_MB`` is the memory all of them together are held to
2502
+ and ``WORLDS_WORKER_FOOTPRINT_MB`` what each is counted at against it
2503
+ (unset, its whole address-space cap; their count is the quotient, and one
2504
+ more version answers 503 ``at_capacity``),
2482
2505
  ``WORLDS_HOST_OBJECT_STORE`` is where every presigned URL it is handed
2483
2506
  may point (required; ``any`` for a dev host),
2484
2507
  ``WORLDS_HOST_MAX_BUNDLE_MB`` is the largest version bundle the cache
@@ -2504,6 +2527,9 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
2504
2527
  worlds_domain=worlds_domain,
2505
2528
  memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
2506
2529
  budget_mb=int(os.environ.get("WORLDS_WORKER_BUDGET_MB") or DEFAULT_WORKER_BUDGET_MB),
2530
+ footprint_mb=int(os.environ["WORLDS_WORKER_FOOTPRINT_MB"])
2531
+ if os.environ.get("WORLDS_WORKER_FOOTPRINT_MB")
2532
+ else DEFAULT_WORKER_FOOTPRINT_MB,
2507
2533
  )
2508
2534
  world_host = WorldHost(
2509
2535
  Path(cache_root),
@@ -0,0 +1,154 @@
1
+ ---
2
+ name: hooks-getting-started
3
+ description: Rules around an agent's tool calls from one gateway-hooks.toml — the alias door (personas in, real values out), identities that arrive from the web (mint_inbound), redaction of anything (kinds, literal values, patterns), per-task overrides, coding-agent and agent-SDK wiring, and how to check a file before an agent runs it. Use when an agent must not see a real person's identifiers, when web results must be scrubbed, or when wiring gateway hooks into Claude Code or an agent SDK.
4
+ ---
5
+
6
+ # Hooks: getting started
7
+
8
+ One file, `gateway-hooks.toml`, holds the rules that run around an agent's tool calls. The
9
+ same file is attached in code by an agent SDK (`HookRun.from_config` / `HookRun.fromConfig`),
10
+ run as a coding agent's hook (`gateway hooks run`), and validated without an agent
11
+ (`gateway hooks check`). Nothing in it is automatic: every behaviour is a rule you wrote or a
12
+ knob with a default, and a task can override the file.
13
+
14
+ ```bash
15
+ gateway hooks guide # this page
16
+ gateway hooks check gateway-hooks.toml # validate, build every handler, dry-run one event
17
+ gateway hooks run # the command a coding agent names in its settings
18
+ gateway hooks legend <run dir> # persona -> real, for the owner
19
+ gateway hooks reveal <file> # a run's file with the real values put back
20
+ ```
21
+
22
+ ## The file, in one screen
23
+
24
+ ```toml
25
+ [alias]
26
+ slugs = ["spycloud"] # worlds that store personal fields as sha256:<slug>:<value>
27
+ public_layer_wins = true # a `role: public` seed is never rewritten, even inside a private email's domain
28
+ public_mailbox_domains = ["gmail.com"] # kept real in an email persona; omit for the built-in free-mail list, [] for none
29
+ mint_inbound = ["email", "phone", "ip"] # kinds minted ON SIGHT in results; omit = seeds only
30
+ legend = "{run_dir}/legend.json" # the owner's way back: run key + every persona, written at run_end
31
+
32
+ [vendors]
33
+ spycloud = "spycloud_.*" # tool-name patterns -> a vendor label for `vendor = ...` matchers
34
+
35
+ [[hooks.pre_tool_call]] # or [[hooks.PreToolUse]] — Claude Code's names are accepted
36
+ matcher = "spycloud_.* | web_search" # `A | B` alternation of unanchored regexes; "" or "*" is every tool
37
+ handlers = [
38
+ { type = "alias" }, # persona -> real on the way out
39
+ { type = "command", command = "python guard.py", timeout = 10 }, # your hook: event on stdin, verdict on stdout
40
+ { type = "deny", reason = "not in this run" },
41
+ ]
42
+
43
+ [[hooks.post_tool_call]]
44
+ matcher = "spycloud_.* | web_search"
45
+ handlers = [
46
+ { type = "alias" }, # real -> persona on the way in, leaks metered
47
+ { type = "record", sink = "{run_dir}/transcript.jsonl", async = true },
48
+ ]
49
+
50
+ [[hooks.post_tool_call]] # a SECOND rule: one rewriter per rule, and rules chain
51
+ matcher = "web_search | web_fetch"
52
+ handlers = [{ type = "redact", kinds = ["phone"], values = ["Acme Holdings"], patterns = ["\\bDOB[: ]+\\S+"] }]
53
+
54
+ [[hooks.run_end]]
55
+ handlers = [{ type = "alias", check = "outgoing" }] # a real value in the report fails the run
56
+ ```
57
+
58
+ Events: `pre_tool_call`, `post_tool_call`, `pre_request`, `post_response`, `run_end`.
59
+ Handlers: `alias`, `command`, `http`, `callable`, `deny`, `record`, `redact`. A rule's handlers
60
+ all see the same event and at most one of them may rewrite it; put a second rewriter under its
61
+ own `[[hooks.<event>]]` — rules apply in order and each sees the previous one's rewrite.
62
+
63
+ ## The alias door
64
+
65
+ Seed it with the task's entities before the agent starts; the instruction the agent reads is
66
+ already in persona space, and every tool result is rewritten on the way in while every tool
67
+ call is resolved back to the real value on the way out.
68
+
69
+ ```json
70
+ [{ "type": "person_name", "value": "Matthew Nowell", "identity": "subject" },
71
+ { "type": "email", "value": "m.nowell@nowell-ltd.com", "identity": "subject" },
72
+ { "type": "domain", "value": "star-co.net.kp", "role": "public" }]
73
+ ```
74
+
75
+ Kinds: `person_name`, `email`, `username`, `phone`, `company`, `domain`, `ip`, `account`,
76
+ `machine`, `log`; anything else gets a `REF-nnnn` stand-in. `identity` ties attributes to one
77
+ person so they stay consistent; `role: "public"` is never replaced. Every variant of a value is
78
+ tracked (bare surname, handle spellings, `(at)` emails, phone formats, percent-encoding, a
79
+ world's `sha256:` stored form); what slips through is counted (`leak_through_inbound`), and a
80
+ real value in the outgoing report fails the run (`leaks_outbound`).
81
+
82
+ ## Identities that arrive, not seeded
83
+
84
+ A page or a vendor row brings people the seed list never named. By default they reach the
85
+ agent as they are. Two knobs change that:
86
+
87
+ - **`mint_inbound = ["email", "phone", "ip"]`** — an unseeded value of a listed kind met in a
88
+ result gets a persona on sight: aliased in, resolved back out on the next call, one persona
89
+ for the rest of the run whatever the spelling. Only these kinds are pattern-safe (a global
90
+ IP; a number with a `+` or an area code); a name or a handle is seeded, never guessed. The
91
+ whole result is read before any of it is rewritten, so a spelling in an earlier field is
92
+ caught by a later one. Listed in `found_inbound`.
93
+ - **`redact`** — removes instead of replacing, from ANY string a result carries (page body,
94
+ title, URL, vendor row): `kinds` for shaped values, `values` for arbitrary literals (a name,
95
+ a company, a phrase — any case, any whitespace), `patterns` for regular expressions;
96
+ `token` (default `[redacted {kind}]`) is what stands in. Runs after the door, leaves personas
97
+ alone, counted in `redactions` (kind and a three-letter prefix, never the value).
98
+
99
+ ## Per task, not per file
100
+
101
+ What a task aliases is the task's decision — one wants a persona for every address the web
102
+ returns, another's selectors are public IPs that must stay facts — so the run overrides the
103
+ file:
104
+
105
+ ```python
106
+ run = HookRun.from_config("gateway-hooks.toml", mint_inbound=["email"]) # this task only
107
+ run.seed(task["entities"] + task.get("replacements", [])) # values expected to surface, seeded early
108
+ run.on("post_tool_call", RedactHandler(run.alias, values=["Acme Holdings"]), matcher="web_.*")
109
+ run.mint("email", found_later) # one more persona, from code, any time
110
+ ```
111
+
112
+ ```ts
113
+ const run = await HookRun.fromConfig("gateway-hooks.toml", { mintInbound: [] }); // seeds only, whatever the file says
114
+ ```
115
+
116
+ ## Seeing the real data (the owner)
117
+
118
+ ```bash
119
+ gateway hooks legend runs/<run id>/ # persona -> real, with role, provenance, identity
120
+ gateway hooks reveal runs/<run id>/report.md # the file with every persona put back
121
+ gateway hooks reveal transcript.jsonl --legend .gateway/hooks/<session>/legend.json --out transcript.real.jsonl
122
+ ```
123
+
124
+ The run writes the legend where `[alias] legend` says (found personas included); a coding
125
+ agent's state dir keeps one beside `run.json` after every event. `reveal` puts every persona
126
+ spelling back in a JSON or text file; a `[redacted …]` token stays — redaction removed the
127
+ value, and its raw copy is a `record` sink placed before the `redact` rule. The legend maps
128
+ personas to people: keep it with the run key, out of version control, never beside world data.
129
+
130
+ ## Wiring
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`.
136
+ - **Claude Code / coding agents** — `.claude/settings.json`: `PreToolUse`, `PostToolUse` and
137
+ `Stop` entries whose command is `gateway hooks run`. State (run key + seeds) persists under
138
+ `--state`, `$GATEWAY_HOOKS_STATE`, else `.gateway/hooks/<session id>`. A coding agent shows the
139
+ model a result before its hook runs, so the inbound rewrite cannot reach it there (the
140
+ command says so: `rewrite reached nobody`); route such tools through the SDK or an MCP server
141
+ that wraps them.
142
+ - **Any transport** — `run.session(session, request_fn=...)` puts `pre_request` /
143
+ `post_response` around a client with its own auth.
144
+
145
+ ## Check before wiring
146
+
147
+ ```bash
148
+ gateway hooks check gateway-hooks.toml --event PreToolUse --tool Bash --input '{"command":"ls"}'
149
+ gateway hooks check gateway-hooks.toml --seed @entities.json --tool web_search --input '{"query":"Keith Yarrow"}'
150
+ ```
151
+
152
+ `check` builds every handler (a callable that does not import, a bad pattern, two rewriters on
153
+ one rule fail here, not mid-run) and prints what each would do to one event. `--json` adds the
154
+ run's meters: aliases, substitutions, leaks, found identities, redactions, denials, hook errors.
@@ -337,7 +337,7 @@ SDK: `openSession(slug, { task: spec })` (TS), `open_session(slug, spec)` (Pytho
337
337
  sessions open it by id and grades attribute to the task and its version:
338
338
 
339
339
  ```bash
340
- gateway worlds task create task.json --world x # version 1; --name overrides the spec's name
340
+ gateway worlds task create task.json --world x # version 1; --name overrides the spec's name; --replace: a taken name becomes its next version
341
341
  gateway worlds task list --world x --metadata externalUserId=u_42
342
342
  gateway worlds task show <TASK_ID> [--version 2] # spec + version history
343
343
  gateway worlds task validate <TASK_ID> # seed/grader entities against the pinned world's version
@@ -403,14 +403,14 @@ client is the agent. Dependency tools are `<alias>.<tool>`, each world grades on
403
403
  ```bash
404
404
  gateway worlds serve ./whatsapp --task escalate_locked_account --port 8080 # prints {task, prompt, tools, verifiers, worlds}
405
405
  curl -s localhost:8080/__session/task # + contracts: each tool's description and input schema
406
- curl -s -X POST localhost:8080/__session/call -d '{"tool":"slack.post_message","args":{...}}'
407
406
  gateway worlds call http://localhost:8080 list_conversations --state --grade # act from the CLI, read state, grade
408
407
  gateway worlds call http://localhost:8080 slack.list_channels --args '{...}' --close # end it; the serve process exits
409
408
  ```
410
409
 
411
- `GET /__session/{task,tools,state}`, `POST /__session/{call,grade,reset,seed,close}`. `--task`
412
- and `--scenario` belong to `serve`; `worlds call <url>` refuses them. A directory target
413
- (`worlds call ./x <tool>`) opens and closes its own session per call instead.
410
+ `GET /__session/{task,tools,state}`, `POST /__session/{call,grade,reset,seed,close}`; `--task` and
411
+ `--scenario` belong to `serve`. A directory target (`worlds call ./x <tool>`) opens and closes its
412
+ own session per call. A HOSTED session is not a served url (the World Host serves no `/__session/*`;
413
+ its `api.url` takes the session's bearer): act on it by id, `gateway worlds call <sessionId> <tool> --state --grade --close`.
414
414
 
415
415
  ## 7. Run and grade
416
416
 
@@ -272,8 +272,9 @@ def build_default(world: str | Path, contract: Contract, *, force: bool = False)
272
272
  fail(
273
273
  "snapshot_pinned",
274
274
  f"{DEFAULT_DIR}/{PIN} pins the hosted snapshot {digest}, which is not in the tree: "
275
- f"fetch the world with its snapshot (load_world_to_sandbox, gateway worlds pull) "
276
- f"or remove the pin to rebuild from the data files",
275
+ f"run the world on the platform (`gateway worlds session open <slug>`, "
276
+ f"load_world_to_sandbox), which serves that snapshot, or remove {DEFAULT_DIR}/{PIN} "
277
+ f"to rebuild from the data files",
277
278
  f"/{DEFAULT_DIR}/{SNAPSHOT}",
278
279
  )
279
280
  return kept
@@ -356,9 +357,9 @@ def check_all(world: str | Path, contract: Contract) -> dict:
356
357
  # refused: authoring edits journals and opens the world, and a served world
357
358
  # replays the journals past a stale snapshot (WorldState opens only a
358
359
  # current one). `stale` is in every check report so it never passes unseen.
359
- found["default"]["stale"] = (
360
- pinned_default(world) is None and found["default"]["batchDigest"] != default_batch_digest(world)
361
- )
360
+ found["default"]["stale"] = pinned_default(world) is None and found["default"][
361
+ "batchDigest"
362
+ ] != default_batch_digest(world)
362
363
  for name in scenario_dirs(world):
363
364
  snapshot = scenario_snapshot(world, name)
364
365
  if snapshot.is_file() or sidecar_path(snapshot).is_file():
@@ -105,10 +105,20 @@ class TaskSpec:
105
105
  return list(dict.fromkeys(named))
106
106
 
107
107
 
108
+ #: Keys a state dump carries beside its entities, which a grader reads like an
109
+ #: entity: ``calls`` (the session's call log) and ``snapshot``. A world cannot
110
+ #: declare an entity by either name (the compiler refuses it), so a check on
111
+ #: one is never a typo for a row entity; a seed may not target them.
112
+ RESERVED_STATE_KEYS = frozenset({"calls", "snapshot"})
113
+
114
+
108
115
  def unknown_task_entities(spec: TaskSpec, defined: Iterable[str]) -> list[str]:
109
- """The entities ``spec`` names that ``defined`` (a world contract's) lacks."""
116
+ """The entities ``spec`` names that ``defined`` (a world contract's) lacks.
117
+ A grader's check on a reserved state key is not one of them."""
110
118
  known = set(defined)
111
- return [entity for entity in spec.entities() if entity not in known]
119
+ seeded = set((spec.seed or {}).get("rows", {})) if isinstance(spec.seed, dict) else set()
120
+ return [entity for entity in spec.entities()
121
+ if entity not in known and not (entity in RESERVED_STATE_KEYS and entity not in seeded)]
112
122
 
113
123
 
114
124
  def parse_task_spec(value: Any) -> TaskSpec:
@@ -53,14 +53,21 @@ from pathlib import Path
53
53
 
54
54
  #: Address space a worker may use, in MiB, unless ``WORLDS_WORKER_MEMORY_MB`` says otherwise.
55
55
  DEFAULT_WORKER_MEMORY_MB = 2048
56
- #: Address space every worker together may use, in MiB, unless
56
+ #: Memory every worker together may use, in MiB, unless
57
57
  #: ``WORLDS_WORKER_BUDGET_MB`` says otherwise. The number of workers a replica
58
- #: runs at once is this over the per-worker cap: two of 2 GiB inside the 6 GiB
59
- #: host container, the rest the supervisor's (its caches, the sessions it
60
- #: serves in-process, exports in flight). A version past that is refused
61
- #: ``at_capacity`` and placed on another replica instead of the kernel
62
- #: choosing which process to kill.
58
+ #: runs at once is this over the footprint each is counted at. A version past
59
+ #: that is refused ``at_capacity`` and placed on another replica instead of
60
+ #: the kernel choosing which process to kill.
63
61
  DEFAULT_WORKER_BUDGET_MB = 4096
62
+ #: What one worker is counted at against the budget, in MiB, unless
63
+ #: ``WORLDS_WORKER_FOOTPRINT_MB`` says otherwise. Unset, a worker is counted at
64
+ #: its whole address-space cap — two of 2 GiB inside a 6 GiB container — which
65
+ #: is the safe reading and a 50x over-reservation: a measured worker holding
66
+ #: sessions is ~40 MiB resident (prod, 2026-09-17). A fleet that must host many
67
+ #: worlds at once sets this to the footprint it has measured, keeps the
68
+ #: address-space cap as the rail each worker cannot cross, and sizes the
69
+ #: container for footprint x workers plus the supervisor's share.
70
+ DEFAULT_WORKER_FOOTPRINT_MB: int | None = None
64
71
  #: Largest file a worker may write (its session databases), in MiB.
65
72
  DEFAULT_WORKER_FILE_MB = 4096
66
73
  #: Open files per worker: one per live session plus the sockets serving them.
@@ -348,13 +355,22 @@ class WorkerPool:
348
355
  worlds_domain: str,
349
356
  memory_mb: int = DEFAULT_WORKER_MEMORY_MB,
350
357
  budget_mb: int = DEFAULT_WORKER_BUDGET_MB,
358
+ footprint_mb: int | None = DEFAULT_WORKER_FOOTPRINT_MB,
351
359
  idle_s: float = DEFAULT_WORKER_IDLE_S,
352
360
  python: str = sys.executable,
353
361
  ):
354
- if budget_mb < memory_mb:
362
+ if footprint_mb is None:
363
+ footprint_mb = memory_mb
364
+ if footprint_mb <= 0 or footprint_mb > memory_mb:
355
365
  raise ValueError(
356
- f"the worker budget ({budget_mb} MiB) holds no worker of {memory_mb} MiB "
357
- "(WORLDS_WORKER_BUDGET_MB, WORLDS_WORKER_MEMORY_MB)"
366
+ f"a worker's footprint ({footprint_mb} MiB) must be between 1 MiB and its "
367
+ f"address-space cap ({memory_mb} MiB) (WORLDS_WORKER_FOOTPRINT_MB, "
368
+ "WORLDS_WORKER_MEMORY_MB)"
369
+ )
370
+ if budget_mb < footprint_mb:
371
+ raise ValueError(
372
+ f"the worker budget ({budget_mb} MiB) holds no worker of {footprint_mb} MiB "
373
+ "(WORLDS_WORKER_BUDGET_MB, WORLDS_WORKER_FOOTPRINT_MB)"
358
374
  )
359
375
  self.root = Path(cache_root)
360
376
  self.workers_root = self.root / "workers"
@@ -365,8 +381,9 @@ class WorkerPool:
365
381
  self.worlds_domain = worlds_domain
366
382
  self.memory_mb = memory_mb
367
383
  self.budget_mb = budget_mb
368
- #: Workers live at once: the budget's worth of per-worker address space.
369
- self.max_workers = budget_mb // memory_mb
384
+ self.footprint_mb = footprint_mb
385
+ #: Workers live at once: the budget's worth of footprints.
386
+ self.max_workers = budget_mb // footprint_mb
370
387
  self.idle_s = idle_s
371
388
  self.python = python
372
389
  self._lock = threading.Lock()
@@ -403,8 +420,8 @@ class WorkerPool:
403
420
  self._workers.pop(spare.pop(0).version_id).stop()
404
421
  if len(self._workers) >= self.max_workers:
405
422
  raise WorkerCapacity(
406
- f"this host's {self.max_workers} version workers ({self.budget_mb} MiB of "
407
- f"{self.memory_mb} MiB each) all hold sessions; place elsewhere"
423
+ f"this host's {self.max_workers} version workers ({self.budget_mb} MiB at "
424
+ f"{self.footprint_mb} MiB each) all hold sessions; place elsewhere"
408
425
  )
409
426
 
410
427
  def peek(self, version_id: str) -> Worker | None: