gts-agency-python-sdk 0.0.1__py3-none-any.whl

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 (66) hide show
  1. agency_sdk/__init__.py +0 -0
  2. agency_sdk/auth_hooks.py +55 -0
  3. agency_sdk/client.py +212 -0
  4. agency_sdk/credentials.py +54 -0
  5. agency_sdk/delegates/__init__.py +0 -0
  6. agency_sdk/delegates/annotations_client.py +495 -0
  7. agency_sdk/delegates/annotations_dto.py +200 -0
  8. agency_sdk/delegates/base_client.py +126 -0
  9. agency_sdk/delegates/datasets_client.py +109 -0
  10. agency_sdk/delegates/datasets_dto.py +81 -0
  11. agency_sdk/delegates/datasource_client.py +44 -0
  12. agency_sdk/delegates/datasource_dto.py +107 -0
  13. agency_sdk/delegates/files_client.py +184 -0
  14. agency_sdk/delegates/files_dto.py +36 -0
  15. agency_sdk/delegates/gateway_client.py +81 -0
  16. agency_sdk/delegates/gateway_dto.py +37 -0
  17. agency_sdk/delegates/ontology_client.py +203 -0
  18. agency_sdk/delegates/ontology_dto.py +221 -0
  19. agency_sdk/delegates/prompts_client.py +56 -0
  20. agency_sdk/delegates/rules_client.py +33 -0
  21. agency_sdk/delegates/rules_dto.py +108 -0
  22. agency_sdk/delegates/session_client.py +95 -0
  23. agency_sdk/delegates/session_dto.py +94 -0
  24. agency_sdk/delegates/session_templates_client.py +23 -0
  25. agency_sdk/delegates/session_templates_dto.py +27 -0
  26. agency_sdk/delegates/session_vault_client.py +135 -0
  27. agency_sdk/delegates/session_vault_dto.py +75 -0
  28. agency_sdk/delegates/work_queue_client.py +230 -0
  29. agency_sdk/delegates/work_queue_dto.py +127 -0
  30. agency_sdk/domain.py +140 -0
  31. agency_sdk/observability/__init__.py +60 -0
  32. agency_sdk/observability/auth.py +15 -0
  33. agency_sdk/observability/bootstrap.py +344 -0
  34. agency_sdk/test/__init__.py +0 -0
  35. agency_sdk/test/conftest.py +106 -0
  36. agency_sdk/test/test_annotations_client.py +599 -0
  37. agency_sdk/test/test_annotations_dto.py +299 -0
  38. agency_sdk/test/test_base_client.py +153 -0
  39. agency_sdk/test/test_client_facade.py +105 -0
  40. agency_sdk/test/test_credentials.py +67 -0
  41. agency_sdk/test/test_files_client.py +264 -0
  42. agency_sdk/test/test_files_dto.py +93 -0
  43. agency_sdk/test/test_gateway_dto.py +70 -0
  44. agency_sdk/test/test_gateway_facade.py +229 -0
  45. agency_sdk/test/test_gateway_openai.py +76 -0
  46. agency_sdk/test/test_observability_auth.py +125 -0
  47. agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
  48. agency_sdk/test/test_observability_langfuse.py +76 -0
  49. agency_sdk/test/test_observability_packaging.py +78 -0
  50. agency_sdk/test/test_observability_pipeline.py +246 -0
  51. agency_sdk/test/test_ontology_client.py +152 -0
  52. agency_sdk/test/test_ontology_dto.py +158 -0
  53. agency_sdk/test/test_session_client.py +128 -0
  54. agency_sdk/test/test_session_dto.py +75 -0
  55. agency_sdk/test/test_session_templates_client.py +36 -0
  56. agency_sdk/test/test_session_templates_dto.py +45 -0
  57. agency_sdk/test/test_session_vault_client.py +151 -0
  58. agency_sdk/test/test_session_vault_dto.py +27 -0
  59. agency_sdk/test/test_stub_requests.py +39 -0
  60. agency_sdk/test/test_work_queue_client.py +388 -0
  61. agency_sdk/test/test_work_queue_dto.py +233 -0
  62. gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
  63. gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
  64. gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
  65. gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
  66. gts_agency_python_sdk-0.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,264 @@
