@withgateway/sdk 0.3.3 → 0.6.0
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/README.md +4 -3
- package/dist/cli.js +3005 -1401
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2996 -1392
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +128 -37
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +126 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
- package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1078 -260
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1040 -251
- package/dist/index.mjs.map +1 -1
- package/dist/replay/index.d.mts +1 -1
- package/dist/replay/index.d.ts +1 -1
- package/dist/replay/index.js.map +1 -1
- package/dist/replay/index.mjs.map +1 -1
- package/dist/traces/index.js +125 -34
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +123 -32
- 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 +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +819 -438
- package/dist/worlds/index.d.ts +819 -438
- package/dist/worlds/index.js +912 -236
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +908 -232
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +82 -66
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +198 -474
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
- package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
- package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
- package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
- package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
- package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
- package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
- package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +32 -116
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
- package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
- package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +50 -28
- package/skills/connector-schema-authoring/connector-worlds.md +282 -18
- package/skills/connector-schema-authoring/world-schema.md +7 -6
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +20 -22
- package/skills/worlds-getting-started/SKILL.md +25 -25
- package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
package/package.json
CHANGED
|
@@ -18,6 +18,7 @@ import importlib.util
|
|
|
18
18
|
import inspect
|
|
19
19
|
import sys
|
|
20
20
|
import uuid
|
|
21
|
+
from contextlib import ExitStack
|
|
21
22
|
from dataclasses import dataclass, field
|
|
22
23
|
from pathlib import Path
|
|
23
24
|
from typing import Any, Callable, Dict, List, Optional
|
|
@@ -124,8 +125,8 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
|
|
|
124
125
|
handler_files = sorted(tools_dir.glob("*.py")) if tools_dir.is_dir() else []
|
|
125
126
|
load_token = runtime._load_registry.set(registry)
|
|
126
127
|
strict_token = runtime._strict_registration.set(contract is not None)
|
|
127
|
-
|
|
128
|
-
|
|
128
|
+
installed = ExitStack()
|
|
129
|
+
installed.enter_context(runtime.installed(runtime))
|
|
129
130
|
# Generated bundles use intra-bundle imports ("from tools._db import …"),
|
|
130
131
|
# so the bundle root must be importable for the load's dynamic extent.
|
|
131
132
|
bundle_root = str(bundle_path)
|
|
@@ -158,10 +159,7 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
|
|
|
158
159
|
modules.append(module)
|
|
159
160
|
modules_by_stem[handler_file.stem] = module
|
|
160
161
|
finally:
|
|
161
|
-
|
|
162
|
-
sys.modules["gateway_env"] = saved
|
|
163
|
-
else:
|
|
164
|
-
sys.modules.pop("gateway_env", None)
|
|
162
|
+
installed.close()
|
|
165
163
|
if path_added:
|
|
166
164
|
try:
|
|
167
165
|
sys.path.remove(bundle_root)
|
|
@@ -2,11 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
import sys
|
|
6
5
|
from pathlib import Path
|
|
7
|
-
from tempfile import TemporaryDirectory
|
|
8
6
|
|
|
9
|
-
from ._bundle import load_handlers, parse_manifest
|
|
10
7
|
from .errors import WorldStartError
|
|
11
8
|
from .legacy_sqlite import materialize
|
|
12
9
|
from .schema import WorldDatabase, bundle_mode, check_bundle
|
|
@@ -29,16 +26,16 @@ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool =
|
|
|
29
26
|
|
|
30
27
|
|
|
31
28
|
def _materialize_schema(bundle: Path, destination: Path) -> dict | None:
|
|
32
|
-
from .schema.snapshot import
|
|
29
|
+
from .schema.snapshot import held_default, refuse_unheld_pin
|
|
33
30
|
|
|
34
31
|
contract = check_bundle(bundle)
|
|
35
32
|
if destination.exists():
|
|
36
33
|
raise ContractError("state_exists", "Refusing to overwrite an existing template")
|
|
37
|
-
|
|
38
|
-
if
|
|
34
|
+
held = held_default(bundle, contract)
|
|
35
|
+
if held is not None:
|
|
39
36
|
# The compiled snapshot holds rows this contract may open; whether they are proven is the caller's (ProvenTemplate).
|
|
40
|
-
WorldDatabase.clone_file(
|
|
41
|
-
return
|
|
37
|
+
WorldDatabase.clone_file(held[0], destination)
|
|
38
|
+
return held[1]
|
|
42
39
|
refuse_unheld_pin(bundle, contract)
|
|
43
40
|
initial = read_json(bundle / "data/initial.json")
|
|
44
41
|
refuse_initial_rows(contract, initial)
|
|
@@ -102,20 +99,3 @@ def refuse_initial_rows(contract: Contract, initial: object) -> None:
|
|
|
102
99
|
}
|
|
103
100
|
row = initial["mutations"][first["index"]].get("value")
|
|
104
101
|
raise_shape_refusal(contract, first, row, summary, context, first["pointer"])
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
def validate_schema_materialization(bundle: Path) -> None:
|
|
108
|
-
"""Validate compiled artifacts and initial state without retaining a database."""
|
|
109
|
-
bundle = Path(bundle)
|
|
110
|
-
write_bytecode = sys.dont_write_bytecode
|
|
111
|
-
sys.dont_write_bytecode = True
|
|
112
|
-
try:
|
|
113
|
-
load_handlers(bundle, parse_manifest(bundle))
|
|
114
|
-
finally:
|
|
115
|
-
sys.dont_write_bytecode = write_bytecode
|
|
116
|
-
with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
|
|
117
|
-
materialize_template(
|
|
118
|
-
bundle,
|
|
119
|
-
Path(directory) / "template.db",
|
|
120
|
-
require_sql=True,
|
|
121
|
-
)
|
|
@@ -1,11 +1,3 @@
|
|
|
1
|
-
"""Worlds — deterministic instances of a mock-tools environment's seeded state.
|
|
2
|
-
|
|
3
|
-
A world is one database file, branched (file-copied) from the environment's
|
|
4
|
-
prepared template, plus the seams that let an agent's tool calls execute
|
|
5
|
-
against it: ``execute``, ``as_registry`` (the exact replay ``ToolStubRegistry``
|
|
6
|
-
mapping contract), ``wrap_tools``, and grading (``verify`` / ``state``).
|
|
7
|
-
"""
|
|
8
|
-
|
|
9
1
|
from __future__ import annotations
|
|
10
2
|
|
|
11
3
|
import time
|
|
@@ -26,30 +18,25 @@ from .score import Score
|
|
|
26
18
|
|
|
27
19
|
if TYPE_CHECKING: # pragma: no cover
|
|
28
20
|
from .core import Environment
|
|
21
|
+
from .schema.journal import JournalUse, WorldJournal
|
|
29
22
|
from .schema.session_files import ProvenTemplate, SessionExport
|
|
23
|
+
from .schema.webhooks import WebhookOutbox, Webhooks
|
|
30
24
|
|
|
31
25
|
|
|
32
26
|
@dataclass
|
|
33
27
|
class VerifierResult:
|
|
34
|
-
"""
|
|
35
|
-
scores are their own category, never coerced to 0) and yields
|
|
36
|
-
``passed=None``; otherwise ``passed = score >= 1.0``."""
|
|
28
|
+
"""``passed`` is ``score >= 1.0``; a ``None`` score is ungraded, never 0, and has ``passed=None``."""
|
|
37
29
|
|
|
38
30
|
name: str
|
|
39
31
|
passed: Optional[bool]
|
|
40
32
|
score: Optional[float]
|
|
41
33
|
detail: str = ""
|
|
42
34
|
rewards: Dict[str, float] = field(default_factory=dict)
|
|
35
|
+
closed: Optional[str] = None
|
|
43
36
|
|
|
44
37
|
|
|
45
38
|
class SqlVerifier:
|
|
46
|
-
"""
|
|
47
|
-
rule every reader applies — ``schema check``, a local session's grade, the
|
|
48
|
-
World Host's grade. Statements run in order; the score is the first column
|
|
49
|
-
of the first row of the LAST statement that returns rows (or could). No
|
|
50
|
-
rows / NULL → ``None``, never coerced to 0; a value that is not a number
|
|
51
|
-
is a :class:`VerifierError` naming it, and so is a score that is not one
|
|
52
|
-
from 0 to 1 (:class:`Score`; earlier statements may count rows)."""
|
|
39
|
+
"""Every reader's score rule, pinned by ``sql-verifier-vectors.json``: NULL or no rows is ``None``, never 0."""
|
|
53
40
|
|
|
54
41
|
def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
|
|
55
42
|
self.name = name[:-4] if name.endswith(".sql") else name
|
|
@@ -57,14 +44,9 @@ class SqlVerifier:
|
|
|
57
44
|
|
|
58
45
|
@classmethod
|
|
59
46
|
def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
|
|
60
|
-
"""``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
|
|
61
47
|
return cls(path.stem, path.read_text(encoding="utf-8"), split)
|
|
62
48
|
|
|
63
49
|
def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
|
|
64
|
-
"""Run every statement through ``execute`` (rows, or ``None`` for a
|
|
65
|
-
statement that returns none, e.g. a temp-table DDL) and answer
|
|
66
|
-
``(score, sql)`` — the score and the statement it came from, both
|
|
67
|
-
``None`` when nothing returned rows."""
|
|
68
50
|
value: Any = None
|
|
69
51
|
last_sql: Optional[str] = None
|
|
70
52
|
for statement in self.statements:
|
|
@@ -92,18 +74,12 @@ _NO_INPUT = object()
|
|
|
92
74
|
|
|
93
75
|
|
|
94
76
|
def _stub_input(tool_input: Any, kwargs: Dict[str, Any]) -> Any:
|
|
95
|
-
"""One rule for callable seams: an explicit positional input (even None)
|
|
96
|
-
is the input; keyword arguments are the input; nothing means omitted."""
|
|
97
77
|
if tool_input is not _NO_INPUT:
|
|
98
78
|
return tool_input
|
|
99
79
|
return kwargs if kwargs else _NO_INPUT
|
|
100
80
|
|
|
101
81
|
|
|
102
82
|
class WorldRegistry(StubRegistryMapping):
|
|
103
|
-
"""``world.as_registry()`` — the replay registry contract (mapping with
|
|
104
|
-
``__missing__``, ``lookup``, ``call_log``/``called_names``) backed by the
|
|
105
|
-
live env world instead of recordings."""
|
|
106
|
-
|
|
107
83
|
def __init__(self, world: "World") -> None:
|
|
108
84
|
self._world = world
|
|
109
85
|
|
|
@@ -129,14 +105,6 @@ class WorldRegistry(StubRegistryMapping):
|
|
|
129
105
|
|
|
130
106
|
|
|
131
107
|
class World:
|
|
132
|
-
"""One live, isolated instance of the environment's seeded state.
|
|
133
|
-
|
|
134
|
-
``template`` is a version's :class:`~.schema.session_files.ProvenTemplate`:
|
|
135
|
-
the world starts from it, and resets to it, with the contract and DDL check
|
|
136
|
-
and no row audit. Without one the world copies its environment's own
|
|
137
|
-
template and audits every row on each open and reset; a ``snapshot`` file
|
|
138
|
-
to start from is always audited."""
|
|
139
|
-
|
|
140
108
|
def __init__(
|
|
141
109
|
self,
|
|
142
110
|
env: "Environment",
|
|
@@ -147,12 +115,17 @@ class World:
|
|
|
147
115
|
) -> None:
|
|
148
116
|
self.env = env
|
|
149
117
|
self.id = world_id or uuid.uuid4().hex[:8]
|
|
150
|
-
self.db_path: Path = env._worlds_dir
|
|
118
|
+
self.db_path: Path = self.database_file(env._worlds_dir, self.id)
|
|
151
119
|
self.call_log: List[Dict[str, Any]] = []
|
|
152
120
|
self._template = self._proven(template)
|
|
153
121
|
self.contract = template.contract if template is not None else self._bundle_contract()
|
|
154
122
|
source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
|
|
155
123
|
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
124
|
+
self.webhooks = self._webhook_outbox(None)
|
|
125
|
+
|
|
126
|
+
@staticmethod
|
|
127
|
+
def database_file(directory: Path, world_id: str) -> Path:
|
|
128
|
+
return Path(directory) / f"world-{world_id}.db"
|
|
156
129
|
|
|
157
130
|
@staticmethod
|
|
158
131
|
def _proven(template: Any) -> Any:
|
|
@@ -162,24 +135,40 @@ class World:
|
|
|
162
135
|
|
|
163
136
|
return ProvenTemplate.required(template)
|
|
164
137
|
|
|
138
|
+
def serve_webhooks(self, webhooks: "Webhooks | None") -> None:
|
|
139
|
+
"""Deliveries this world's tools stage go to the subscriptions ``webhooks`` declares."""
|
|
140
|
+
if webhooks is not None and self.contract is not None:
|
|
141
|
+
webhooks.check_contract(self.contract.entities)
|
|
142
|
+
self.webhooks = self._webhook_outbox(webhooks if self.contract is not None else None)
|
|
143
|
+
|
|
144
|
+
def _webhook_outbox(self, webhooks: "Webhooks | None") -> "WebhookOutbox":
|
|
145
|
+
from .schema.api import ApiContext
|
|
146
|
+
from .schema.primary_key import PrimaryKey
|
|
147
|
+
from .schema.webhooks import WebhookOutbox
|
|
148
|
+
|
|
149
|
+
return WebhookOutbox(
|
|
150
|
+
webhooks,
|
|
151
|
+
lambda entity: list(self.store.list(entity)),
|
|
152
|
+
lambda entity, row: PrimaryKey.in_contract(self.contract, entity).key(row),
|
|
153
|
+
ApiContext.clock,
|
|
154
|
+
)
|
|
155
|
+
|
|
165
156
|
def _bundle_contract(self) -> Any:
|
|
166
157
|
from .schema import bundle_mode, check_bundle
|
|
167
158
|
|
|
168
159
|
return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
|
|
169
160
|
|
|
170
161
|
def _seed(self) -> "tuple[Path, bool]":
|
|
171
|
-
"""The file a fresh or reset world copies, and whether its rows are audited."""
|
|
172
162
|
if self._template is None:
|
|
173
163
|
return Path(self.env._template_db), True
|
|
174
164
|
return self._template.path, False
|
|
175
165
|
|
|
176
166
|
@property
|
|
177
167
|
def store(self):
|
|
178
|
-
"""
|
|
168
|
+
"""``None`` for a contract-less mock-tools world."""
|
|
179
169
|
return self._backing.store
|
|
180
170
|
|
|
181
171
|
def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
182
|
-
"""Execute atomically in schema mode, validating both input and output."""
|
|
183
172
|
from .schema.validation import validate
|
|
184
173
|
|
|
185
174
|
handler = self.env._handlers.get(tool_name)
|
|
@@ -187,7 +176,7 @@ class World:
|
|
|
187
176
|
raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
|
|
188
177
|
supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
|
|
189
178
|
started = time.perf_counter()
|
|
190
|
-
with self._backing.transaction():
|
|
179
|
+
with self.webhooks.transaction(), self._backing.transaction():
|
|
191
180
|
if self.contract is not None:
|
|
192
181
|
validate(
|
|
193
182
|
self.contract.tools[tool_name]["input_schema"],
|
|
@@ -196,6 +185,7 @@ class World:
|
|
|
196
185
|
)
|
|
197
186
|
token = runtime._active_connection.set(self._backing.handler_connection())
|
|
198
187
|
store_token = runtime._active_store.set(self.store)
|
|
188
|
+
webhooks_token = runtime._active_webhooks.set(self.webhooks)
|
|
199
189
|
try:
|
|
200
190
|
if isinstance(supplied, Mapping):
|
|
201
191
|
result = handler(**supplied)
|
|
@@ -212,6 +202,7 @@ class World:
|
|
|
212
202
|
finally:
|
|
213
203
|
runtime._active_connection.reset(token)
|
|
214
204
|
runtime._active_store.reset(store_token)
|
|
205
|
+
runtime._active_webhooks.reset(webhooks_token)
|
|
215
206
|
duration_ms = (time.perf_counter() - started) * 1000.0
|
|
216
207
|
self.call_log.append({"tool": tool_name, "match": "env", "input": supplied})
|
|
217
208
|
self.env._record_route(tool_name, "env", duration_ms, self.id)
|
|
@@ -236,14 +227,10 @@ class World:
|
|
|
236
227
|
)
|
|
237
228
|
|
|
238
229
|
def as_registry(self) -> WorldRegistry:
|
|
239
|
-
"""
|
|
240
|
-
identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
|
|
230
|
+
"""Drop-in for agent tool layers, with the contract of replay's ``ToolStubRegistry.as_registry()``."""
|
|
241
231
|
return WorldRegistry(self)
|
|
242
232
|
|
|
243
233
|
def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
|
|
244
|
-
"""Substitute env-served callables by name in a list/dict of tools;
|
|
245
|
-
everything not served (or not env-routed) passes through unchanged."""
|
|
246
|
-
|
|
247
234
|
def routed_to_env(name: Optional[str]) -> bool:
|
|
248
235
|
return bool(name) and name in self.env._handlers and self.env.resolve_route(name) == "env"
|
|
249
236
|
|
|
@@ -265,11 +252,11 @@ class World:
|
|
|
265
252
|
return wrapped
|
|
266
253
|
|
|
267
254
|
def reset(self) -> None:
|
|
268
|
-
"""Back to the seed, in place (same world instance)."""
|
|
269
255
|
if self._template is None:
|
|
270
256
|
self._refuse_a_changed_contract()
|
|
271
257
|
source, audit = self._seed()
|
|
272
258
|
self._relay(source, audit=audit)
|
|
259
|
+
self.webhooks.clear()
|
|
273
260
|
|
|
274
261
|
def _refuse_a_changed_contract(self) -> None:
|
|
275
262
|
"""An environment's bundle can change under a live world; a version's cannot."""
|
|
@@ -281,14 +268,11 @@ class World:
|
|
|
281
268
|
raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
|
|
282
269
|
|
|
283
270
|
def restore(self, source: Union[str, Path]) -> None:
|
|
284
|
-
"""
|
|
285
|
-
A schema-backed world audits it against its contract row by row, as it would
|
|
286
|
-
any file it did not write."""
|
|
271
|
+
"""Audited row by row: the file is not one this store wrote."""
|
|
287
272
|
self._relay(Path(source), audit=True)
|
|
288
273
|
|
|
289
274
|
def resume(self, export: "SessionExport") -> None:
|
|
290
|
-
"""
|
|
291
|
-
the sha256 recorded when the store wrote them, without a second row audit."""
|
|
275
|
+
"""No second row audit: a :class:`SessionExport` is digest-verified or this session's own recovered store."""
|
|
292
276
|
from .schema.session_files import SessionExport
|
|
293
277
|
|
|
294
278
|
self._relay(SessionExport.required(export).path, audit=False)
|
|
@@ -298,39 +282,43 @@ class World:
|
|
|
298
282
|
self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
|
|
299
283
|
|
|
300
284
|
def snapshot(self, destination: Union[str, Path]) -> Path:
|
|
301
|
-
"""Pin this world's current state to a file (for debugging fixtures)."""
|
|
302
285
|
return self._backing.snapshot(Path(destination))
|
|
303
286
|
|
|
304
287
|
def close(self) -> None:
|
|
305
288
|
self._backing.close()
|
|
306
289
|
|
|
307
290
|
def set_task_context(self, scenario_id: str) -> bool:
|
|
308
|
-
"""
|
|
291
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
309
292
|
return self._backing.set_task_context(scenario_id)
|
|
310
293
|
|
|
311
294
|
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
312
|
-
"""
|
|
295
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
313
296
|
return self._backing.set_run_parameters(parameters)
|
|
314
297
|
|
|
315
298
|
def record_conversation_event(
|
|
316
|
-
self,
|
|
299
|
+
self,
|
|
300
|
+
scenario_id: str,
|
|
301
|
+
user_turn_index: int,
|
|
302
|
+
event_type: str,
|
|
303
|
+
actor: str,
|
|
304
|
+
name: Optional[str],
|
|
305
|
+
payload_json: str,
|
|
317
306
|
) -> bool:
|
|
318
|
-
"""
|
|
307
|
+
"""``False`` when a mock-tools world does not declare the table."""
|
|
319
308
|
return self._backing.record_conversation_event(
|
|
320
309
|
scenario_id, user_turn_index, event_type, actor, name, payload_json
|
|
321
310
|
)
|
|
322
311
|
|
|
323
312
|
def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
|
|
324
|
-
"""Read-only SQL against the world's db (SELECT/WITH only)."""
|
|
325
313
|
return self._backing.rows(sql, params)
|
|
326
314
|
|
|
327
|
-
def verify(self, name: str) -> VerifierResult:
|
|
328
|
-
"""
|
|
315
|
+
def verify(self, name: str, journal: Optional["WorldJournal"] = None) -> VerifierResult:
|
|
316
|
+
"""NULL or no rows scores ``None``, never 0. A verifier that read the journal fails closed when none was
|
|
317
|
+
recorded, and on an incomplete one unless ``gateway-env.toml`` declares
|
|
318
|
+
``[verifiers.<name>] accepts_incomplete_journal = true``."""
|
|
319
|
+
from .schema.journal import JournalDatabase, WorldJournal
|
|
320
|
+
from .schema.validation import ContractError
|
|
329
321
|
|
|
330
|
-
:class:`SqlVerifier` is the rule: the first column of the first row of
|
|
331
|
-
the LAST row-returning statement. NULL / no rows → score None (passed
|
|
332
|
-
None) — never coerced to 0.
|
|
333
|
-
"""
|
|
334
322
|
verifier_name = name[:-4] if name.endswith(".sql") else name
|
|
335
323
|
path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
|
|
336
324
|
if not path.is_file():
|
|
@@ -340,7 +328,20 @@ class World:
|
|
|
340
328
|
def execute(statement: str) -> Optional[List[Any]]:
|
|
341
329
|
return self._backing.verifier_rows(verifier_name, statement)
|
|
342
330
|
|
|
343
|
-
|
|
331
|
+
database = JournalDatabase(journal or WorldJournal.unrecorded(), self.db_path.parent / "journal")
|
|
332
|
+
verifier = SqlVerifier.read(path, self._backing.split_statements)
|
|
333
|
+
with self._backing.journal(database) as used:
|
|
334
|
+
try:
|
|
335
|
+
score, last_sql = verifier.score(execute)
|
|
336
|
+
except (ContractError, VerifierError):
|
|
337
|
+
closed = self._closed_on(verifier_name, database.journal, used(verifier.statements))
|
|
338
|
+
if closed is None:
|
|
339
|
+
raise
|
|
340
|
+
return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
|
|
341
|
+
use = used(verifier.statements)
|
|
342
|
+
closed = self._closed_on(verifier_name, database.journal, use)
|
|
343
|
+
if closed is not None:
|
|
344
|
+
return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
|
|
344
345
|
if last_sql is None:
|
|
345
346
|
detail = "no row-returning statement — score is null"
|
|
346
347
|
elif score is None:
|
|
@@ -349,3 +350,18 @@ class World:
|
|
|
349
350
|
detail = f"score {score} from: {last_sql}"
|
|
350
351
|
passed = None if score is None else score >= 1.0
|
|
351
352
|
return VerifierResult(name=verifier_name, passed=passed, score=score, detail=detail)
|
|
353
|
+
|
|
354
|
+
def _closed_on(self, verifier: str, journal: "WorldJournal", use: "JournalUse") -> Optional[str]:
|
|
355
|
+
from .schema.journal import accepting_incomplete
|
|
356
|
+
|
|
357
|
+
gap = journal.gap(use)
|
|
358
|
+
if gap is None:
|
|
359
|
+
return None
|
|
360
|
+
if not journal.recorded:
|
|
361
|
+
return f"{gap}: verifier '{verifier}' reads the journal"
|
|
362
|
+
if verifier in accepting_incomplete(self.env.bundle_path):
|
|
363
|
+
return None
|
|
364
|
+
return (
|
|
365
|
+
f"{gap}: verifier '{verifier}' reads the journal; declare "
|
|
366
|
+
f"[verifiers.{verifier}] accepts_incomplete_journal = true to grade an incomplete one"
|
|
367
|
+
)
|
|
@@ -1,29 +1,25 @@
|
|
|
1
|
-
"""What a :class:`~gatewaysdk.environment._world.World`'s state lives in: a
|
|
2
|
-
contract-bound world database, or the raw SQLite file of a contract-less
|
|
3
|
-
mock-tools world. The world asks its backing and never branches on which."""
|
|
4
|
-
|
|
5
1
|
from __future__ import annotations
|
|
6
2
|
|
|
7
3
|
from abc import ABC, abstractmethod
|
|
4
|
+
from collections.abc import Callable
|
|
8
5
|
from contextlib import AbstractContextManager
|
|
9
6
|
from pathlib import Path
|
|
10
|
-
from typing import Any, Dict, List, Optional
|
|
7
|
+
from typing import TYPE_CHECKING, Any, Dict, List, Optional
|
|
11
8
|
|
|
12
9
|
from .schema.compiler import Contract
|
|
13
10
|
from .schema.database import WorldDatabase
|
|
14
11
|
from .schema.validation import ContractError
|
|
15
12
|
|
|
13
|
+
if TYPE_CHECKING:
|
|
14
|
+
from .schema.journal import JournalDatabase, JournalUse
|
|
16
15
|
|
|
17
|
-
class WorldBacking(ABC):
|
|
18
|
-
"""One world's open state file."""
|
|
19
16
|
|
|
17
|
+
class WorldBacking(ABC):
|
|
20
18
|
store: Optional[WorldDatabase] = None
|
|
21
19
|
|
|
22
20
|
@staticmethod
|
|
23
21
|
def branch(source: Path, path: Path, contract: Optional[Contract], *, audit: bool = True) -> "WorldBacking":
|
|
24
|
-
"""
|
|
25
|
-
``path`` is removed again when the copy does not open. ``audit=False`` is for a
|
|
26
|
-
source whose rows are already proven (a version's template, a verified export)."""
|
|
22
|
+
"""``audit=False`` only for a source whose rows are already proven: a version's template, a verified export."""
|
|
27
23
|
from .legacy_sqlite import LegacySQLiteBacking
|
|
28
24
|
|
|
29
25
|
WorldDatabase.clone_file(Path(source), Path(path))
|
|
@@ -36,34 +32,34 @@ class WorldBacking(ABC):
|
|
|
36
32
|
raise
|
|
37
33
|
|
|
38
34
|
@abstractmethod
|
|
39
|
-
def transaction(self) -> AbstractContextManager[Any]:
|
|
40
|
-
"""The unit one tool call runs in."""
|
|
35
|
+
def transaction(self) -> AbstractContextManager[Any]: ...
|
|
41
36
|
|
|
42
37
|
@abstractmethod
|
|
43
|
-
def handler_connection(self) -> Any:
|
|
44
|
-
"""What a tool handler receives as ``conn``."""
|
|
38
|
+
def handler_connection(self) -> Any: ...
|
|
45
39
|
|
|
46
40
|
@abstractmethod
|
|
47
41
|
def split_statements(self, script: str) -> List[str]: ...
|
|
48
42
|
|
|
49
43
|
@abstractmethod
|
|
50
44
|
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
51
|
-
"""Read-only SQL
|
|
45
|
+
"""Read-only SQL: every backing refuses a write here (``world.state``)."""
|
|
52
46
|
|
|
53
47
|
@abstractmethod
|
|
54
48
|
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
55
|
-
"""
|
|
49
|
+
"""``None`` when the statement projects no columns, which the score skips; ``[]`` (no rows) scores ``None``."""
|
|
50
|
+
|
|
51
|
+
@abstractmethod
|
|
52
|
+
def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
|
|
53
|
+
"""Yields what a verifier's statements read of ``database``, so one that read an incomplete journal fails closed."""
|
|
56
54
|
|
|
57
55
|
@abstractmethod
|
|
58
56
|
def snapshot(self, destination: Path) -> Path: ...
|
|
59
57
|
|
|
60
58
|
@abstractmethod
|
|
61
|
-
def set_task_context(self, scenario_id: str) -> bool:
|
|
62
|
-
"""Name the active task; ``False`` when the world does not declare the table."""
|
|
59
|
+
def set_task_context(self, scenario_id: str) -> bool: ...
|
|
63
60
|
|
|
64
61
|
@abstractmethod
|
|
65
|
-
def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
|
|
66
|
-
"""Bind the run's conditions; ``False`` when the world does not declare the table."""
|
|
62
|
+
def set_run_parameters(self, parameters: Dict[str, str]) -> bool: ...
|
|
67
63
|
|
|
68
64
|
@abstractmethod
|
|
69
65
|
def record_conversation_event(
|
|
@@ -74,16 +70,13 @@ class WorldBacking(ABC):
|
|
|
74
70
|
actor: str,
|
|
75
71
|
name: Optional[str],
|
|
76
72
|
payload_json: str,
|
|
77
|
-
) -> bool:
|
|
78
|
-
"""Log one turn event; ``False`` when the world does not declare the table."""
|
|
73
|
+
) -> bool: ...
|
|
79
74
|
|
|
80
75
|
@abstractmethod
|
|
81
76
|
def close(self) -> None: ...
|
|
82
77
|
|
|
83
78
|
|
|
84
79
|
class ContractBacking(WorldBacking):
|
|
85
|
-
"""A schema world's state: the world database its contract compiled to."""
|
|
86
|
-
|
|
87
80
|
def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
|
|
88
81
|
self.store = WorldDatabase.open(path, contract, audit=audit)
|
|
89
82
|
|
|
@@ -99,6 +92,9 @@ class ContractBacking(WorldBacking):
|
|
|
99
92
|
def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
|
|
100
93
|
return [dict(row) for row in self.store.query(sql, params)]
|
|
101
94
|
|
|
95
|
+
def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
|
|
96
|
+
return database.attached(self.store)
|
|
97
|
+
|
|
102
98
|
def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
|
|
103
99
|
try:
|
|
104
100
|
return self.store.query(statement, private=True)
|
|
@@ -153,7 +153,6 @@ class Environment:
|
|
|
153
153
|
|
|
154
154
|
_install_ambient_interceptor()
|
|
155
155
|
|
|
156
|
-
# -- kind guards -----------------------------------------------------
|
|
157
156
|
|
|
158
157
|
def _require_mock(self, operation: str) -> None:
|
|
159
158
|
if self.kind != KIND_MOCK_TOOLS:
|
|
@@ -172,7 +171,6 @@ class Environment:
|
|
|
172
171
|
"the registry/execute seams instead."
|
|
173
172
|
)
|
|
174
173
|
|
|
175
|
-
# -- mock-tools: template + worlds ------------------------------------
|
|
176
174
|
|
|
177
175
|
def _build_template_db(self) -> None:
|
|
178
176
|
from ._materialize import materialize_template
|
|
@@ -235,7 +233,6 @@ class Environment:
|
|
|
235
233
|
self._implicit_world = World(self)
|
|
236
234
|
return self._implicit_world
|
|
237
235
|
|
|
238
|
-
# -- delegates to the implicit world ----------------------------------
|
|
239
236
|
|
|
240
237
|
def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
|
|
241
238
|
return self._ensure_world().execute(tool_name, tool_input)
|
|
@@ -255,7 +252,6 @@ class Environment:
|
|
|
255
252
|
def reset(self) -> None:
|
|
256
253
|
self._ensure_world().reset()
|
|
257
254
|
|
|
258
|
-
# -- harbor ----------------------------------------------------------
|
|
259
255
|
|
|
260
256
|
@property
|
|
261
257
|
def tasks(self) -> List[HarborTask]:
|
|
@@ -284,7 +280,6 @@ class Environment:
|
|
|
284
280
|
self._docker_runtime = CliDockerRuntime()
|
|
285
281
|
return self._docker_runtime
|
|
286
282
|
|
|
287
|
-
# -- routing ----------------------------------------------------------
|
|
288
283
|
|
|
289
284
|
def resolve_route(self, tool_name: str) -> str:
|
|
290
285
|
"""Route map > effects default (read→default_route, write→env,
|
|
@@ -339,11 +334,6 @@ def _effects_of(tool_name: str) -> Optional[str]:
|
|
|
339
334
|
return None
|
|
340
335
|
|
|
341
336
|
|
|
342
|
-
# ---------------------------------------------------------------------------
|
|
343
|
-
# Ambient interception — the define_tool wrapper's hook (spec §4.4, rung 1.5)
|
|
344
|
-
# ---------------------------------------------------------------------------
|
|
345
|
-
|
|
346
|
-
|
|
347
337
|
def _ambient_intercept(name: str, fn: Any, args: tuple, kwargs: dict) -> Any:
|
|
348
338
|
"""Called by the ``define_tool`` wrapper on every invocation. No active
|
|
349
339
|
world → miss sentinel (the wrapper calls the original fn — the identity
|
|
@@ -410,11 +400,6 @@ def _install_ambient_interceptor() -> None:
|
|
|
410
400
|
_interceptor_installed = True
|
|
411
401
|
|
|
412
402
|
|
|
413
|
-
# ---------------------------------------------------------------------------
|
|
414
|
-
# init
|
|
415
|
-
# ---------------------------------------------------------------------------
|
|
416
|
-
|
|
417
|
-
|
|
418
403
|
def init_from_path(
|
|
419
404
|
path: Union[str, Path],
|
|
420
405
|
*,
|
|
@@ -494,7 +479,7 @@ def init(
|
|
|
494
479
|
|
|
495
480
|
bench = GatewayBenchmarkClient(resolved_host, resolved_public, resolved_secret)
|
|
496
481
|
try:
|
|
497
|
-
details = bench.resolve_version(slug, version
|
|
482
|
+
details = bench.resolve_version(slug, version)
|
|
498
483
|
except BenchmarkPushError as error:
|
|
499
484
|
raise EnvironmentNotReady(f"no runnable version for '{slug}': {error}") from None
|
|
500
485
|
content_hash = details.get("contentHash")
|