@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.
- package/dist/cli.js +11992 -4572
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +11998 -4578
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +71 -31
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +59 -20
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -0
- package/dist/hooks/index.d.ts +1 -0
- package/dist/hooks/index.js +4355 -0
- package/dist/hooks/index.js.map +1 -0
- package/dist/hooks/index.mjs +4243 -0
- package/dist/hooks/index.mjs.map +1 -0
- package/dist/{index-Dpo-t8iO.d.ts → index-1xnxt0Cc.d.ts} +58 -2
- package/dist/index-B0R3IgsV.d.mts +1279 -0
- package/dist/index-B0R3IgsV.d.ts +1279 -0
- package/dist/{index-B5HUQQDE.d.mts → index-C1wDEwH4.d.mts} +58 -2
- package/dist/index.d.mts +4 -3
- package/dist/index.d.ts +4 -3
- package/dist/index.js +6547 -1552
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +6636 -1655
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +60 -20
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +51 -12
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +46 -3
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +41 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +371 -6
- package/dist/worlds/index.d.ts +371 -6
- package/dist/worlds/index.js +2061 -235
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +2050 -224
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/_materialize.py +3 -3
- package/runtime/gatewaysdk/environment/schema/api.py +116 -2
- package/runtime/gatewaysdk/environment/schema/compiler.py +14 -0
- package/runtime/gatewaysdk/environment/schema/host.py +37 -11
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +154 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +5 -5
- package/runtime/gatewaysdk/environment/schema/snapshot.py +6 -5
- package/runtime/gatewaysdk/environment/schema/tasks.py +12 -2
- package/runtime/gatewaysdk/environment/schema/workers.py +30 -13
- package/skills/hooks-getting-started/SKILL.md +154 -0
- 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.
|
|
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:
|
|
41
|
-
"
|
|
42
|
-
"
|
|
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 = {
|
|
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
|
-
|
|
1657
|
-
|
|
1658
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
2480
|
-
``WORLDS_WORKER_BUDGET_MB`` all of them together
|
|
2481
|
-
|
|
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}
|
|
412
|
-
|
|
413
|
-
|
|
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"
|
|
276
|
-
f"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#:
|
|
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
|
|
59
|
-
#:
|
|
60
|
-
#:
|
|
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
|
|
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"
|
|
357
|
-
"(
|
|
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
|
-
|
|
369
|
-
|
|
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
|
|
407
|
-
f"{self.
|
|
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:
|