traceforge-pcb 1.0.0__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 (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,690 @@
1
+ """Hosted traceforge server (FastAPI + WebSocket).
2
+
3
+ ANTHROPIC_API_KEY=... traceforge serve --host 0.0.0.0 --port 8787
4
+ traceforge keys create alice --limit 5000000
5
+
6
+ Put it behind TLS (a reverse proxy) before exposing it to the internet.
7
+ """
8
+
9
+ # No `from __future__ import annotations`: FastAPI must resolve the WebSocket annotation at runtime.
10
+
11
+ import asyncio
12
+ import json
13
+ import os
14
+ import time
15
+ from collections import defaultdict, deque
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ from traceforge.agent import Agent, AgentError, AgentEvent
20
+ from traceforge.config import Settings
21
+ from traceforge.prices import model_cost, usage_cost
22
+ from traceforge.remote import PROTOCOL_VERSION, SUPPORTED_PROTOCOLS
23
+ from traceforge.remote.orgs import OrgError, OrgStore
24
+ from traceforge.remote.store import KeyStore
25
+
26
+ MAX_FRAME = 16 * 1024 * 1024
27
+ TOOL_TIMEOUT = float(os.environ.get("TRACEFORGE_TOOL_TIMEOUT", "1800"))
28
+ ALLOWED_MODES = {"agent", "plan", "ask", "review"}
29
+
30
+
31
+ class RateLimiter:
32
+ """Sliding-window limiter, in memory (per server process): ``hit`` is False when over."""
33
+
34
+ def __init__(self, limit: int, window: float = 60.0):
35
+ self.limit, self.window = limit, window
36
+ self.hits: dict[str, deque] = defaultdict(deque)
37
+
38
+ def hit(self, name: str) -> bool:
39
+ now = time.monotonic()
40
+ queue = self.hits[name]
41
+ while queue and now - queue[0] > self.window:
42
+ queue.popleft()
43
+ if len(queue) >= self.limit:
44
+ return False
45
+ queue.append(now)
46
+ if len(self.hits) > 10_000: # forget idle names
47
+ for key in [k for k, v in self.hits.items() if not v]:
48
+ del self.hits[key]
49
+ return True
50
+
51
+
52
+ class _Outbox:
53
+ """Sends frames in the order they were produced, from sync and async code alike."""
54
+
55
+ def __init__(self, websocket: Any):
56
+ self.websocket = websocket
57
+ self.queue: asyncio.Queue = asyncio.Queue()
58
+ self.task = asyncio.create_task(self._writer())
59
+
60
+ async def _writer(self) -> None:
61
+ while True:
62
+ frame = await self.queue.get()
63
+ try:
64
+ await self.websocket.send_json(frame)
65
+ except Exception: # noqa: BLE001 - the client went away; the turn ends anyway
66
+ pass
67
+ finally:
68
+ self.queue.task_done()
69
+
70
+ def post(self, frame: dict[str, Any]) -> None:
71
+ self.queue.put_nowait(frame)
72
+
73
+ async def send_json(self, frame: dict[str, Any]) -> None:
74
+ self.post(frame)
75
+
76
+ async def flush(self) -> None:
77
+ await self.queue.join()
78
+
79
+ def close(self) -> None:
80
+ self.task.cancel()
81
+
82
+
83
+ class RemoteExecutor:
84
+ """Executes tools by asking the connected client to run them."""
85
+
86
+ def __init__(
87
+ self,
88
+ websocket: Any,
89
+ definitions: list[dict[str, Any]],
90
+ parallel_safe: set[str] | None = None,
91
+ ):
92
+ self.websocket = websocket
93
+ self._definitions = definitions
94
+ self._parallel = set(parallel_safe or ())
95
+ self._pending: dict[str, asyncio.Future] = {}
96
+
97
+ def definitions(self) -> list[dict[str, Any]]:
98
+ return self._definitions
99
+
100
+ def parallel_safe(self, name: str) -> bool:
101
+ # Only tools the client declared read-only run concurrently; anything that may ask
102
+ # for approval goes one at a time so prompts on the client stay sequential.
103
+ return name in self._parallel
104
+
105
+ async def execute(
106
+ self, name: str, arguments: dict[str, Any], tool_use_id: str
107
+ ) -> tuple[str, bool]:
108
+ future: asyncio.Future = asyncio.get_running_loop().create_future()
109
+ self._pending[tool_use_id] = future
110
+ await self.websocket.send_json(
111
+ {"type": "tool_request", "id": tool_use_id, "name": name, "input": arguments}
112
+ )
113
+ try:
114
+ return await asyncio.wait_for(future, TOOL_TIMEOUT)
115
+ except TimeoutError:
116
+ return f"the client did not return a result within {TOOL_TIMEOUT:.0f}s", True
117
+ finally:
118
+ self._pending.pop(tool_use_id, None)
119
+
120
+ def resolve(self, message: dict[str, Any]) -> None:
121
+ future = self._pending.get(str(message.get("id")))
122
+ if future and not future.done():
123
+ content = message.get("content", "")
124
+ if not (isinstance(content, list) and all(isinstance(b, dict) for b in content)):
125
+ content = str(content)[:MAX_FRAME] # text, or content blocks with images
126
+ future.set_result((content, bool(message.get("is_error"))))
127
+
128
+
129
+ def _sanitize_definitions(raw: Any) -> list[dict[str, Any]]:
130
+ if not isinstance(raw, list):
131
+ return []
132
+ clean = []
133
+ for tool in raw[:100]:
134
+ if (
135
+ isinstance(tool, dict)
136
+ and isinstance(tool.get("name"), str)
137
+ and isinstance(tool.get("input_schema"), dict)
138
+ ):
139
+ clean.append(
140
+ {
141
+ "name": tool["name"][:64],
142
+ "description": str(tool.get("description", ""))[:4000],
143
+ "input_schema": tool["input_schema"],
144
+ "eager_input_streaming": True,
145
+ }
146
+ )
147
+ return sorted(clean, key=lambda t: t["name"])
148
+
149
+
150
+ def allowed_models(default: str) -> list[str]:
151
+ """Models clients may pick (``TRACEFORGE_SERVER_MODELS``, comma separated)."""
152
+ raw = os.environ.get("TRACEFORGE_SERVER_MODELS", "")
153
+ models = [item.strip() for item in raw.split(",") if item.strip()]
154
+ return list(dict.fromkeys([default, *models]))
155
+
156
+
157
+ def _next_month() -> str:
158
+ import time
159
+
160
+ year, month = time.gmtime()[:2]
161
+ return f"{year + (month == 12)}-{month % 12 + 1:02d}-01"
162
+
163
+
164
+ def create_app(db: Path | None = None, client: Any = None, oidc: Any = None):
165
+ try:
166
+ from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
167
+ except ImportError as exc: # pragma: no cover - optional dependency
168
+ raise SystemExit(
169
+ "the server needs the 'server' extra: pip install 'traceforge-pcb[server]'"
170
+ ) from exc
171
+
172
+ keys = KeyStore(db)
173
+ orgs = OrgStore(keys.path)
174
+ inflight: dict[str, list[float]] = defaultdict(lambda: [0, 0.0]) # id -> [tokens, usd]
175
+ auth_failures = RateLimiter(int(os.environ.get("TRACEFORGE_RATE_AUTH_FAILURES", "10")))
176
+ turn_starts = RateLimiter(int(os.environ.get("TRACEFORGE_RATE_TURNS", "30")))
177
+ app = FastAPI(title="traceforge server", version="1")
178
+ base_settings = Settings.load(None, {"model": os.environ.get("TRACEFORGE_SERVER_MODEL")})
179
+
180
+ models = allowed_models(base_settings.model)
181
+
182
+ def _client_ip(request: Any) -> str:
183
+ return request.client.host if request.client else "?"
184
+
185
+ def _authorized(request: Request) -> dict:
186
+ ip = _client_ip(request)
187
+ auth = request.headers.get("authorization", "")
188
+ key = keys.authenticate(auth.removeprefix("Bearer ").strip())
189
+ if key is None:
190
+ if not auth_failures.hit(ip):
191
+ raise HTTPException(status_code=429, detail="too many failed attempts; slow down")
192
+ raise HTTPException(status_code=401, detail="invalid or revoked API key")
193
+ key["member"] = orgs.member_of_key(key["id"])
194
+ return key
195
+
196
+ def _admin(request: Request) -> dict:
197
+ key = _authorized(request)
198
+ member = key["member"]
199
+ if member is None or member["role"] != "admin":
200
+ raise HTTPException(status_code=403, detail="organisation admins only")
201
+ return member
202
+
203
+ def _summary(member: dict | None) -> dict[str, Any]:
204
+ if member is None:
205
+ return {}
206
+ org = orgs.need_org(member["org_id"])
207
+ mine = orgs.usage(member_id=member["id"])
208
+ pool = orgs.usage(org_id=org["id"])
209
+ return {
210
+ "org": {"id": org["id"], "name": org["name"]},
211
+ "role": member["role"],
212
+ "email": member["email"],
213
+ "spend_cap_usd": member["cap_usd"],
214
+ "token_cap": member["cap_tokens"],
215
+ "spent_usd": mine["spent_usd"],
216
+ "tokens_used": mine["tokens"],
217
+ "org_usage": {
218
+ "tokens": pool["tokens"],
219
+ "token_quota": org["quota_tokens"],
220
+ "spent_usd": pool["spent_usd"],
221
+ "usd_quota": org["quota_usd"],
222
+ },
223
+ }
224
+
225
+ @app.get("/health")
226
+ async def health() -> dict[str, Any]:
227
+ return {"ok": True, "protocol": PROTOCOL_VERSION, "model": base_settings.model}
228
+
229
+ @app.get("/v1/models")
230
+ async def list_models(request: Request) -> dict[str, Any]:
231
+ _authorized(request)
232
+ return {"default": base_settings.model, "models": models}
233
+
234
+ @app.get("/v1/me")
235
+ async def me(request: Request) -> dict[str, Any]:
236
+ key = _authorized(request)
237
+ return {
238
+ "id": key["id"],
239
+ "name": key["name"],
240
+ "used": keys.used(key["id"]),
241
+ "limit": key["limit"],
242
+ "resets": _next_month(),
243
+ "model": base_settings.model,
244
+ **_summary(key["member"]),
245
+ }
246
+
247
+ @app.get("/v1/usage")
248
+ async def usage_endpoint(request: Request) -> dict[str, Any]:
249
+ key = _authorized(request)
250
+ member = key["member"]
251
+ if member is None:
252
+ return {"tokens": keys.used(key["id"]), "resets": _next_month()}
253
+ by_model = orgs.usage_by_model(member_id=member["id"])
254
+ return {
255
+ **orgs.usage(member_id=member["id"]),
256
+ "by_model": {
257
+ m: {**c, "cost_usd": usage_cost({"by_model": {m: c}}).usd}
258
+ for m, c in by_model.items()
259
+ },
260
+ "resets": _next_month(),
261
+ **_summary(member),
262
+ }
263
+
264
+ @app.get("/v1/org")
265
+ async def org_endpoint(request: Request) -> dict[str, Any]:
266
+ member = _admin(request)
267
+ rows = orgs.members(member["org_id"])
268
+ return {
269
+ **_summary(member),
270
+ "members": [
271
+ {
272
+ k: r[k]
273
+ for k in (
274
+ "email",
275
+ "name",
276
+ "role",
277
+ "cap_usd",
278
+ "cap_tokens",
279
+ "tokens",
280
+ "spent_usd",
281
+ )
282
+ }
283
+ for r in rows
284
+ ],
285
+ }
286
+
287
+ @app.get("/v1/audit")
288
+ async def audit_endpoint(request: Request, limit: int = 50) -> dict[str, Any]:
289
+ key = _authorized(request)
290
+ member = key["member"]
291
+ if member is None:
292
+ raise HTTPException(status_code=403, detail="API key is not part of an organisation")
293
+ mine_only = None if member["role"] == "admin" else member["id"]
294
+ return {"events": orgs.audit(member["org_id"], min(max(limit, 1), 500), mine_only)}
295
+
296
+ @app.post("/v1/org/invites")
297
+ async def invite_endpoint(request: Request) -> dict[str, Any]:
298
+ member = _admin(request)
299
+ body = await request.json()
300
+ try:
301
+ token = orgs.invite(
302
+ member["org_id"], str(body.get("email", "")), body.get("role", "member")
303
+ )
304
+ except OrgError as exc:
305
+ raise HTTPException(status_code=400, detail=exc.message) from exc
306
+ orgs.record(
307
+ org_id=member["org_id"],
308
+ member_id=member["id"],
309
+ key_id=None,
310
+ event="invite",
311
+ detail=f"invited {body.get('email')}",
312
+ )
313
+ return {"invite": token}
314
+
315
+ @app.delete("/v1/org/members/{email}")
316
+ async def remove_endpoint(email: str, request: Request) -> dict[str, Any]:
317
+ member = _admin(request)
318
+ try:
319
+ orgs.remove_member(member["org_id"], email)
320
+ except OrgError as exc:
321
+ raise HTTPException(status_code=400, detail=exc.message) from exc
322
+ orgs.record(
323
+ org_id=member["org_id"],
324
+ member_id=member["id"],
325
+ key_id=None,
326
+ event="remove_member",
327
+ detail=f"removed {email}",
328
+ )
329
+ return {"removed": email}
330
+
331
+ @app.post("/v1/invites/accept")
332
+ async def accept_endpoint(request: Request) -> dict[str, Any]:
333
+ ip = _client_ip(request)
334
+ if not auth_failures.hit("invite:" + ip):
335
+ raise HTTPException(status_code=429, detail="too many attempts; slow down")
336
+ body = await request.json()
337
+ try:
338
+ api_key, member = orgs.accept_invite(
339
+ str(body.get("invite", "")), str(body.get("name", ""))
340
+ )
341
+ except OrgError as exc:
342
+ raise HTTPException(status_code=400, detail=exc.message) from exc
343
+ orgs.record(org_id=member["org_id"], member_id=member["id"], key_id=None, event="join")
344
+ return {"key": api_key, "email": member["email"], "role": member["role"]}
345
+
346
+ @app.get("/v1/auth/oidc/start")
347
+ async def oidc_start() -> dict[str, Any]:
348
+ if oidc is None:
349
+ raise HTTPException(status_code=404, detail="SSO is not configured on this server")
350
+ from traceforge.remote.oidc import OIDCError
351
+
352
+ try:
353
+ return oidc.start()
354
+ except OIDCError as exc:
355
+ raise HTTPException(status_code=502, detail=exc.message) from exc
356
+
357
+ @app.get("/v1/auth/oidc/callback")
358
+ async def oidc_callback(request: Request, code: str = "", state: str = "") -> dict[str, Any]:
359
+ if oidc is None:
360
+ raise HTTPException(status_code=404, detail="SSO is not configured on this server")
361
+ from traceforge.remote.oidc import OIDCError
362
+
363
+ if not auth_failures.hit("sso:" + _client_ip(request)):
364
+ raise HTTPException(status_code=429, detail="too many attempts; slow down")
365
+ try:
366
+ claims = await asyncio.to_thread(oidc.finish, code, state)
367
+ org = orgs.need_org(oidc.config.org)
368
+ member = orgs.member_by_subject(org["id"], claims["sub"]) or orgs.member(
369
+ org["id"], claims["email"]
370
+ )
371
+ if member is None:
372
+ if not oidc.config.auto_provision:
373
+ raise OIDCError(
374
+ "not_invited", "no seat for this user; ask an admin for an invite"
375
+ )
376
+ member = orgs.add_member(
377
+ org["id"],
378
+ claims["email"],
379
+ claims["role"],
380
+ str(claims.get("name", "")),
381
+ claims["sub"],
382
+ )
383
+ elif member["role"] != claims["role"]:
384
+ # The IdP is the source of truth for role (group mapping) on every login.
385
+ orgs.set_role(org["id"], member["email"], claims["role"])
386
+ except OIDCError as exc:
387
+ orgs.record(
388
+ org_id=None,
389
+ member_id=None,
390
+ key_id=None,
391
+ event="sso_denied",
392
+ status=exc.code,
393
+ detail=exc.message,
394
+ )
395
+ raise HTTPException(
396
+ status_code=401, detail={"code": exc.code, "message": exc.message}
397
+ ) from exc
398
+ except OrgError as exc:
399
+ raise HTTPException(status_code=400, detail=exc.message) from exc
400
+ api_key, _ = orgs.issue_key(member, "sso")
401
+ orgs.record(org_id=org["id"], member_id=member["id"], key_id=None, event="sso_login")
402
+ return {"key": api_key, "email": member["email"], "role": claims["role"]}
403
+
404
+ @app.websocket("/v1/agent")
405
+ async def agent_socket(websocket: WebSocket) -> None:
406
+ auth = websocket.headers.get("authorization", "")
407
+ key = keys.authenticate(auth.removeprefix("Bearer ").strip())
408
+ await websocket.accept()
409
+ client_ip = websocket.client.host if websocket.client else "?"
410
+ if key is None and not auth_failures.hit(client_ip):
411
+ await websocket.send_json(
412
+ {"type": "error", "code": "rate_limited", "message": "too many failed attempts"}
413
+ )
414
+ await websocket.close(code=4429, reason="rate limited")
415
+ return
416
+ if key is None:
417
+ await websocket.send_json(
418
+ {"type": "error", "code": "unauthorized", "message": "invalid or revoked API key"}
419
+ )
420
+ await websocket.close(code=4401, reason="invalid or revoked API key")
421
+ return
422
+ if keys.over_limit(key):
423
+ await websocket.send_json(
424
+ {
425
+ "type": "error",
426
+ "code": "quota",
427
+ "message": f"monthly token limit reached; it resets on {_next_month()}",
428
+ "resets": _next_month(),
429
+ }
430
+ )
431
+ await websocket.close(code=4429, reason="monthly token limit reached")
432
+ return
433
+ member = orgs.member_of_key(key["id"])
434
+ if not turn_starts.hit(key["id"]):
435
+ await websocket.send_json(
436
+ {"type": "error", "code": "rate_limited", "message": "too many turns per minute"}
437
+ )
438
+ await websocket.close(code=4429, reason="rate limited")
439
+ return
440
+ try:
441
+ start = await websocket.receive_json()
442
+ except (WebSocketDisconnect, json.JSONDecodeError, ValueError):
443
+ return
444
+ protocol = start.get("protocol")
445
+ if start.get("type") != "turn" or protocol not in SUPPORTED_PROTOCOLS:
446
+ await websocket.send_json(
447
+ {
448
+ "type": "error",
449
+ "code": "protocol",
450
+ "message": f"expected a turn with protocol {SUPPORTED_PROTOCOLS}",
451
+ }
452
+ )
453
+ await websocket.close()
454
+ return
455
+ mode = start.get("mode", "agent")
456
+ if mode not in ALLOWED_MODES:
457
+ await websocket.send_json(
458
+ {"type": "error", "code": "bad_request", "message": f"unknown mode {mode}"}
459
+ )
460
+ await websocket.close()
461
+ return
462
+ effort = (
463
+ start.get("effort")
464
+ if start.get("effort") in {"low", "medium", "high", "xhigh", "max"}
465
+ else base_settings.effort
466
+ )
467
+ model = str(start.get("model") or base_settings.model)
468
+ if model not in models:
469
+ await websocket.send_json(
470
+ {
471
+ "type": "error",
472
+ "code": "bad_request",
473
+ "message": f"model {model!r} is not offered here; choose from {models}",
474
+ }
475
+ )
476
+ await websocket.close()
477
+ return
478
+ settings = Settings(**{**base_settings.__dict__, "effort": effort, "model": model})
479
+ org_row = orgs.need_org(member["org_id"]) if member else None
480
+ base_mine = orgs.usage(member_id=member["id"]) if member else {}
481
+ base_pool = orgs.usage(org_id=org_row["id"]) if org_row else {}
482
+ if member:
483
+ from traceforge.providers import provider_for
484
+
485
+ priced = model_cost(model, {}, provider_for(model, settings.provider)) is not None
486
+ verdict = orgs.check(member, priced, {k: tuple(v) for k, v in inflight.items()})
487
+ if not verdict.ok:
488
+ orgs.record(
489
+ org_id=member["org_id"],
490
+ member_id=member["id"],
491
+ key_id=key["id"],
492
+ event="blocked",
493
+ mode=mode,
494
+ model=model,
495
+ status=verdict.code,
496
+ detail=verdict.message,
497
+ )
498
+ await websocket.send_json(
499
+ {
500
+ "type": "error",
501
+ "code": verdict.code,
502
+ "message": verdict.message,
503
+ "resets": _next_month(),
504
+ }
505
+ )
506
+ await websocket.close(code=4429, reason=verdict.code)
507
+ return
508
+ tool_names: list[str] = []
509
+ turn_state = {"tokens": 0, "usd": 0.0, "stop": None}
510
+
511
+ def account(usage: dict[str, Any]) -> None:
512
+ """Count this turn's running spend into the shared in-flight totals."""
513
+ if not member:
514
+ return
515
+ tokens = sum(
516
+ int(usage.get(k, 0) or 0)
517
+ for k in (
518
+ "input_tokens",
519
+ "output_tokens",
520
+ "cache_read_input_tokens",
521
+ "cache_creation_input_tokens",
522
+ )
523
+ )
524
+ usd = usage_cost(usage, model, settings.provider).usd or 0.0
525
+ for ident in (member["id"], member["org_id"]):
526
+ inflight[ident][0] += tokens - turn_state["tokens"]
527
+ inflight[ident][1] += usd - turn_state["usd"]
528
+ turn_state["tokens"], turn_state["usd"] = tokens, usd
529
+ verdict = orgs.verdict(
530
+ member,
531
+ org_row,
532
+ base_mine,
533
+ base_pool,
534
+ tuple(inflight[member["id"]]),
535
+ tuple(inflight[member["org_id"]]),
536
+ )
537
+ if not verdict.ok and turn_state["stop"] is None:
538
+ # Hard stop: the answer already in flight is kept, but the turn goes no
539
+ # further (the next tool call, hence the next model call, is cancelled).
540
+ turn_state["stop"] = verdict
541
+
542
+ parallel = start.get("parallel_safe")
543
+ outbox = _Outbox(websocket)
544
+ executor = RemoteExecutor(
545
+ outbox,
546
+ _sanitize_definitions(start.get("tools")),
547
+ {str(name) for name in parallel} if isinstance(parallel, list) else None,
548
+ )
549
+ agent = Agent(
550
+ settings,
551
+ executor,
552
+ mode,
553
+ client=client,
554
+ extra_instructions=str(start.get("instructions", ""))[:20_000],
555
+ )
556
+ messages = start.get("messages") if isinstance(start.get("messages"), list) else []
557
+ content = start.get("content") if isinstance(start.get("content"), list) else []
558
+
559
+ run_task_ref: list[Any] = [None]
560
+
561
+ async def sink(event: AgentEvent) -> None:
562
+ if event.kind == "tool_call" and isinstance(event.data, dict):
563
+ tool_names.append(str(event.data.get("name", ""))[:64])
564
+ if turn_state["stop"] is not None:
565
+ run_task_ref[0].cancel()
566
+ if event.kind == "usage" and isinstance(event.data, dict):
567
+ account(event.data)
568
+ if event.kind in {"text", "thinking", "status", "usage", "error", "notice"}:
569
+ outbox.post({"type": "event", "kind": event.kind, "data": event.data})
570
+
571
+ sent = {"count": len(messages)}
572
+
573
+ def checkpoint(history: list[dict[str, Any]]) -> None:
574
+ # Protocol 2: send the history added since the last checkpoint, so a client that
575
+ # loses the connection can resume from here instead of starting the turn over.
576
+ if protocol < 2:
577
+ return
578
+ start_index = min(sent["count"], len(history))
579
+ # The user message may grow in place (content appended), so resend from its index.
580
+ if start_index and history[start_index - 1]["role"] == "user":
581
+ start_index -= 1
582
+ frame = {"type": "checkpoint", "start": start_index, "messages": history[start_index:]}
583
+ sent["count"] = len(history)
584
+ outbox.post(frame)
585
+
586
+ async def reader() -> None:
587
+ while True:
588
+ message = await websocket.receive_json()
589
+ if message.get("type") == "tool_result":
590
+ executor.resolve(message)
591
+ elif message.get("type") == "cancel":
592
+ raise asyncio.CancelledError
593
+
594
+ recorded = False
595
+ read_task = asyncio.create_task(reader())
596
+ run_task = asyncio.create_task(agent.run(messages, content, sink, checkpoint))
597
+ run_task_ref[0] = run_task
598
+ try:
599
+ done, _ = await asyncio.wait({read_task, run_task}, return_when=asyncio.FIRST_COMPLETED)
600
+ if run_task in done:
601
+ result = run_task.result()
602
+ keys.record(key["id"], result.usage.input_tokens, result.usage.output_tokens)
603
+ recorded = True
604
+ await outbox.flush()
605
+ await websocket.send_json(
606
+ {
607
+ "type": "done",
608
+ "messages": messages,
609
+ "usage": result.usage.to_dict(),
610
+ "text": result.text,
611
+ "stop_reason": result.stop_reason,
612
+ "refusal": result.refusal,
613
+ }
614
+ )
615
+ else:
616
+ run_task.cancel()
617
+ except AgentError as exc:
618
+ await outbox.flush()
619
+ await websocket.send_json({"type": "error", "code": "agent", "message": str(exc)})
620
+ except (WebSocketDisconnect, asyncio.CancelledError):
621
+ run_task.cancel()
622
+ stopped = turn_state["stop"]
623
+ if stopped is not None:
624
+ await outbox.flush()
625
+ try:
626
+ await websocket.send_json(
627
+ {
628
+ "type": "error",
629
+ "code": stopped.code,
630
+ "message": stopped.message,
631
+ "resets": _next_month(),
632
+ }
633
+ )
634
+ except Exception: # noqa: BLE001
635
+ pass
636
+ except Exception as exc: # noqa: BLE001 - report, so a protocol-2 client can resume
637
+ await outbox.flush()
638
+ try:
639
+ await websocket.send_json(
640
+ {
641
+ "type": "error",
642
+ "code": "internal",
643
+ "message": f"{type(exc).__name__}: {exc}",
644
+ "retryable": True,
645
+ }
646
+ )
647
+ except Exception: # noqa: BLE001
648
+ pass
649
+ finally:
650
+ read_task.cancel()
651
+ outbox.close()
652
+ if not recorded and agent.usage.requests:
653
+ keys.record(key["id"], agent.usage.input_tokens, agent.usage.output_tokens)
654
+ if member:
655
+ for ident in (member["id"], member["org_id"]):
656
+ inflight[ident][0] -= turn_state["tokens"]
657
+ inflight[ident][1] -= turn_state["usd"]
658
+ used = agent.usage.to_dict()
659
+ if used["requests"] or turn_state["stop"]:
660
+ cost = usage_cost(used, model, settings.provider)
661
+ stop = turn_state["stop"]
662
+ orgs.record(
663
+ org_id=member["org_id"] if member else None,
664
+ member_id=member["id"] if member else None,
665
+ key_id=key["id"],
666
+ mode=mode,
667
+ model=model,
668
+ tools=tool_names,
669
+ usage=used,
670
+ cost_usd=cost.usd if not cost.unknown_models else None,
671
+ status=f"stopped:{stop.code}"
672
+ if stop and not recorded
673
+ else ("ok" if recorded else "incomplete"),
674
+ )
675
+ try:
676
+ await websocket.close()
677
+ except Exception:
678
+ pass
679
+
680
+ return app
681
+
682
+
683
+ def run_server(host: str = "127.0.0.1", port: int = 8787, db: Path | None = None) -> None:
684
+ import uvicorn
685
+
686
+ from traceforge.remote.oidc import load_oidc_from_env
687
+
688
+ uvicorn.run(
689
+ create_app(db, oidc=load_oidc_from_env()), host=host, port=port, ws_max_size=MAX_FRAME
690
+ )