1
+ """Offline protocol tests for AgencyFilesClient.
2
+
3
+ Every test asserts the exact wire contract (URL, query params, headers, body)
4
+ verified against gts-agency-control/src/handler/files.rs.
5
+ """
6
+
7
+ import pytest
8
+
9
+ from agency_sdk.delegates.files_client import AgencyFilesClient
10
+ from agency_sdk.test.test_files_dto import FILE_ENTRY_JSON, FOLDER_ENTRY_JSON
11
+
12
+ PAGED_JSON = {
13
+ "page": {"page": 0, "size": 50, "total": 2},
14
+ "items": [FILE_ENTRY_JSON, FOLDER_ENTRY_JSON],
15
+ }
16
+
17
+ SIGNED_URL_JSON = {
18
+ "signed_url": "https://storage.googleapis.com/files/abc?X-Goog-Signature=sig",
19
+ "expires_at": "2026-06-10T12:15:00Z",
20
+ "file": FILE_ENTRY_JSON,
21
+ }
22
+
23
+
24
+ @pytest.fixture
25
+ def client(fake_credentials):
26
+ return AgencyFilesClient(token_supplier=fake_credentials, base_url="http://cp.test/")
27
+
28
+
29
+ def signed_url_for(content: bytes) -> dict:
30
+ """A signed-url response whose file size_bytes matches the given content."""
31
+ return {
32
+ "signed_url": "https://storage.googleapis.com/files/abc?X-Goog-Signature=sig",
33
+ "expires_at": "2026-06-10T12:15:00Z",
34
+ "file": {**FILE_ENTRY_JSON, "size_bytes": len(content)},
35
+ }
36
+
37
+
38
+ class TestDownload:
39
+ def test_download_streams_signed_url_to_target(self, client, stub_requests, tmp_path):
40
+ content = b"%PDF-1.7 fake content"
41
+ stub_requests.queue(json_data=signed_url_for(content))
42
+ stub_requests.queue(content_bytes=content)
43
+ target = tmp_path / "nested" / "dir" / "out.pdf"
44
+
45
+ entry = client.download(file_id="abc-123", organisation_id=2, target_path=target)
46
+
47
+ signed_call, blob_call = stub_requests.calls
48
+ assert signed_call.url == "http://cp.test/api/files/abc-123/_signed-url"
49
+ assert blob_call.method == "GET"
50
+ assert blob_call.kwargs["stream"] is True
51
+ assert blob_call.kwargs["timeout"] == 300
52
+ assert target.read_bytes() == content
53
+ assert entry.name == "report.pdf"
54
+
55
+ def test_download_accepts_string_target_path(self, client, stub_requests, tmp_path):
56
+ content = b"x"
57
+ stub_requests.queue(json_data=signed_url_for(content))
58
+ stub_requests.queue(content_bytes=content)
59
+
60
+ client.download(file_id="abc-123", organisation_id=2, target_path=str(tmp_path / "plain.bin"))
61
+
62
+ assert (tmp_path / "plain.bin").read_bytes() == content
63
+
64
+ def test_download_raises_on_truncated_stream(self, client, stub_requests, tmp_path):
65
+ # signed URL advertises a larger size than the bytes actually streamed
66
+ stub_requests.queue(json_data=signed_url_for(b"x" * 100))
67
+ stub_requests.queue(content_bytes=b"x" * 40)
68
+
69
+ with pytest.raises(IOError):
70
+ client.download(file_id="abc-123", organisation_id=2, target_path=tmp_path / "short.bin")
71
+
72
+
73
+ class TestResolveGtsfUri:
74
+ def test_resolves_valid_uri_via_signed_url_endpoint(self, client, stub_requests):
75
+ stub_requests.queue(json_data=SIGNED_URL_JSON)
76
+
77
+ result = client.resolve_gtsf_uri("gtsf://550e8400-e29b-41d4-a716-446655440000", organisation_id=2)
78
+
79
+ call = stub_requests.calls[0]
80
+ assert call.url == "http://cp.test/api/files/550e8400-e29b-41d4-a716-446655440000/_signed-url"
81
+ assert call.kwargs["params"] == {"o": "2"}
82
+ assert result.signed_url == SIGNED_URL_JSON["signed_url"]
83
+
84
+ def test_resolve_forwards_expires(self, client, stub_requests):
85
+ stub_requests.queue(json_data=SIGNED_URL_JSON)
86
+
87
+ client.resolve_gtsf_uri("gtsf://abc-123", organisation_id=2, expires=120)
88
+
89
+ assert stub_requests.calls[0].kwargs["params"] == {"o": "2", "expires": "120"}
90
+
91
+ @pytest.mark.parametrize(
92
+ "bad_uri",
93
+ [
94
+ "https://example.com/file", # wrong scheme
95
+ "gtsf://", # empty id
96
+ "gtsf://abc/123", # embedded slash
97
+ "GTSF://abc-123", # uppercase scheme (strict lowercase)
98
+ "abc-123", # bare id, no scheme
99
+ "", # empty string
100
+ ],
101
+ )
102
+ def test_rejects_malformed_uris_before_any_network_call(self, client, stub_requests, bad_uri):
103
+ with pytest.raises(ValueError):
104
+ client.resolve_gtsf_uri(bad_uri, organisation_id=2)
105
+
106
+ assert stub_requests.calls == []
107
+
108
+
109
+ class TestUpload:
110
+ def test_upload_sends_repeated_file_multipart_fields(self, client, stub_requests, tmp_path):
111
+ report = tmp_path / "report.txt"
112
+ report.write_bytes(b"hello")
113
+ blob = tmp_path / "data.unknownext"
114
+ blob.write_bytes(b"\x00\x01")
115
+ stub_requests.queue(json_data={"uploaded": [FILE_ENTRY_JSON, FOLDER_ENTRY_JSON]})
116
+
117
+ result = client.upload(organisation_id=2, file_paths=[report, str(blob)], path="guidelines")
118
+
119
+ call = stub_requests.calls[0]
120
+ assert call.method == "POST"
121
+ assert call.url == "http://cp.test/api/files/_upload"
122
+ assert call.kwargs["params"] == {"o": "2", "path": "guidelines"}
123
+ assert call.kwargs["timeout"] == 300
124
+
125
+ files = call.kwargs["files"]
126
+ assert [field for field, _ in files] == ["file", "file"]
127
+ assert files[0][1][0] == "report.txt"
128
+ assert files[0][1][2] == "text/plain"
129
+ assert files[1][1][0] == "data.unknownext"
130
+ assert files[1][1][2] is None
131
+ assert len(result.uploaded) == 2
132
+
133
+ def test_upload_has_no_json_content_type_header(self, client, stub_requests, tmp_path):
134
+ f = tmp_path / "a.txt"
135
+ f.write_bytes(b"x")
136
+ stub_requests.queue(json_data={"uploaded": [FILE_ENTRY_JSON]})
137
+
138
+ client.upload(organisation_id=2, file_paths=[f])
139
+
140
+ headers = stub_requests.calls[0].kwargs["headers"]
141
+ assert headers["Authorization"] == "Bearer test-token"
142
+ assert "Content-Type" not in headers
143
+ assert stub_requests.calls[0].kwargs["params"] == {"o": "2", "path": ""}
144
+
145
+ def test_upload_rejects_empty_file_list_before_network(self, client, stub_requests):
146
+ with pytest.raises(ValueError):
147
+ client.upload(organisation_id=2, file_paths=[])
148
+
149
+ assert stub_requests.calls == []
150
+
151
+
152
+ class TestCreateFolder:
153
+ def test_create_folder_posts_json_body(self, client, stub_requests):
154
+ stub_requests.queue(json_data=FOLDER_ENTRY_JSON)
155
+
156
+ result = client.create_folder(organisation_id=2, name="guidelines")
157
+
158
+ call = stub_requests.calls[0]
159
+ assert call.method == "POST"
160
+ assert call.url == "http://cp.test/api/files/_folder"
161
+ assert call.kwargs["params"] == {"o": "2"}
162
+ assert call.kwargs["json"] == {"folder_path": "", "name": "guidelines"}
163
+ assert result.is_folder is True
164
+ assert result.name == "guidelines"
165
+
166
+ def test_create_folder_under_parent_path(self, client, stub_requests):
167
+ stub_requests.queue(json_data=FOLDER_ENTRY_JSON)
168
+
169
+ client.create_folder(organisation_id=2, name="2026", folder_path="guidelines")
170
+
171
+ assert stub_requests.calls[0].kwargs["json"] == {"folder_path": "guidelines", "name": "2026"}
172
+
173
+ def test_create_folder_propagates_409_conflict(self, client, stub_requests):
174
+ import requests
175
+
176
+ stub_requests.queue(json_data={"message": "already exists"}, status_code=409)
177
+
178
+ with pytest.raises(requests.HTTPError):
179
+ client.create_folder(organisation_id=2, name="guidelines")
180
+
181
+
182
+ class TestDelete:
183
+ def test_delete_file_hits_id_endpoint_and_returns_none(self, client, stub_requests):
184
+ stub_requests.queue(json_data={"status": "deleted"})
185
+
186
+ result = client.delete_file(file_id="abc-123", organisation_id=2)
187
+
188
+ call = stub_requests.calls[0]
189
+ assert call.method == "DELETE"
190
+ assert call.url == "http://cp.test/api/files/abc-123"
191
+ assert call.kwargs["params"] == {"o": "2"}
192
+ assert result is None
193
+
194
+ def test_delete_folder_requires_path_param(self, client, stub_requests):
195
+ stub_requests.queue(json_data={"status": "deleted"})
196
+
197
+ result = client.delete_folder(organisation_id=2, path="guidelines/2026")
198
+
199
+ call = stub_requests.calls[0]
200
+ assert call.method == "DELETE"
201
+ assert call.url == "http://cp.test/api/files/_folder"
202
+ assert call.kwargs["params"] == {"o": "2", "path": "guidelines/2026"}
203
+ assert result is None
204
+
205
+ def test_delete_file_propagates_400_for_folder_ids(self, client, stub_requests):
206
+ import requests
207
+
208
+ stub_requests.queue(json_data={"message": "Use folder delete for folders"}, status_code=400)
209
+
210
+ with pytest.raises(requests.HTTPError):
211
+ client.delete_file(file_id="folder-id", organisation_id=2)
212
+
213
+
214
+ class TestSignedUrl:
215
+ def test_signed_url_without_expires(self, client, stub_requests):
216
+ stub_requests.queue(json_data=SIGNED_URL_JSON)
217
+
218
+ result = client.signed_url(file_id="abc-123", organisation_id=2)
219
+
220
+ call = stub_requests.calls[0]
221
+ assert call.method == "GET"
222
+ assert call.url == "http://cp.test/api/files/abc-123/_signed-url"
223
+ assert call.kwargs["params"] == {"o": "2"}
224
+ assert result.signed_url == SIGNED_URL_JSON["signed_url"]
225
+ assert result.file.name == "report.pdf"
226
+
227
+ def test_signed_url_with_expires(self, client, stub_requests):
228
+ stub_requests.queue(json_data=SIGNED_URL_JSON)
229
+
230
+ client.signed_url(file_id="abc-123", organisation_id=2, expires=3600)
231
+
232
+ assert stub_requests.calls[0].kwargs["params"] == {"o": "2", "expires": "3600"}
233
+
234
+ def test_signed_url_propagates_http_errors(self, client, stub_requests):
235
+ import requests
236
+
237
+ stub_requests.queue(json_data={"message": "File not found"}, status_code=404)
238
+
239
+ with pytest.raises(requests.HTTPError):
240
+ client.signed_url(file_id="missing", organisation_id=2)
241
+
242
+
243
+ class TestList:
244
+ def test_list_hits_files_endpoint_with_defaults(self, client, stub_requests):
245
+ stub_requests.queue(json_data=PAGED_JSON)
246
+
247
+ result = client.list(organisation_id=2)
248
+
249
+ call = stub_requests.calls[0]
250
+ assert call.method == "GET"
251
+ assert call.url == "http://cp.test/api/files"
252
+ assert call.kwargs["params"] == {"o": "2", "path": "", "p": "0", "s": "50"}
253
+ assert call.kwargs["headers"]["Authorization"] == "Bearer test-token"
254
+ assert result.page.total == 2
255
+ assert result.items[0].name == "report.pdf"
256
+ assert result.items[1].is_folder is True
257
+
258
+ def test_list_passes_path_and_pagination(self, client, stub_requests):
259
+ stub_requests.queue(json_data={"page": {"page": 3, "size": 5, "total": 0}, "items": []})
260
+
261
+ client.list(organisation_id=9, path="guidelines/2026", page=3, size=5)
262
+
263
+ params = stub_requests.calls[0].kwargs["params"]
264
+ assert params == {"o": "9", "path": "guidelines/2026", "p": "3", "s": "5"}
@@ -0,0 +1,93 @@
1
+ """DTO deserialisation tests for the files delegate.
2
+
3
+ JSON samples are transcribed from the server DTOs in
4
+ gts-agency-control/src/service/tenant_files/tenant_files_dto.rs.
5
+ """
6
+
7
+ from agency_sdk.delegates.files_dto import (
8
+ FileEntry,
9
+ FilesPagedResult,
10
+ SignedUrlResponse,
11
+ UploadResult,
12
+ )
13
+
14
+ FILE_ENTRY_JSON = {
15
+ "id": "550e8400-e29b-41d4-a716-446655440000",
16
+ "name": "report.pdf",
17
+ "folder_path": "guidelines/2026",
18
+ "path": "guidelines/2026/report.pdf",
19
+ "is_folder": False,
20
+ "content_type": "application/pdf",
21
+ "size_bytes": 12345,
22
+ "uploaded_by": 7,
23
+ "created_on": "2026-06-10T12:00:00Z",
24
+ }
25
+
26
+ FOLDER_ENTRY_JSON = {
27
+ "id": "f0000000-0000-0000-0000-000000000001",
28
+ "name": "guidelines",
29
+ "folder_path": "",
30
+ "path": "guidelines",
31
+ "is_folder": True,
32
+ "content_type": None,
33
+ "size_bytes": 0,
34
+ "uploaded_by": 7,
35
+ "created_on": "2026-06-09T08:30:00Z",
36
+ }
37
+
38
+
39
+ def test_file_entry_deserialises_from_server_json():
40
+ entry = FileEntry(**FILE_ENTRY_JSON)
41
+
42
+ assert entry.id == "550e8400-e29b-41d4-a716-446655440000"
43
+ assert entry.name == "report.pdf"
44
+ assert entry.folder_path == "guidelines/2026"
45
+ assert entry.path == "guidelines/2026/report.pdf"
46
+ assert entry.is_folder is False
47
+ assert entry.content_type == "application/pdf"
48
+ assert entry.size_bytes == 12345
49
+ assert entry.uploaded_by == 7
50
+ assert entry.created_on == "2026-06-10T12:00:00Z"
51
+
52
+
53
+ def test_folder_entry_allows_null_content_type_and_root_folder_path():
54
+ entry = FileEntry(**FOLDER_ENTRY_JSON)
55
+
56
+ assert entry.is_folder is True
57
+ assert entry.content_type is None
58
+ assert entry.folder_path == ""
59
+
60
+
61
+ def test_files_paged_result_matches_server_paged_shape():
62
+ result = FilesPagedResult(
63
+ **{
64
+ "page": {"page": 0, "size": 50, "total": 2},
65
+ "items": [FILE_ENTRY_JSON, FOLDER_ENTRY_JSON],
66
+ }
67
+ )
68
+
69
+ assert result.page.total == 2
70
+ assert result.page.size == 50
71
+ assert len(result.items) == 2
72
+ assert result.items[1].is_folder is True
73
+
74
+
75
+ def test_upload_result_wraps_uploaded_entries():
76
+ result = UploadResult(**{"uploaded": [FILE_ENTRY_JSON]})
77
+
78
+ assert len(result.uploaded) == 1
79
+ assert result.uploaded[0].name == "report.pdf"
80
+
81
+
82
+ def test_signed_url_response_carries_file_metadata():
83
+ response = SignedUrlResponse(
84
+ **{
85
+ "signed_url": "https://storage.googleapis.com/files/abc?X-Goog-Signature=sig",
86
+ "expires_at": "2026-06-10T12:15:00Z",
87
+ "file": FILE_ENTRY_JSON,
88
+ }
89
+ )
90
+
91
+ assert response.signed_url.startswith("https://storage.googleapis.com/")
92
+ assert response.expires_at == "2026-06-10T12:15:00Z"
93
+ assert response.file.id == FILE_ENTRY_JSON["id"]
@@ -0,0 +1,70 @@
1
+ """Offline DTO tests for agent gateway URL discovery.
2
+
3
+ Discovery DTOs are modeled from the control-plane Rust source
4
+ (agent_gateway_dto.rs:24-47) and live-verified 2026-07-07: the endpoint returns
5
+ a Page-wrapped payload and slots carry extra fields tolerated via
6
+ ``extra="allow"``. Chat request/response DTOs no longer live here — the gateway
7
+ hands back official ``openai`` clients, which own those types.
8
+ """
9
+
10
+ from agency_sdk.delegates.gateway_dto import (
11
+ AgentGatewayEnvironmentResponse,
12
+ AgentGatewayStatusResponse,
13
+ )
14
+
15
+
16
+ def test_discovery_status_parses_both_slots():
17
+ payload = {
18
+ "enabled": True,
19
+ "code": "gateway-1a2b3c4d",
20
+ "production": {
21
+ "environment": "production",
22
+ "status": "ready",
23
+ "url": "https://agentgateway-org-2-wadexavawa-uk.a.run.app",
24
+ "version": 3,
25
+ },
26
+ "test": {
27
+ "environment": "test",
28
+ "status": "ready",
29
+ "url": "https://agentgateway-org-2-test-wadexavawa-uk.a.run.app",
30
+ "version": 4,
31
+ },
32
+ }
33
+
34
+ status = AgentGatewayStatusResponse(**payload)
35
+
36
+ assert status.enabled is True
37
+ assert status.production is not None
38
+ assert status.production.url == "https://agentgateway-org-2-wadexavawa-uk.a.run.app"
39
+ assert status.test is not None
40
+ assert status.test.url == "https://agentgateway-org-2-test-wadexavawa-uk.a.run.app"
41
+
42
+
43
+ def test_discovery_status_tolerates_missing_slots_and_url():
44
+ status = AgentGatewayStatusResponse(enabled=False)
45
+
46
+ assert status.production is None
47
+ assert status.test is None
48
+ assert status.code is None
49
+
50
+ provisioning = AgentGatewayEnvironmentResponse(environment="test", status="provisioning")
51
+ assert provisioning.url is None
52
+ assert provisioning.version is None
53
+
54
+
55
+ def test_discovery_status_retains_unknown_slot_fields():
56
+ # Live payload carries id/vendor/runtime/manages_lifecycle beyond the modeled
57
+ # fields — extra="allow" keeps them instead of rejecting the response.
58
+ status = AgentGatewayStatusResponse(
59
+ enabled=True,
60
+ production={
61
+ "environment": "production",
62
+ "status": "ready",
63
+ "url": "https://gw.example",
64
+ "vendor": "agentgateway",
65
+ "manages_lifecycle": True,
66
+ },
67
+ )
68
+
69
+ assert status.production is not None
70
+ assert status.production.model_dump()["vendor"] == "agentgateway"
@@ -0,0 +1,229 @@
1
+ """Facade tests for AgencyClient.gateway(...) and control-plane URL discovery.
2
+
3
+ The accessor mirrors the observability precedent (DCL cache, shared
4
+ CredentialsSupplier) but targets the gateway's own Cloud Run host and keys
5
+ the cache per (org_id, gateway_base_url/environment) identity — a multi-org
6
+ process must never get org A's x-org/host when it asked for org B. Discovery
7
+ (GET /api/agentgateways?o={org}) is source-modeled from the control-plane DTO
8
+ and verification-deferred (design §4/§10 decision 1) — these offline tests are
9
+ its only verification for now.
10
+ """
11
+
12
+ import threading
13
+ import time
14
+
15
+ import pytest
16
+
17
+ import agency_sdk.delegates.gateway_client as gateway_module
18
+ from agency_sdk.client import AgencyClient
19
+ from agency_sdk.delegates.gateway_client import AgencyGatewayClient
20
+
21
+ PROD_URL = "https://agentgateway-org-2-wadexavawa-uk.a.run.app"
22
+ TEST_URL = "https://agentgateway-org-2-test-wadexavawa-uk.a.run.app"
23
+
24
+ DISCOVERY_ITEM = {
25
+ "enabled": True,
26
+ "code": "gateway-1a2b3c4d",
27
+ "production": {"environment": "production", "status": "ready", "url": PROD_URL, "version": 3},
28
+ "test": {"environment": "test", "status": "ready", "url": TEST_URL, "version": 4},
29
+ }
30
+
31
+
32
+ @pytest.fixture
33
+ def client(fake_credentials):
34
+ return AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
35
+
36
+
37
+ def test_gateway_with_explicit_url_builds_bound_client(client, fake_credentials):
38
+ gateway = client.gateway(org_id="2", gateway_base_url="http://gw.test:4000/")
39
+
40
+ assert isinstance(gateway, AgencyGatewayClient)
41
+ assert gateway.token_supplier is fake_credentials # shared creds, one cached token
42
+ assert gateway.gateway_base_url == "http://gw.test:4000"
43
+ assert gateway.org_id == "2"
44
+
45
+
46
+ def test_gateway_returns_same_instance(client):
47
+ first = client.gateway(org_id="2", gateway_base_url="http://gw.test:4000")
48
+
49
+ assert client.gateway(org_id="2", gateway_base_url="http://gw.test:4000") is first
50
+
51
+
52
+ def test_gateway_is_thread_safe(monkeypatch, client):
53
+ real_cls = gateway_module.AgencyGatewayClient
54
+ count = {"n": 0}
55
+ count_lock = threading.Lock()
56
+
57
+ def counting(*args, **kwargs):
58
+ with count_lock:
59
+ count["n"] += 1
60
+ time.sleep(0.01) # widen the race window so an unguarded build builds N times
61
+ return real_cls(*args, **kwargs)
62
+
63
+ monkeypatch.setattr(gateway_module, "AgencyGatewayClient", counting)
64
+
65
+ n_threads = 8
66
+ results: list = []
67
+ results_lock = threading.Lock()
68
+ barrier = threading.Barrier(n_threads)
69
+
70
+ def worker():
71
+ barrier.wait() # release all threads together
72
+ instance = client.gateway(org_id="2", gateway_base_url="http://gw.test:4000")
73
+ with results_lock:
74
+ results.append(instance)
75
+
76
+ threads = [threading.Thread(target=worker) for _ in range(n_threads)]
77
+ for t in threads:
78
+ t.start()
79
+ for t in threads:
80
+ t.join()
81
+
82
+ assert count["n"] == 1 # constructed exactly once despite concurrent callers
83
+ assert len(results) == n_threads
84
+ assert all(instance is results[0] for instance in results)
85
+
86
+
87
+ def test_gateway_discovers_production_url_when_base_url_omitted(stub_requests, client):
88
+ stub_requests.queue(json_data=[DISCOVERY_ITEM])
89
+
90
+ gateway = client.gateway(org_id="2")
91
+
92
+ assert gateway.gateway_base_url == PROD_URL
93
+ call = stub_requests.calls[0]
94
+ assert call.method == "GET"
95
+ assert call.url == "http://cp.test/api/agentgateways" # control-plane host, not gateway
96
+ assert call.kwargs["params"] == {"o": "2"}
97
+ assert call.kwargs["headers"]["Authorization"] == "Bearer test-token"
98
+
99
+
100
+ def test_gateway_discovers_test_url_for_environment_test(stub_requests, client):
101
+ stub_requests.queue(json_data=[DISCOVERY_ITEM])
102
+
103
+ gateway = client.gateway(org_id="2", environment="test")
104
+
105
+ assert gateway.gateway_base_url == TEST_URL
106
+
107
+
108
+ def test_discovery_accepts_page_wrapped_items(stub_requests, client):
109
+ # Control-plane list endpoints commonly wrap results; tolerate {"items": [...]}.
110
+ stub_requests.queue(json_data={"items": [DISCOVERY_ITEM]})
111
+
112
+ gateway = client.gateway(org_id="2")
113
+
114
+ assert gateway.gateway_base_url == PROD_URL
115
+
116
+
117
+ def test_discovery_raises_on_empty_result(stub_requests, client):
118
+ stub_requests.queue(json_data=[])
119
+
120
+ with pytest.raises(ValueError, match="org 2"):
121
+ client.gateway(org_id="2")
122
+
123
+
124
+ def test_discovery_raises_when_slot_or_url_missing(stub_requests, client):
125
+ # Gateway enabled but the test slot is still provisioning (no URL yet).
126
+ item = {
127
+ "enabled": True,
128
+ "production": {"environment": "production", "status": "ready", "url": PROD_URL},
129
+ "test": {"environment": "test", "status": "provisioning", "url": None},
130
+ }
131
+ stub_requests.queue(json_data=[item])
132
+
133
+ with pytest.raises(ValueError, match="test"):
134
+ client.gateway(org_id="2", environment="test")
135
+
136
+
137
+ def test_discovery_rejects_unknown_environment(client):
138
+ with pytest.raises(ValueError, match="environment"):
139
+ client.gateway(org_id="2", environment="staging")
140
+
141
+
142
+ def test_gateway_rejects_url_and_environment_together(stub_requests, client):
143
+ # Either give the URL, or give env (with discovery) — never both. Previously
144
+ # environment was silently ignored when a URL was given (API wart).
145
+ with pytest.raises(ValueError, match="environment"):
146
+ client.gateway(org_id="2", gateway_base_url="http://gw.test:4000", environment="test")
147
+
148
+ assert stub_requests.calls == [] # fails fast, before any network call
149
+ assert client.gateway(org_id="2", gateway_base_url="http://gw.test:4000") is not None # URL-only still fine
150
+
151
+
152
+ # --- Cache identity: one instance per (org_id, gateway_base_url/environment) ---
153
+ # The cache must never hand org B a client stamped with org A's x-org header and
154
+ # host (the first-call-wins footgun): each distinct identity gets its own client.
155
+
156
+
157
+ def test_gateway_builds_distinct_instances_per_org(client):
158
+ org2 = client.gateway(org_id="2", gateway_base_url="http://gw2.test:4000")
159
+ org7 = client.gateway(org_id="7", gateway_base_url="http://gw7.test:4000")
160
+
161
+ assert org2 is not org7
162
+ assert (org2.org_id, org2.gateway_base_url) == ("2", "http://gw2.test:4000")
163
+ assert (org7.org_id, org7.gateway_base_url) == ("7", "http://gw7.test:4000") # not org 2's host/x-org
164
+ assert client.gateway(org_id="2", gateway_base_url="http://gw2.test:4000") is org2 # same args still cached
165
+
166
+
167
+ def test_gateway_builds_distinct_instances_per_environment(stub_requests, client):
168
+ stub_requests.queue(json_data=[DISCOVERY_ITEM])
169
+ stub_requests.queue(json_data=[DISCOVERY_ITEM])
170
+
171
+ production = client.gateway(org_id="2")
172
+ test = client.gateway(org_id="2", environment="test")
173
+
174
+ assert production is not test
175
+ assert production.gateway_base_url == PROD_URL
176
+ assert test.gateway_base_url == TEST_URL # not silently the cached production instance
177
+ assert len(stub_requests.calls) == 2 # one discovery round-trip per environment
178
+
179
+
180
+ def test_gateway_discovery_runs_once_per_org_and_environment(stub_requests, client):
181
+ stub_requests.queue(json_data=[DISCOVERY_ITEM])
182
+
183
+ first = client.gateway(org_id="2", environment="test")
184
+
185
+ assert client.gateway(org_id="2", environment="test") is first
186
+ assert len(stub_requests.calls) == 1 # URL resolved once, then served from the cache
187
+
188
+
189
+ def test_gateway_normalizes_url_for_cache_identity(client):
190
+ first = client.gateway(org_id="2", gateway_base_url="http://gw.test:4000")
191
+
192
+ assert client.gateway(org_id="2", gateway_base_url="http://gw.test:4000/") is first # trailing slash, same host
193
+
194
+
195
+ def test_gateway_thread_safety_builds_once_per_identity(monkeypatch, client):
196
+ real_cls = gateway_module.AgencyGatewayClient
197
+ count = {"n": 0}
198
+ count_lock = threading.Lock()
199
+
200
+ def counting(*args, **kwargs):
201
+ with count_lock:
202
+ count["n"] += 1
203
+ time.sleep(0.01) # widen the race window so an unguarded build builds N times
204
+ return real_cls(*args, **kwargs)
205
+
206
+ monkeypatch.setattr(gateway_module, "AgencyGatewayClient", counting)
207
+
208
+ n_threads = 8
209
+ orgs = ["2", "7"]
210
+ results: dict[str, list] = {org: [] for org in orgs}
211
+ results_lock = threading.Lock()
212
+ barrier = threading.Barrier(n_threads)
213
+
214
+ def worker(org: str):
215
+ barrier.wait() # release all threads together
216
+ instance = client.gateway(org_id=org, gateway_base_url=f"http://gw{org}.test:4000")
217
+ with results_lock:
218
+ results[org].append(instance)
219
+
220
+ threads = [threading.Thread(target=worker, args=(orgs[i % len(orgs)],)) for i in range(n_threads)]
221
+ for t in threads:
222
+ t.start()
223
+ for t in threads:
224
+ t.join()
225
+
226
+ assert count["n"] == len(orgs) # exactly one build per identity despite concurrent callers
227
+ for org in orgs:
228
+ assert all(instance is results[org][0] for instance in results[org])
229
+ assert results[org][0].org_id == org