@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.
Files changed (130) hide show
  1. package/README.md +141 -2
  2. package/dist/cli.js +8683 -1343
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +8683 -1344
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/index.d.mts +1 -1
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.js +979 -46
  9. package/dist/index.js.map +1 -1
  10. package/dist/index.mjs +943 -38
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/tracing/index.js +9 -2
  13. package/dist/tracing/index.js.map +1 -1
  14. package/dist/tracing/index.mjs +9 -2
  15. package/dist/tracing/index.mjs.map +1 -1
  16. package/dist/worlds/index.d.mts +738 -28
  17. package/dist/worlds/index.d.ts +738 -28
  18. package/dist/worlds/index.js +940 -42
  19. package/dist/worlds/index.js.map +1 -1
  20. package/dist/worlds/index.mjs +934 -36
  21. package/dist/worlds/index.mjs.map +1 -1
  22. package/package.json +9 -2
  23. package/runtime/gatewaysdk/__init__.py +0 -0
  24. package/runtime/gatewaysdk/environment/__init__.py +108 -0
  25. package/runtime/gatewaysdk/environment/_bundle.py +281 -0
  26. package/runtime/gatewaysdk/environment/_harbor.py +276 -0
  27. package/runtime/gatewaysdk/environment/_materialize.py +97 -0
  28. package/runtime/gatewaysdk/environment/_tar.py +33 -0
  29. package/runtime/gatewaysdk/environment/_world.py +346 -0
  30. package/runtime/gatewaysdk/environment/core.py +527 -0
  31. package/runtime/gatewaysdk/environment/errors.py +58 -0
  32. package/runtime/gatewaysdk/environment/runtime.py +150 -0
  33. package/runtime/gatewaysdk/environment/schema/__init__.py +35 -0
  34. package/runtime/gatewaysdk/environment/schema/__main__.py +225 -0
  35. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +116 -0
  36. package/runtime/gatewaysdk/environment/schema/_slack_scenario.py +183 -0
  37. package/runtime/gatewaysdk/environment/schema/api.py +1628 -0
  38. package/runtime/gatewaysdk/environment/schema/batch.py +755 -0
  39. package/runtime/gatewaysdk/environment/schema/compiler.py +615 -0
  40. package/runtime/gatewaysdk/environment/schema/conform.py +428 -0
  41. package/runtime/gatewaysdk/environment/schema/connector.py +777 -0
  42. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py +17 -0
  43. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json +28 -0
  44. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json +233 -0
  45. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml +112 -0
  46. package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/world.json +1380 -0
  47. package/runtime/gatewaysdk/environment/schema/connectors/base.json +28 -0
  48. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +18 -0
  49. package/runtime/gatewaysdk/environment/schema/connectors/custom/world.json +123 -0
  50. package/runtime/gatewaysdk/environment/schema/connectors/github/handlers.py +81 -0
  51. package/runtime/gatewaysdk/environment/schema/connectors/github/parity.json +37 -0
  52. package/runtime/gatewaysdk/environment/schema/connectors/github/provenance.json +134 -0
  53. package/runtime/gatewaysdk/environment/schema/connectors/github/scope.toml +158 -0
  54. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +5869 -0
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/handlers.py +23 -0
  56. package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/world.json +209 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/handlers.py +18 -0
  58. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/world.json +286 -0
  59. package/runtime/gatewaysdk/environment/schema/connectors/jamf/handlers.py +34 -0
  60. package/runtime/gatewaysdk/environment/schema/connectors/jamf/parity.json +49 -0
  61. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +181 -0
  62. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +128 -0
  63. package/runtime/gatewaysdk/environment/schema/connectors/jamf/world.json +2218 -0
  64. package/runtime/gatewaysdk/environment/schema/connectors/jira/handlers.py +28 -0
  65. package/runtime/gatewaysdk/environment/schema/connectors/jira/world.json +389 -0
  66. package/runtime/gatewaysdk/environment/schema/connectors/kandji/handlers.py +38 -0
  67. package/runtime/gatewaysdk/environment/schema/connectors/kandji/parity.json +29 -0
  68. package/runtime/gatewaysdk/environment/schema/connectors/kandji/provenance.json +152 -0
  69. package/runtime/gatewaysdk/environment/schema/connectors/kandji/scope.toml +120 -0
  70. package/runtime/gatewaysdk/environment/schema/connectors/kandji/world.json +765 -0
  71. package/runtime/gatewaysdk/environment/schema/connectors/linear/handlers.py +20 -0
  72. package/runtime/gatewaysdk/environment/schema/connectors/linear/world.json +363 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/fidelity.json +45 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/handlers.py +1 -0
  75. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/provenance.json +851 -0
  76. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md +231 -0
  77. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/teams-types.json +1710 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/world.json +858 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/handlers.py +32 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/parity.json +50 -0
  81. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/provenance.json +137 -0
  82. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/scope.toml +78 -0
  83. package/runtime/gatewaysdk/environment/schema/connectors/netsuite/world.json +16243 -0
  84. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/handlers.py +806 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/parity.json +46 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/provenance.json +143 -0
  87. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/scope.toml +174 -0
  88. package/runtime/gatewaysdk/environment/schema/connectors/salesforce/world.json +4695 -0
  89. package/runtime/gatewaysdk/environment/schema/connectors/slack/MODEL.md +236 -0
  90. package/runtime/gatewaysdk/environment/schema/connectors/slack/capabilities.json +1039 -0
  91. package/runtime/gatewaysdk/environment/schema/connectors/slack/handlers.py +762 -0
  92. package/runtime/gatewaysdk/environment/schema/connectors/slack/parity.json +65 -0
  93. package/runtime/gatewaysdk/environment/schema/connectors/slack/provenance.json +294 -0
  94. package/runtime/gatewaysdk/environment/schema/connectors/slack/scope.toml +44 -0
  95. package/runtime/gatewaysdk/environment/schema/connectors/slack/world.json +4993 -0
  96. package/runtime/gatewaysdk/environment/schema/connectors/workday/handlers.py +75 -0
  97. package/runtime/gatewaysdk/environment/schema/connectors/workday/parity.json +36 -0
  98. package/runtime/gatewaysdk/environment/schema/connectors/workday/provenance.json +179 -0
  99. package/runtime/gatewaysdk/environment/schema/connectors/workday/scope.toml +180 -0
  100. package/runtime/gatewaysdk/environment/schema/connectors/workday/world.json +806 -0
  101. package/runtime/gatewaysdk/environment/schema/data.py +593 -0
  102. package/runtime/gatewaysdk/environment/schema/extract.py +263 -0
  103. package/runtime/gatewaysdk/environment/schema/host.py +2407 -0
  104. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +275 -0
  105. package/runtime/gatewaysdk/environment/schema/platform.py +1272 -0
  106. package/runtime/gatewaysdk/environment/schema/scaffold.py +250 -0
  107. package/runtime/gatewaysdk/environment/schema/skill.py +118 -0
  108. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +202 -0
  109. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  110. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  111. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +313 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +223 -0
  113. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +293 -0
  114. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +390 -0
  115. package/runtime/gatewaysdk/environment/schema/slack.py +757 -0
  116. package/runtime/gatewaysdk/environment/schema/snapshot.py +479 -0
  117. package/runtime/gatewaysdk/environment/schema/store.py +904 -0
  118. package/runtime/gatewaysdk/environment/schema/tasks.py +525 -0
  119. package/runtime/gatewaysdk/environment/schema/tools_world.py +322 -0
  120. package/runtime/gatewaysdk/environment/schema/validation.py +577 -0
  121. package/runtime/gatewaysdk/environment/schema/worker.py +78 -0
  122. package/runtime/gatewaysdk/environment/schema/workers.py +500 -0
  123. package/runtime/gatewaysdk/environment/schema/world_tests.py +336 -0
  124. package/skills/agents/connector-template-author.md +202 -0
  125. package/skills/connector-schema-authoring/CONNECTORS.md +331 -0
  126. package/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
  127. package/skills/connector-schema-authoring/SKILL.md +313 -0
  128. package/skills/world-data-ingestion/ROWS.md +223 -0
  129. package/skills/world-data-ingestion/SKILL.md +293 -0
  130. 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.1.20",
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