@withgateway/sdk 0.4.0 → 0.9.1
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/agents/index.d.mts +573 -0
- package/dist/agents/index.d.ts +573 -0
- package/dist/agents/index.js +1443 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1394 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +5655 -1890
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +5769 -2005
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +418 -120
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +418 -120
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
- package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +2862 -438
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2820 -431
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- 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.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +418 -120
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +418 -120
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +2086 -1749
- package/dist/worlds/index.d.ts +2086 -1749
- package/dist/worlds/index.js +1471 -269
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1466 -265
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_world.py +24 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/api.py +27 -7
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
- package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
- package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
- 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 +9 -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/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
- package/runtime/gatewaysdk/environment/schema/host.py +74 -11
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
- package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
- package/runtime/gatewaysdk/environment/schema/local.py +33 -7
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
- package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
- package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
- package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
- package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +20 -24
- package/skills/connector-schema-authoring/connector-worlds.md +155 -13
- package/skills/connector-schema-authoring/world-schema.md +36 -29
- package/skills/world-data-ingestion/SKILL.md +11 -11
- package/skills/worlds-getting-started/SKILL.md +9 -9
- package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
- package/skills/worlds-getting-started/references/gotchas.md +40 -9
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- package/dist/media-BIApiPzS.d.ts +0 -102
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
"""The bridge's template commands: ``templates``, ``template-summary``, ``describe``,
|
|
2
|
+
``init-template``, ``init-template-files``, ``init-world-files``, ``build-slack`` and ``refresh-slack``.
|
|
3
|
+
|
|
4
|
+
A vendor template is an official world on the platform, a schema world built from it, and
|
|
5
|
+
arrives as that world's files (``[{path, content}]``, base64); only the blank ``custom``
|
|
6
|
+
scaffold is read from code. None of these runs a template's Python.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import tempfile
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from typing import TYPE_CHECKING, Any, Callable
|
|
15
|
+
|
|
16
|
+
from .cast import world_fields
|
|
17
|
+
from .scaffold import (
|
|
18
|
+
CUSTOM,
|
|
19
|
+
TEMPLATE_SLUG,
|
|
20
|
+
CustomScaffold,
|
|
21
|
+
TemplateWorld,
|
|
22
|
+
init_bundle,
|
|
23
|
+
init_bundle_from_files,
|
|
24
|
+
init_bundle_from_world,
|
|
25
|
+
refuse_official,
|
|
26
|
+
request_files,
|
|
27
|
+
template_digest,
|
|
28
|
+
)
|
|
29
|
+
from .validation import ContractError, fail
|
|
30
|
+
|
|
31
|
+
if TYPE_CHECKING:
|
|
32
|
+
from .connector import Spec
|
|
33
|
+
from .redaction import RedactPolicy
|
|
34
|
+
|
|
35
|
+
COMPILED_MARKERS = ("schema/world.json", "tool-schemas.json")
|
|
36
|
+
DESCRIBE_PATHS = (
|
|
37
|
+
"schema/world.json",
|
|
38
|
+
"tool-schemas.json",
|
|
39
|
+
"connector.toml",
|
|
40
|
+
"gateway-env.toml",
|
|
41
|
+
"api/handlers.py",
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def templates(request: dict) -> dict:
|
|
46
|
+
"""A summary of each official world the caller sends, in its order, then ``custom``. A world whose
|
|
47
|
+
own files cannot be summarized is answered under ``refused`` and the others still list; a
|
|
48
|
+
request of the wrong shape is refused whole."""
|
|
49
|
+
listed = request.get("templates")
|
|
50
|
+
listed = [] if listed is None else listed
|
|
51
|
+
if not isinstance(listed, list):
|
|
52
|
+
fail("input", "Expected templates as [{slug, files: [{path, content}]}]", "/templates")
|
|
53
|
+
summaries: list[dict] = []
|
|
54
|
+
refused: list[dict] = []
|
|
55
|
+
seen: set[str] = set()
|
|
56
|
+
for index, entry in enumerate(listed):
|
|
57
|
+
location = f"/templates/{index}"
|
|
58
|
+
slug = _official_slug(entry, location)
|
|
59
|
+
if slug in seen:
|
|
60
|
+
fail("input", f"{slug} is sent twice", f"{location}/slug")
|
|
61
|
+
seen.add(slug)
|
|
62
|
+
template = TemplateWorld(request_files(entry, location=f"{location}/files"), location=f"{location}/files")
|
|
63
|
+
try:
|
|
64
|
+
summaries.append(template.summary(slug))
|
|
65
|
+
except ContractError as error:
|
|
66
|
+
refused.append({"slug": slug, "error": error.detail})
|
|
67
|
+
return {"status": "ok", "templates": [*summaries, CustomScaffold().summary(CUSTOM)], "refused": refused}
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _official_slug(entry: Any, location: str) -> str:
|
|
71
|
+
slug = entry.get("slug") if isinstance(entry, dict) else None
|
|
72
|
+
if not isinstance(slug, str) or not TEMPLATE_SLUG.fullmatch(slug):
|
|
73
|
+
fail(
|
|
74
|
+
"input", "Each template is {slug, files} with a slug of lowercase letters, digits and -", f"{location}/slug"
|
|
75
|
+
)
|
|
76
|
+
if slug == CUSTOM:
|
|
77
|
+
fail(
|
|
78
|
+
"input",
|
|
79
|
+
"custom is the runtime's own scaffold and is always listed last; send official templates only",
|
|
80
|
+
f"{location}/slug",
|
|
81
|
+
)
|
|
82
|
+
return slug
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def init_template(request: dict, root: Path) -> None:
|
|
86
|
+
connector = request.get("connector", CUSTOM)
|
|
87
|
+
name = request.get("name")
|
|
88
|
+
if not isinstance(connector, str) or (name is not None and not isinstance(name, str)):
|
|
89
|
+
fail("input", "Expected a connector template slug and an optional name")
|
|
90
|
+
refuse_official(connector, "init-template-files")
|
|
91
|
+
init_bundle(root, connector=CUSTOM, name=name, with_example_tool=request.get("with_example_tool") is True)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def init_template_files(request: dict, root: Path) -> None:
|
|
95
|
+
"""The template arrives as files, never as a path the request chose."""
|
|
96
|
+
connector = request.get("connector")
|
|
97
|
+
name = request.get("name")
|
|
98
|
+
if not isinstance(connector, str) or (name is not None and not isinstance(name, str)):
|
|
99
|
+
fail("input", "Expected the connector slug and an optional name")
|
|
100
|
+
init_bundle_from_files(root, request_files(request), connector=connector, name=name)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def init_world_files(request: dict, root: Path) -> None:
|
|
104
|
+
"""An official world's files, copied under ``name`` and compiled."""
|
|
105
|
+
name = request.get("name")
|
|
106
|
+
if not isinstance(name, str):
|
|
107
|
+
fail("input", "Expected the new world's name")
|
|
108
|
+
init_bundle_from_world(root, request_files(request), name=name)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def build_slack(request: dict, root: Path) -> None:
|
|
112
|
+
from .slack import build_slack_bundle
|
|
113
|
+
|
|
114
|
+
template = request_files(request, "template")
|
|
115
|
+
build_slack_bundle(root, template=template, evidence=request.get("evidence"), name=request.get("name"))
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def refresh_slack(request: dict, root: Path) -> None:
|
|
119
|
+
from .slack import refresh_slack_bundle
|
|
120
|
+
|
|
121
|
+
template = request_files(request, "template")
|
|
122
|
+
refresh_slack_bundle(root, request.get("evidence"), template=template, batch_id=request.get("batch_id"))
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
WRITERS: dict[str, Callable[[dict, Path], None]] = {
|
|
126
|
+
"init-template": init_template,
|
|
127
|
+
"init-template-files": init_template_files,
|
|
128
|
+
"init-world-files": init_world_files,
|
|
129
|
+
"build-slack": build_slack,
|
|
130
|
+
"refresh-slack": refresh_slack,
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def _redact_summary(spec: "Spec | RedactPolicy") -> dict:
|
|
135
|
+
"""``slug`` is the salt ``_digest`` hashes under: the connector's slug, not the platform world slug."""
|
|
136
|
+
return {
|
|
137
|
+
"slug": spec.slug,
|
|
138
|
+
"hash": sorted(spec.hash_fields),
|
|
139
|
+
"drop": sorted(spec.drop_fields),
|
|
140
|
+
"preserve": sorted(spec.preserve_fields),
|
|
141
|
+
"round": dict(spec.round_fields),
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def _annotate_redaction(entities: list[dict], spec: "Spec | RedactPolicy | None") -> None:
|
|
146
|
+
from .connector import redaction_of
|
|
147
|
+
|
|
148
|
+
for entity in entities:
|
|
149
|
+
for field in entity["fields"]:
|
|
150
|
+
field["redaction"] = redaction_of(spec, field["name"]) if spec else None
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def _operations(spec: "Spec") -> list[dict]:
|
|
154
|
+
return [
|
|
155
|
+
{
|
|
156
|
+
"name": op.name,
|
|
157
|
+
"method": op.method,
|
|
158
|
+
"path": op.path,
|
|
159
|
+
"params": list(op.params),
|
|
160
|
+
"entity": op.entity,
|
|
161
|
+
"results": op.results,
|
|
162
|
+
}
|
|
163
|
+
for op in spec.operations.values()
|
|
164
|
+
]
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _served_operations(spec: "Spec", settings: Any) -> list[dict]:
|
|
168
|
+
operations = _operations(spec)
|
|
169
|
+
for operation in operations:
|
|
170
|
+
served = settings.for_operation(operation["name"]) if settings else None
|
|
171
|
+
operation["action"] = served.action if served else None
|
|
172
|
+
operation["status"] = served.status if served else None
|
|
173
|
+
return operations
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def template_summary(files: dict[str, bytes]) -> dict:
|
|
177
|
+
"""Never runs the template's Python."""
|
|
178
|
+
from .connector import bind_spec, parse_spec
|
|
179
|
+
from .redaction import parse_env_policy
|
|
180
|
+
|
|
181
|
+
world_path = next((path for path in ("world.json", "schema/world.json") if path in files), None)
|
|
182
|
+
if world_path is None:
|
|
183
|
+
fail(
|
|
184
|
+
"template",
|
|
185
|
+
"No world.json (template) or schema/world.json (world) among the files",
|
|
186
|
+
)
|
|
187
|
+
try:
|
|
188
|
+
world = json.loads(files[world_path].decode("utf-8"))
|
|
189
|
+
except (UnicodeDecodeError, json.JSONDecodeError) as error:
|
|
190
|
+
fail("template", f"{world_path} is not valid JSON: {error}")
|
|
191
|
+
gateway = world.get("x-gateway") if isinstance(world, dict) else None
|
|
192
|
+
if not isinstance(gateway, dict):
|
|
193
|
+
fail("template", f"{world_path} is not a gateway-world document")
|
|
194
|
+
spec = bind_spec(parse_spec(files["connector.toml"].decode("utf-8")), world) if "connector.toml" in files else None
|
|
195
|
+
policy = spec
|
|
196
|
+
if policy is None and "gateway-env.toml" in files:
|
|
197
|
+
policy = parse_env_policy(files["gateway-env.toml"].decode("utf-8"))
|
|
198
|
+
entities = []
|
|
199
|
+
fields_by_entity = world_fields(world)
|
|
200
|
+
for name, entity in sorted((gateway.get("entities") or {}).items()):
|
|
201
|
+
entities.append(
|
|
202
|
+
{
|
|
203
|
+
"name": name,
|
|
204
|
+
"primaryKey": list(entity.get("primary_key") or []) if isinstance(entity, dict) else [],
|
|
205
|
+
"unique": list(entity.get("unique") or []) if isinstance(entity, dict) else [],
|
|
206
|
+
"relationships": list(entity.get("relationships") or []) if isinstance(entity, dict) else [],
|
|
207
|
+
"fields": [field.describe() for field in fields_by_entity.get(name, [])],
|
|
208
|
+
}
|
|
209
|
+
)
|
|
210
|
+
_annotate_redaction(entities, policy)
|
|
211
|
+
connection = None
|
|
212
|
+
if spec is not None:
|
|
213
|
+
connection = {
|
|
214
|
+
"slug": spec.slug,
|
|
215
|
+
"baseUrl": spec.base_url,
|
|
216
|
+
"auth": spec.scheme,
|
|
217
|
+
"redact": _redact_summary(spec),
|
|
218
|
+
"operations": _operations(spec),
|
|
219
|
+
}
|
|
220
|
+
package = gateway.get("package") or {}
|
|
221
|
+
return {
|
|
222
|
+
"status": "ok",
|
|
223
|
+
"summary": {
|
|
224
|
+
"packageVersion": package.get("version"),
|
|
225
|
+
"domainVersion": gateway.get("domain_version"),
|
|
226
|
+
"domainId": world.get("$id"),
|
|
227
|
+
"digest": template_digest(files),
|
|
228
|
+
"entities": entities,
|
|
229
|
+
"connection": connection,
|
|
230
|
+
"redact": _redact_summary(policy) if policy is not None else None,
|
|
231
|
+
"tools": sorted((gateway.get("tools") or {}).keys()),
|
|
232
|
+
"files": sorted(files),
|
|
233
|
+
},
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def describe(request: dict) -> dict:
|
|
238
|
+
"""``connector`` (``custom`` only) or the ``files`` of a template or a compiled world."""
|
|
239
|
+
from .platform import describe_dependencies
|
|
240
|
+
from .ui import ui_kind
|
|
241
|
+
|
|
242
|
+
with tempfile.TemporaryDirectory(prefix="gateway-schema-") as directory:
|
|
243
|
+
root = Path(directory) / "bundle"
|
|
244
|
+
authored = _described_tree(request, root)
|
|
245
|
+
summary = template_summary({"world.json": (root / "schema/world.json").read_bytes()})["summary"]
|
|
246
|
+
summary["digest"] = template_digest(authored)
|
|
247
|
+
summary["files"] = sorted(authored)
|
|
248
|
+
summary["ui"] = ui_kind(root)
|
|
249
|
+
summary["tools"] = _tool_schemas(root)
|
|
250
|
+
summary["connection"] = None
|
|
251
|
+
summary["openapi"] = None
|
|
252
|
+
_describe_surface(root, summary)
|
|
253
|
+
summary["dependencies"] = describe_dependencies(root) if (root / "gateway-env.toml").is_file() else []
|
|
254
|
+
return {"status": "ok", "description": summary}
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
def _described_tree(request: dict, root: Path) -> dict[str, bytes]:
|
|
258
|
+
from .connector import parse_spec
|
|
259
|
+
|
|
260
|
+
connector = request.get("connector")
|
|
261
|
+
if connector is not None:
|
|
262
|
+
return _custom_tree(connector, root)
|
|
263
|
+
authored = request_files(request)
|
|
264
|
+
if all(marker in authored for marker in COMPILED_MARKERS):
|
|
265
|
+
_write_compiled(authored, root)
|
|
266
|
+
return authored
|
|
267
|
+
slug = request.get("slug") if isinstance(request.get("slug"), str) else None
|
|
268
|
+
if slug is None and "connector.toml" in authored:
|
|
269
|
+
slug = parse_spec(authored["connector.toml"].decode("utf-8")).slug
|
|
270
|
+
init_bundle_from_files(root, authored, connector=slug or CUSTOM)
|
|
271
|
+
return authored
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def _custom_tree(connector: Any, root: Path) -> dict[str, bytes]:
|
|
275
|
+
if not isinstance(connector, str):
|
|
276
|
+
fail("input", "Expected a connector template slug", "/connector")
|
|
277
|
+
refuse_official(connector, "describe", "/connector")
|
|
278
|
+
scaffold = CustomScaffold()
|
|
279
|
+
scaffold.write(root, connector=CUSTOM)
|
|
280
|
+
return scaffold.files
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def _write_compiled(authored: dict[str, bytes], root: Path) -> None:
|
|
284
|
+
root.mkdir()
|
|
285
|
+
for path, data in authored.items():
|
|
286
|
+
if path in DESCRIBE_PATHS:
|
|
287
|
+
target = root / path
|
|
288
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
289
|
+
target.write_bytes(data)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def _tool_schemas(root: Path) -> list[dict]:
|
|
293
|
+
tool_schemas = {}
|
|
294
|
+
if (root / "tool-schemas.json").is_file():
|
|
295
|
+
tool_schemas = json.loads((root / "tool-schemas.json").read_text(encoding="utf-8")).get("tools") or {}
|
|
296
|
+
return [
|
|
297
|
+
{
|
|
298
|
+
"name": name,
|
|
299
|
+
"description": str(entry.get("description") or ""),
|
|
300
|
+
"inputSchema": entry.get("input_schema"),
|
|
301
|
+
"outputSchema": entry.get("output_schema"),
|
|
302
|
+
}
|
|
303
|
+
for name, entry in sorted(tool_schemas.items())
|
|
304
|
+
]
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def _describe_surface(root: Path, summary: dict) -> None:
|
|
308
|
+
from .api import load_api_settings, openapi_document
|
|
309
|
+
from .connector import load_spec
|
|
310
|
+
from .redaction import env_policy
|
|
311
|
+
|
|
312
|
+
if not (root / "connector.toml").is_file():
|
|
313
|
+
policy = env_policy(root / "gateway-env.toml")
|
|
314
|
+
_annotate_redaction(summary["entities"], policy)
|
|
315
|
+
summary["redact"] = _redact_summary(policy) if policy else None
|
|
316
|
+
return
|
|
317
|
+
spec = load_spec(root)
|
|
318
|
+
try:
|
|
319
|
+
settings = load_api_settings(root, spec)
|
|
320
|
+
except ContractError:
|
|
321
|
+
# A template without its handlers still has a shape worth showing.
|
|
322
|
+
settings = None
|
|
323
|
+
_annotate_redaction(summary["entities"], spec)
|
|
324
|
+
summary["connection"] = {
|
|
325
|
+
"slug": spec.slug,
|
|
326
|
+
"baseUrl": spec.base_url,
|
|
327
|
+
"auth": spec.scheme,
|
|
328
|
+
"redact": _redact_summary(spec),
|
|
329
|
+
"operations": _served_operations(spec, settings),
|
|
330
|
+
}
|
|
331
|
+
summary["openapi"] = openapi_document(spec, summary.get("domainId") or spec.slug, settings)
|
|
332
|
+
summary["redact"] = summary["connection"]["redact"]
|
|
@@ -434,11 +434,14 @@ class _Unredirected(urllib.request.HTTPRedirectHandler):
|
|
|
434
434
|
return None
|
|
435
435
|
|
|
436
436
|
|
|
437
|
+
UNREDIRECTED = urllib.request.build_opener(_Unredirected)
|
|
438
|
+
|
|
439
|
+
|
|
437
440
|
class PlatformLedger:
|
|
438
441
|
"""The platform's ledger door (:data:`LEDGER_ROUTE`), behind the control-plane secret; an answer that
|
|
439
442
|
redirects the flush is not followed, so it reads as unavailable, never as stored."""
|
|
440
443
|
|
|
441
|
-
_opener =
|
|
444
|
+
_opener = UNREDIRECTED
|
|
442
445
|
|
|
443
446
|
def __init__(self, platform_url: str, secret: str, timeout_s: float = 30.0, host_url: str | None = None) -> None:
|
|
444
447
|
self.url = f"{platform_url.rstrip('/')}{LEDGER_ROUTE}"
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""The knob values a session opens with (a world state's bindings), as the World Host takes them."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from .validation import fail
|
|
6
|
+
|
|
7
|
+
MAX_RUN_PARAMETERS = 8
|
|
8
|
+
MAX_RUN_PARAMETER_VALUE_LENGTH = 64
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def parse_run_parameters(raw: object) -> dict[str, str]:
|
|
12
|
+
if raw is None:
|
|
13
|
+
return {}
|
|
14
|
+
if not isinstance(raw, dict):
|
|
15
|
+
fail("host", "parameters is an object of parameter name to value")
|
|
16
|
+
if len(raw) > MAX_RUN_PARAMETERS:
|
|
17
|
+
fail("host", f"an open binds at most {MAX_RUN_PARAMETERS} parameters, not {len(raw)}")
|
|
18
|
+
for name, value in raw.items():
|
|
19
|
+
if not isinstance(name, str) or not name:
|
|
20
|
+
fail("host", "each parameter has a name")
|
|
21
|
+
if not isinstance(value, str):
|
|
22
|
+
fail("host", f"parameter '{name}' is bound to a string, not {type(value).__name__}")
|
|
23
|
+
if len(value) > MAX_RUN_PARAMETER_VALUE_LENGTH:
|
|
24
|
+
fail("host", f"parameter '{name}' is bound to at most {MAX_RUN_PARAMETER_VALUE_LENGTH} characters")
|
|
25
|
+
return dict(raw)
|
|
@@ -15,10 +15,11 @@ from .database import WorldDatabase
|
|
|
15
15
|
from .dependencies import Dependency
|
|
16
16
|
from .grading import Grade, GraderError, TaskGrader
|
|
17
17
|
from .journal import CallsView, WorldJournal
|
|
18
|
+
from .page_checks import PageCheck
|
|
18
19
|
from .request_ledger import RequestOutbox
|
|
19
20
|
from .served_names import ServedNames
|
|
20
21
|
from .session_files import CALLS_JOURNAL, LEDGER_JOURNAL, SessionExport
|
|
21
|
-
from .snapshot import SCENARIOS
|
|
22
|
+
from .snapshot import SCENARIO_GRADERS, SCENARIOS
|
|
22
23
|
from .tasks import (
|
|
23
24
|
TASK_DIR,
|
|
24
25
|
TaskSpec,
|
|
@@ -29,7 +30,9 @@ from .tasks import (
|
|
|
29
30
|
write_task_dir,
|
|
30
31
|
)
|
|
31
32
|
from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
|
|
33
|
+
from .ui_interactions import UiRecorder
|
|
32
34
|
from .validation import fail
|
|
35
|
+
from .webhooks import WebhookPoll
|
|
33
36
|
from .workers import ConfinedVerifierSandbox
|
|
34
37
|
|
|
35
38
|
if TYPE_CHECKING:
|
|
@@ -39,6 +42,8 @@ Restorer = Callable[[Callable[[SessionExport], None]], bool]
|
|
|
39
42
|
|
|
40
43
|
|
|
41
44
|
class WorldRuntime(ABC):
|
|
45
|
+
takes_parameters = False
|
|
46
|
+
|
|
42
47
|
def __init__(
|
|
43
48
|
self,
|
|
44
49
|
cached: CachedVersion,
|
|
@@ -48,8 +53,10 @@ class WorldRuntime(ABC):
|
|
|
48
53
|
spec: TaskSpec | None,
|
|
49
54
|
token: str | None,
|
|
50
55
|
journaled: bool = False,
|
|
56
|
+
parameters: dict[str, str] | None = None,
|
|
51
57
|
) -> None:
|
|
52
58
|
self.cached = cached
|
|
59
|
+
self.parameters = dict(parameters or {})
|
|
53
60
|
self.session_dir = Path(session_dir)
|
|
54
61
|
self.task = task
|
|
55
62
|
self.task_spec = spec
|
|
@@ -93,23 +100,38 @@ class WorldRuntime(ABC):
|
|
|
93
100
|
token: str | None,
|
|
94
101
|
dependencies: dict[str, DependencyWorld],
|
|
95
102
|
restore: Restorer,
|
|
103
|
+
pages_vouched: bool,
|
|
96
104
|
journaled: bool = False,
|
|
105
|
+
parameters: dict[str, str] | None = None,
|
|
97
106
|
) -> WorldRuntime:
|
|
98
107
|
"""``journaled`` keeps the calls on disk, so a version worker that dies leaves them to the next one."""
|
|
99
|
-
|
|
108
|
+
if parameters and not cached.runtime_class.takes_parameters:
|
|
109
|
+
fail("host", f"version {cached.version_id} is an api bundle, which takes no runtime parameters")
|
|
110
|
+
runtime = cached.runtime_class(
|
|
111
|
+
cached, session_dir, task=task, spec=spec, token=token, journaled=journaled, parameters=parameters
|
|
112
|
+
)
|
|
100
113
|
runtime._start(dependencies)
|
|
101
114
|
try:
|
|
102
115
|
if spec is not None:
|
|
103
116
|
runtime._check_task_entities(spec)
|
|
117
|
+
runtime._check_page_checks(spec)
|
|
104
118
|
write_task_dir(spec, runtime.session_dir)
|
|
105
119
|
runtime._to_start()
|
|
106
120
|
runtime.restored = restore(runtime.restore)
|
|
121
|
+
runtime._note_pages(pages_vouched)
|
|
107
122
|
runtime._attach_app()
|
|
108
123
|
except BaseException:
|
|
109
124
|
runtime.close()
|
|
110
125
|
raise
|
|
111
126
|
return runtime
|
|
112
127
|
|
|
128
|
+
def _note_pages(self, vouched: bool) -> None:
|
|
129
|
+
"""A first open notes that this host records the pages; a restore from an export no recording host took
|
|
130
|
+
notes that an earlier life may have gone unrecorded. A restore a recording host vouched for adds nothing."""
|
|
131
|
+
if self.cached.ui is None or (self.restored and vouched):
|
|
132
|
+
return
|
|
133
|
+
(UiRecorder.unrecorded if self.restored else UiRecorder.recording)(self.calls)
|
|
134
|
+
|
|
113
135
|
def _attach_app(self) -> None:
|
|
114
136
|
cached = self.cached
|
|
115
137
|
if cached.spec is None:
|
|
@@ -141,6 +163,18 @@ class WorldRuntime(ABC):
|
|
|
141
163
|
"/task",
|
|
142
164
|
)
|
|
143
165
|
|
|
166
|
+
def _check_page_checks(self, spec: TaskSpec) -> None:
|
|
167
|
+
"""A check on the page of a world that serves none could never be decided."""
|
|
168
|
+
named = [
|
|
169
|
+
check.get("id") or check["entity"] for check in spec.grader_checks() if PageCheck(check).names_the_page
|
|
170
|
+
]
|
|
171
|
+
if named and self.cached.ui is None:
|
|
172
|
+
fail(
|
|
173
|
+
"task",
|
|
174
|
+
f"the task's checks {', '.join(named)} read the page, and this world serves none",
|
|
175
|
+
"/task/grader",
|
|
176
|
+
)
|
|
177
|
+
|
|
144
178
|
@abstractmethod
|
|
145
179
|
def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
|
|
146
180
|
"""A failure here leaves nothing to close: :meth:`open` runs it outside its cleanup."""
|
|
@@ -206,6 +240,12 @@ class WorldRuntime(ABC):
|
|
|
206
240
|
def state(self) -> dict:
|
|
207
241
|
return self.calls.into_state(self._rows())
|
|
208
242
|
|
|
243
|
+
def webhooks(self, poll: WebhookPoll) -> dict:
|
|
244
|
+
"""The subscriptions the world's ``[webhooks]`` finds (none declared: ``declared`` false), a page
|
|
245
|
+
of deliveries, and how many of the poll's answers the ledger kept."""
|
|
246
|
+
outbox = self.app.state.webhooks if self.app is not None else None
|
|
247
|
+
return self.calls.webhook_page(outbox, poll)
|
|
248
|
+
|
|
209
249
|
def grader_state(self, report: Optional[str] = None, journal: Optional[WorldJournal] = None) -> dict:
|
|
210
250
|
"""Keys beside the rows (``calls``, ``snapshot``, ``report``, ``gateway_*``) are reserved from entity names."""
|
|
211
251
|
state = self.calls.into_state(self._grader_rows())
|
|
@@ -322,6 +362,8 @@ class WorldRuntime(ABC):
|
|
|
322
362
|
|
|
323
363
|
|
|
324
364
|
class TreeRuntime(WorldRuntime):
|
|
365
|
+
takes_parameters = True
|
|
366
|
+
|
|
325
367
|
world: ToolsWorld
|
|
326
368
|
|
|
327
369
|
@classmethod
|
|
@@ -359,10 +401,13 @@ class TreeRuntime(WorldRuntime):
|
|
|
359
401
|
allowed=self.allowed,
|
|
360
402
|
dependencies=dependencies,
|
|
361
403
|
calls=self.calls,
|
|
404
|
+
parameters=self.parameters,
|
|
362
405
|
)
|
|
363
406
|
return
|
|
364
407
|
assert self.task is not None
|
|
365
|
-
self.world = ToolsWorld(
|
|
408
|
+
self.world = ToolsWorld(
|
|
409
|
+
tools, self.session_dir, self.task, dependencies=dependencies, calls=self.calls, parameters=self.parameters
|
|
410
|
+
)
|
|
366
411
|
|
|
367
412
|
def _app_state(self) -> ToolsWorldState:
|
|
368
413
|
return ToolsWorldState(self.world, self.cached.tree)
|
|
@@ -551,7 +596,7 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
551
596
|
def _bundled_verifier(self) -> Path | None:
|
|
552
597
|
assert self.task is not None
|
|
553
598
|
scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
|
|
554
|
-
return scenario /
|
|
599
|
+
return scenario / SCENARIO_GRADERS / "verify.py" if scenario else None
|
|
555
600
|
|
|
556
601
|
def call(self, tool: str, args: dict) -> dict:
|
|
557
602
|
ServedNames.of((), self.cached.spec).refuse(tool)
|