@withgateway/sdk 0.1.20 → 0.2.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 +141 -2
- package/dist/cli.js +8683 -1343
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +8683 -1344
- package/dist/cli.mjs.map +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +979 -46
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +943 -38
- package/dist/index.mjs.map +1 -1
- package/dist/tracing/index.js +9 -2
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +9 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +738 -28
- package/dist/worlds/index.d.ts +738 -28
- package/dist/worlds/index.js +940 -42
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +934 -36
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +9 -2
- package/runtime/gatewaysdk/__init__.py +0 -0
- package/runtime/gatewaysdk/environment/__init__.py +108 -0
- package/runtime/gatewaysdk/environment/_bundle.py +281 -0
- package/runtime/gatewaysdk/environment/_harbor.py +276 -0
- package/runtime/gatewaysdk/environment/_materialize.py +97 -0
- package/runtime/gatewaysdk/environment/_tar.py +33 -0
- package/runtime/gatewaysdk/environment/_world.py +346 -0
- package/runtime/gatewaysdk/environment/core.py +527 -0
- package/runtime/gatewaysdk/environment/errors.py +58 -0
- package/runtime/gatewaysdk/environment/runtime.py +150 -0
- package/runtime/gatewaysdk/environment/schema/__init__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +225 -0
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +116 -0
- package/runtime/gatewaysdk/environment/schema/_slack_scenario.py +183 -0
- package/runtime/gatewaysdk/environment/schema/api.py +1628 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +755 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +615 -0
- package/runtime/gatewaysdk/environment/schema/conform.py +428 -0
- package/runtime/gatewaysdk/environment/schema/connector.py +777 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py +17 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json +233 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml +112 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/world.json +1380 -0
- package/runtime/gatewaysdk/environment/schema/connectors/base.json +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +18 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/world.json +123 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/handlers.py +81 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/parity.json +37 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/provenance.json +134 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/scope.toml +158 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +5869 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/handlers.py +23 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/world.json +209 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/handlers.py +18 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/world.json +286 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/handlers.py +34 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/parity.json +49 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +181 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +128 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/world.json +2218 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jira/handlers.py +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jira/world.json +389 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/handlers.py +38 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/parity.json +29 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/provenance.json +152 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/scope.toml +120 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/world.json +765 -0
- package/runtime/gatewaysdk/environment/schema/connectors/linear/handlers.py +20 -0
- package/runtime/gatewaysdk/environment/schema/connectors/linear/world.json +363 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/fidelity.json +45 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/handlers.py +1 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/provenance.json +851 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md +231 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/teams-types.json +1710 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/world.json +858 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/handlers.py +32 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/parity.json +50 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/provenance.json +137 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/scope.toml +78 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/world.json +16243 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/handlers.py +806 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/parity.json +46 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/provenance.json +143 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/scope.toml +174 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/world.json +4695 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/MODEL.md +236 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/capabilities.json +1039 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/handlers.py +762 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/parity.json +65 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/provenance.json +294 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/scope.toml +44 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/world.json +4993 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/handlers.py +75 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/parity.json +36 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/provenance.json +179 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/scope.toml +180 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/world.json +806 -0
- package/runtime/gatewaysdk/environment/schema/data.py +593 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +263 -0
- package/runtime/gatewaysdk/environment/schema/host.py +2407 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +275 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +1272 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +250 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +118 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +202 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +331 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +313 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +223 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +293 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +390 -0
- package/runtime/gatewaysdk/environment/schema/slack.py +757 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +479 -0
- package/runtime/gatewaysdk/environment/schema/store.py +904 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +525 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +322 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +577 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +78 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +500 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +336 -0
- package/skills/agents/connector-template-author.md +202 -0
- package/skills/connector-schema-authoring/CONNECTORS.md +331 -0
- package/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
- package/skills/connector-schema-authoring/SKILL.md +313 -0
- package/skills/world-data-ingestion/ROWS.md +223 -0
- package/skills/world-data-ingestion/SKILL.md +293 -0
- package/skills/worlds-getting-started/SKILL.md +390 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@withgateway/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
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",
|
|
@@ -69,12 +69,15 @@
|
|
|
69
69
|
},
|
|
70
70
|
"files": [
|
|
71
71
|
"dist",
|
|
72
|
+
"skills",
|
|
73
|
+
"runtime",
|
|
72
74
|
"README.md"
|
|
73
75
|
],
|
|
74
76
|
"publishConfig": {
|
|
75
77
|
"access": "public"
|
|
76
78
|
},
|
|
77
79
|
"scripts": {
|
|
80
|
+
"prebuild": "node scripts/copy-skills.mjs && node scripts/copy-runtime.mjs",
|
|
78
81
|
"build": "tsup",
|
|
79
82
|
"dev": "tsup --watch",
|
|
80
83
|
"typecheck": "tsc --noEmit",
|
|
@@ -107,7 +110,8 @@
|
|
|
107
110
|
"@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
|
|
108
111
|
"@opentelemetry/resources": ">=1.0.0",
|
|
109
112
|
"@opentelemetry/sdk-trace-base": ">=1.0.0",
|
|
110
|
-
"@opentelemetry/sdk-trace-node": ">=1.0.0"
|
|
113
|
+
"@opentelemetry/sdk-trace-node": ">=1.0.0",
|
|
114
|
+
"playwright": ">=1.40.0"
|
|
111
115
|
},
|
|
112
116
|
"peerDependenciesMeta": {
|
|
113
117
|
"@opentelemetry/api": {
|
|
@@ -124,6 +128,9 @@
|
|
|
124
128
|
},
|
|
125
129
|
"@opentelemetry/resources": {
|
|
126
130
|
"optional": true
|
|
131
|
+
},
|
|
132
|
+
"playwright": {
|
|
133
|
+
"optional": true
|
|
127
134
|
}
|
|
128
135
|
},
|
|
129
136
|
"optionalDependencies": {
|
|
File without changes
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
"""Mock environments as an execution substrate — ``gatewaysdk.environment``.
|
|
2
|
+
|
|
3
|
+
import gatewaysdk.environment as gwenv
|
|
4
|
+
|
|
5
|
+
env = gwenv.init("refund-flows-env") # slug/id, READY head
|
|
6
|
+
with env: # fresh world + ambient interception
|
|
7
|
+
my_agent("handle ticket #4415") # define_tool calls hit the mock world
|
|
8
|
+
assert env.verify("refund_row_created").passed
|
|
9
|
+
|
|
10
|
+
Seams (spec §4.4): ``world.as_registry()`` (replay's registry contract),
|
|
11
|
+
``world.wrap_tools()``, ``world.execute()``, and the ambient ``define_tool``
|
|
12
|
+
wrapper inside ``with env:`` / ``env.branch()``. Harbor-kind environments
|
|
13
|
+
(task.toml trees) expose ``env.tasks`` / ``env.task(name)`` docker sandboxes
|
|
14
|
+
instead. ``gwenv.init_from_path(dir)`` boots a local bundle offline.
|
|
15
|
+
|
|
16
|
+
Note: :mod:`gatewaysdk.environments` (plural) is the platform HUB client
|
|
17
|
+
(read/inspect/trigger); this module is the local execution runtime built on
|
|
18
|
+
top of it.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
import importlib
|
|
22
|
+
from typing import TYPE_CHECKING
|
|
23
|
+
|
|
24
|
+
from . import runtime
|
|
25
|
+
from ._bundle import EnvManifest, HarborTask
|
|
26
|
+
from .errors import (
|
|
27
|
+
EnvironmentKindError,
|
|
28
|
+
EnvironmentNotConfigured,
|
|
29
|
+
EnvironmentNotReady,
|
|
30
|
+
GatewayEnvError,
|
|
31
|
+
HermeticViolation,
|
|
32
|
+
ToolRouteError,
|
|
33
|
+
VerifierError,
|
|
34
|
+
WorldStartError,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
# The heavy seams live in ``core`` (platform hub + tracing clients), ``_harbor``
|
|
38
|
+
# (docker CLI) and ``_world`` (the replay registry contract). Bind them LAZILY
|
|
39
|
+
# via PEP 562 so a lean consumer — e.g. the benchmark runner's mock_tools engine,
|
|
40
|
+
# which vendors only this ``environment`` subpackage and imports ``_bundle`` /
|
|
41
|
+
# ``_world`` (worlds + verifiers) directly — can ``import gatewaysdk.environment``
|
|
42
|
+
# without dragging ``gatewaysdk.environments`` / ``gatewaysdk.build`` / docker /
|
|
43
|
+
# replay into the image. First access to any of these names imports its module
|
|
44
|
+
# on demand, so full-SDK behaviour is unchanged (just deferred).
|
|
45
|
+
_LAZY_ATTRS = {
|
|
46
|
+
"ENV_ENVIRONMENT_PREFIX": "core",
|
|
47
|
+
"Environment": "core",
|
|
48
|
+
"Report": "core",
|
|
49
|
+
"RouteRecord": "core",
|
|
50
|
+
"get_active_world": "core",
|
|
51
|
+
"init": "core",
|
|
52
|
+
"init_from_path": "core",
|
|
53
|
+
"CliDockerRuntime": "_harbor",
|
|
54
|
+
"DockerRuntime": "_harbor",
|
|
55
|
+
"ExecResult": "_harbor",
|
|
56
|
+
"HarborWorld": "_harbor",
|
|
57
|
+
"VerifierResult": "_world",
|
|
58
|
+
"World": "_world",
|
|
59
|
+
"WorldRegistry": "_world",
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
if TYPE_CHECKING: # pragma: no cover — static analysers still see the symbols
|
|
63
|
+
from ._harbor import CliDockerRuntime, DockerRuntime, ExecResult, HarborWorld
|
|
64
|
+
from ._world import VerifierResult, World, WorldRegistry
|
|
65
|
+
from .core import (
|
|
66
|
+
ENV_ENVIRONMENT_PREFIX,
|
|
67
|
+
Environment,
|
|
68
|
+
Report,
|
|
69
|
+
RouteRecord,
|
|
70
|
+
get_active_world,
|
|
71
|
+
init,
|
|
72
|
+
init_from_path,
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def __getattr__(name: str):
|
|
77
|
+
module = _LAZY_ATTRS.get(name)
|
|
78
|
+
if module is None:
|
|
79
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
80
|
+
return getattr(importlib.import_module(f".{module}", __name__), name)
|
|
81
|
+
|
|
82
|
+
__all__ = [
|
|
83
|
+
"ENV_ENVIRONMENT_PREFIX",
|
|
84
|
+
"CliDockerRuntime",
|
|
85
|
+
"DockerRuntime",
|
|
86
|
+
"EnvManifest",
|
|
87
|
+
"Environment",
|
|
88
|
+
"EnvironmentKindError",
|
|
89
|
+
"EnvironmentNotConfigured",
|
|
90
|
+
"EnvironmentNotReady",
|
|
91
|
+
"ExecResult",
|
|
92
|
+
"GatewayEnvError",
|
|
93
|
+
"HarborTask",
|
|
94
|
+
"HarborWorld",
|
|
95
|
+
"HermeticViolation",
|
|
96
|
+
"Report",
|
|
97
|
+
"RouteRecord",
|
|
98
|
+
"ToolRouteError",
|
|
99
|
+
"VerifierError",
|
|
100
|
+
"VerifierResult",
|
|
101
|
+
"World",
|
|
102
|
+
"WorldRegistry",
|
|
103
|
+
"WorldStartError",
|
|
104
|
+
"get_active_world",
|
|
105
|
+
"init",
|
|
106
|
+
"init_from_path",
|
|
107
|
+
"runtime",
|
|
108
|
+
]
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
"""Bundle inspection: kind detection, manifest parsing, handler loading.
|
|
2
|
+
|
|
3
|
+
Two structurally-detected environment kinds (spec §3.1 + addendum):
|
|
4
|
+
|
|
5
|
+
- **mock-tools** — ``gateway-env.toml`` at the bundle root, ``tools/*.py``
|
|
6
|
+
handlers, ``db/schema.sql`` (+ ``db/seed.sql``), ``verifiers/*.sql``.
|
|
7
|
+
- **harbor** — a tree of Harbor task dirs (``tasks/*/task.toml`` or
|
|
8
|
+
``*/task.toml``), mirroring ``benchmark_hub.harbor_adapter.detect_env_kind``.
|
|
9
|
+
|
|
10
|
+
Handler loading executes each ``tools/*.py`` with this SDK's
|
|
11
|
+
:mod:`gatewaysdk.environment.runtime` injected into ``sys.modules`` as
|
|
12
|
+
``gateway_env`` for the duration of the load — the module the generated
|
|
13
|
+
handlers import — and restores ``sys.modules`` afterwards.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import functools
|
|
19
|
+
import importlib.util
|
|
20
|
+
import inspect
|
|
21
|
+
import sys
|
|
22
|
+
import tomllib
|
|
23
|
+
import uuid
|
|
24
|
+
from dataclasses import dataclass, field
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any, Callable, Dict, List, Optional
|
|
27
|
+
|
|
28
|
+
from . import runtime
|
|
29
|
+
from .errors import EnvironmentNotReady, WorldStartError
|
|
30
|
+
|
|
31
|
+
KIND_MOCK_TOOLS = "mock-tools"
|
|
32
|
+
KIND_API = "api"
|
|
33
|
+
KIND_HARBOR = "harbor"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def detect_kind(bundle_path: Path) -> str:
|
|
37
|
+
""""api" iff ``gateway-api-world.toml`` sits at the root; else "mock-tools"
|
|
38
|
+
iff ``gateway-env.toml`` does; else "harbor" iff the tree holds Harbor task
|
|
39
|
+
dirs (same glob heuristics as the runner's ``detect_env_kind``); else the
|
|
40
|
+
bundle is not runnable here."""
|
|
41
|
+
from .schema import bundle_mode
|
|
42
|
+
|
|
43
|
+
bundle_mode(bundle_path) # Orphan/invalid schema declarations never downgrade.
|
|
44
|
+
if (bundle_path / "gateway-api-world.toml").is_file():
|
|
45
|
+
return KIND_API
|
|
46
|
+
if (bundle_path / "gateway-env.toml").is_file():
|
|
47
|
+
return KIND_MOCK_TOOLS
|
|
48
|
+
if list(bundle_path.glob("tasks/*/task.toml")) or list(bundle_path.glob("*/task.toml")):
|
|
49
|
+
return KIND_HARBOR
|
|
50
|
+
raise EnvironmentNotReady(
|
|
51
|
+
f"{bundle_path} is neither a mock-tools bundle (no gateway-env.toml) nor "
|
|
52
|
+
"a harbor task tree (no */task.toml) — nothing gwenv can run locally."
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
# ---------------------------------------------------------------------------
|
|
57
|
+
# mock-tools: manifest + handlers
|
|
58
|
+
# ---------------------------------------------------------------------------
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass
|
|
62
|
+
class EnvManifest:
|
|
63
|
+
"""Parsed ``gateway-env.toml``."""
|
|
64
|
+
|
|
65
|
+
name: str
|
|
66
|
+
serve: List[str]
|
|
67
|
+
db_engine: str = "sqlite"
|
|
68
|
+
raw: Dict[str, Any] = field(default_factory=dict)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def parse_manifest(bundle_path: Path) -> EnvManifest:
|
|
72
|
+
manifest_path = bundle_path / "gateway-env.toml"
|
|
73
|
+
try:
|
|
74
|
+
data = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
|
|
75
|
+
except (OSError, tomllib.TOMLDecodeError) as error:
|
|
76
|
+
raise EnvironmentNotReady(f"cannot parse {manifest_path}: {error}") from error
|
|
77
|
+
|
|
78
|
+
# Builder-generated manifests use an [environment] table; hand-written
|
|
79
|
+
# ones may use [env] or a top-level name.
|
|
80
|
+
env_table: Dict[str, Any] = {}
|
|
81
|
+
for key in ("environment", "env"):
|
|
82
|
+
if isinstance(data.get(key), dict):
|
|
83
|
+
env_table = data[key]
|
|
84
|
+
break
|
|
85
|
+
name = env_table.get("name") or data.get("name") or bundle_path.name
|
|
86
|
+
|
|
87
|
+
tools_table = data.get("tools") if isinstance(data.get("tools"), dict) else {}
|
|
88
|
+
serve = tools_table.get("serve") or []
|
|
89
|
+
if not isinstance(serve, list):
|
|
90
|
+
raise EnvironmentNotReady(f"{manifest_path}: [tools] serve must be a list of tool names")
|
|
91
|
+
|
|
92
|
+
db_value = data.get("db")
|
|
93
|
+
if isinstance(db_value, dict):
|
|
94
|
+
engine = db_value.get("engine") or env_table.get("db") or "sqlite"
|
|
95
|
+
elif isinstance(db_value, str):
|
|
96
|
+
engine = db_value
|
|
97
|
+
else:
|
|
98
|
+
engine = env_table.get("db") or "sqlite"
|
|
99
|
+
if engine != "sqlite":
|
|
100
|
+
raise WorldStartError(
|
|
101
|
+
f"db engine {engine!r} is not supported in local mode — P1 runs "
|
|
102
|
+
"sqlite in-process (Postgres arrives with hosted worlds, spec §4.9)."
|
|
103
|
+
)
|
|
104
|
+
return EnvManifest(name=str(name), serve=[str(s) for s in serve], db_engine=engine, raw=data)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _wrap_run_handler(fn: Callable[..., Any], tool_name: str) -> Callable[..., Any]:
|
|
108
|
+
"""Adapt the generated-bundle handler contract to the SDK's call shapes.
|
|
109
|
+
|
|
110
|
+
Builder-generated bundles expose ``run(input: dict, conn=None)`` in
|
|
111
|
+
``tools/<tool_name>.py`` — the whole tool input arrives as one dict, and
|
|
112
|
+
the runtime injects an open sqlite connection so writes land in the
|
|
113
|
+
active world (not the bundle's on-disk default db).
|
|
114
|
+
"""
|
|
115
|
+
takes_conn = "conn" in inspect.signature(fn).parameters
|
|
116
|
+
|
|
117
|
+
@functools.wraps(fn)
|
|
118
|
+
def handler(*args: Any, **kwargs: Any) -> Any:
|
|
119
|
+
tool_input = args[0] if args else (kwargs if runtime._active_store.get() is not None else (kwargs or None))
|
|
120
|
+
if takes_conn:
|
|
121
|
+
return fn(tool_input, conn=runtime._active_connection.get())
|
|
122
|
+
return fn(tool_input)
|
|
123
|
+
|
|
124
|
+
handler.__name__ = tool_name
|
|
125
|
+
return handler
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callable[..., Any]]:
|
|
129
|
+
"""Execute ``tools/*.py`` and return the tool-name → handler map.
|
|
130
|
+
|
|
131
|
+
Registration paths, in priority order:
|
|
132
|
+
1. ``@tool(name=...)`` / bare ``@tool`` decorations (captured via the
|
|
133
|
+
runtime's load-registry contextvar during module exec);
|
|
134
|
+
2. fallback discovery — a plain module-level ``def <tool_name>`` whose
|
|
135
|
+
name matches a served tool that no decorator claimed;
|
|
136
|
+
3. the generated-bundle contract — ``run(input, conn=None)`` in the
|
|
137
|
+
module whose FILE STEM is the served tool name (wrapped so the
|
|
138
|
+
active world's connection is injected).
|
|
139
|
+
|
|
140
|
+
``gateway_env`` is importable only inside this function's dynamic extent.
|
|
141
|
+
"""
|
|
142
|
+
from .schema import bundle_mode, check_bundle
|
|
143
|
+
|
|
144
|
+
contract = check_bundle(bundle_path) if bundle_mode(bundle_path) is not None else None
|
|
145
|
+
tools_dir = bundle_path / "tools"
|
|
146
|
+
registry: Dict[str, Callable[..., Any]] = {}
|
|
147
|
+
modules = []
|
|
148
|
+
modules_by_stem: Dict[str, Any] = {}
|
|
149
|
+
|
|
150
|
+
handler_files = sorted(tools_dir.glob("*.py")) if tools_dir.is_dir() else []
|
|
151
|
+
load_token = runtime._load_registry.set(registry)
|
|
152
|
+
strict_token = runtime._strict_registration.set(contract is not None)
|
|
153
|
+
saved = sys.modules.get("gateway_env")
|
|
154
|
+
sys.modules["gateway_env"] = runtime
|
|
155
|
+
# Generated bundles use intra-bundle imports ("from tools._db import …"),
|
|
156
|
+
# so the bundle root must be importable for the load's dynamic extent.
|
|
157
|
+
bundle_root = str(bundle_path)
|
|
158
|
+
path_added = bundle_root not in sys.path
|
|
159
|
+
if path_added:
|
|
160
|
+
sys.path.insert(0, bundle_root)
|
|
161
|
+
saved_pkgs = {
|
|
162
|
+
name: sys.modules.get(name)
|
|
163
|
+
for name in list(sys.modules)
|
|
164
|
+
if name == "tools" or name.startswith("tools.")
|
|
165
|
+
}
|
|
166
|
+
for name in saved_pkgs:
|
|
167
|
+
sys.modules.pop(name, None)
|
|
168
|
+
try:
|
|
169
|
+
for handler_file in handler_files:
|
|
170
|
+
if handler_file.name.startswith("_"):
|
|
171
|
+
continue
|
|
172
|
+
module_name = f"_gateway_env_bundle_{uuid.uuid4().hex[:8]}_{handler_file.stem}"
|
|
173
|
+
spec = importlib.util.spec_from_file_location(module_name, handler_file)
|
|
174
|
+
if spec is None or spec.loader is None: # pragma: no cover — importlib edge
|
|
175
|
+
raise WorldStartError(f"cannot load handler module {handler_file}")
|
|
176
|
+
module = importlib.util.module_from_spec(spec)
|
|
177
|
+
sys.modules[module_name] = module
|
|
178
|
+
try:
|
|
179
|
+
spec.loader.exec_module(module)
|
|
180
|
+
except Exception as error:
|
|
181
|
+
raise WorldStartError(
|
|
182
|
+
f"handler module {handler_file.name} failed to import: {error}"
|
|
183
|
+
) from error
|
|
184
|
+
modules.append(module)
|
|
185
|
+
modules_by_stem[handler_file.stem] = module
|
|
186
|
+
finally:
|
|
187
|
+
if saved is not None:
|
|
188
|
+
sys.modules["gateway_env"] = saved
|
|
189
|
+
else:
|
|
190
|
+
sys.modules.pop("gateway_env", None)
|
|
191
|
+
if path_added:
|
|
192
|
+
try:
|
|
193
|
+
sys.path.remove(bundle_root)
|
|
194
|
+
except ValueError:
|
|
195
|
+
pass
|
|
196
|
+
# Drop bundle-local "tools" modules and restore anything shadowed.
|
|
197
|
+
for name in [
|
|
198
|
+
n for n in sys.modules if n == "tools" or n.startswith("tools.")
|
|
199
|
+
]:
|
|
200
|
+
sys.modules.pop(name, None)
|
|
201
|
+
for name, module in saved_pkgs.items():
|
|
202
|
+
if module is not None:
|
|
203
|
+
sys.modules[name] = module
|
|
204
|
+
runtime._load_registry.reset(load_token)
|
|
205
|
+
runtime._strict_registration.reset(strict_token)
|
|
206
|
+
|
|
207
|
+
# Fallbacks for undecorated bundles.
|
|
208
|
+
for tool_name in manifest.serve:
|
|
209
|
+
if tool_name in registry:
|
|
210
|
+
continue
|
|
211
|
+
# (2) a plain module-level function named exactly like the tool.
|
|
212
|
+
for module in modules:
|
|
213
|
+
candidate = getattr(module, tool_name, None)
|
|
214
|
+
if callable(candidate) and getattr(candidate, "__module__", None) == module.__name__:
|
|
215
|
+
registry[tool_name] = candidate
|
|
216
|
+
break
|
|
217
|
+
else:
|
|
218
|
+
# (3) run(input, conn=None) in tools/<tool_name>.py.
|
|
219
|
+
stem_module = modules_by_stem.get(tool_name)
|
|
220
|
+
run_fn = getattr(stem_module, "run", None) if stem_module else None
|
|
221
|
+
if callable(run_fn):
|
|
222
|
+
registry[tool_name] = _wrap_run_handler(run_fn, tool_name)
|
|
223
|
+
if contract is not None and set(registry) != set(contract.tools):
|
|
224
|
+
from .schema import ContractError
|
|
225
|
+
|
|
226
|
+
raise ContractError("tool", "Authored handlers must exactly cover the declared tools")
|
|
227
|
+
return registry
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
# ---------------------------------------------------------------------------
|
|
231
|
+
# harbor: task enumeration
|
|
232
|
+
# ---------------------------------------------------------------------------
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
@dataclass
|
|
236
|
+
class HarborTask:
|
|
237
|
+
"""One Harbor task dir (``task.toml`` + ``instruction.md`` + ``tests/``)."""
|
|
238
|
+
|
|
239
|
+
name: str
|
|
240
|
+
path: Path
|
|
241
|
+
instruction: Optional[str]
|
|
242
|
+
docker_image: Optional[str]
|
|
243
|
+
has_tests: bool
|
|
244
|
+
config: Dict[str, Any] = field(default_factory=dict)
|
|
245
|
+
|
|
246
|
+
@property
|
|
247
|
+
def prompt(self) -> Optional[str]:
|
|
248
|
+
"""Alias — the task's instruction is its prompt."""
|
|
249
|
+
return self.instruction
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def harbor_tasks_root(bundle_path: Path) -> Path:
|
|
253
|
+
"""The dir whose CHILDREN are task dirs: ``<src>/tasks`` if present, else
|
|
254
|
+
``<src>`` (mirrors ``harbor_adapter.tasks_root``)."""
|
|
255
|
+
tasks = bundle_path / "tasks"
|
|
256
|
+
return tasks if list(tasks.glob("*/task.toml")) else bundle_path
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def load_harbor_tasks(bundle_path: Path) -> List[HarborTask]:
|
|
260
|
+
tasks: List[HarborTask] = []
|
|
261
|
+
for task_toml in sorted(harbor_tasks_root(bundle_path).glob("*/task.toml")):
|
|
262
|
+
task_dir = task_toml.parent
|
|
263
|
+
try:
|
|
264
|
+
config = tomllib.loads(task_toml.read_text(encoding="utf-8"))
|
|
265
|
+
except (OSError, tomllib.TOMLDecodeError) as error:
|
|
266
|
+
raise EnvironmentNotReady(f"cannot parse {task_toml}: {error}") from error
|
|
267
|
+
environment = config.get("environment") if isinstance(config.get("environment"), dict) else {}
|
|
268
|
+
instruction_path = task_dir / "instruction.md"
|
|
269
|
+
tasks.append(
|
|
270
|
+
HarborTask(
|
|
271
|
+
name=task_dir.name,
|
|
272
|
+
path=task_dir,
|
|
273
|
+
instruction=(
|
|
274
|
+
instruction_path.read_text(encoding="utf-8") if instruction_path.is_file() else None
|
|
275
|
+
),
|
|
276
|
+
docker_image=environment.get("docker_image"),
|
|
277
|
+
has_tests=(task_dir / "tests").is_dir(),
|
|
278
|
+
config=config,
|
|
279
|
+
)
|
|
280
|
+
)
|
|
281
|
+
return tasks
|