wspx 0.1.0.dev0__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 (99) hide show
  1. wspx/__init__.py +24 -0
  2. wspx/_version.py +1 -0
  3. wspx/addressing.py +415 -0
  4. wspx/auth.py +77 -0
  5. wspx/cli/__init__.py +1 -0
  6. wspx/cli/client.py +124 -0
  7. wspx/cli/config.py +89 -0
  8. wspx/cli/connect.py +88 -0
  9. wspx/cli/main.py +848 -0
  10. wspx/cloud/__init__.py +20 -0
  11. wspx/cloud/app.py +191 -0
  12. wspx/cloud/backend.py +141 -0
  13. wspx/cloud/compose.py +85 -0
  14. wspx/cloud/deploy.py +102 -0
  15. wspx/config.py +189 -0
  16. wspx/control/__init__.py +5 -0
  17. wspx/control/app.py +488 -0
  18. wspx/control/backend.py +244 -0
  19. wspx/control/gateway_client.py +79 -0
  20. wspx/control/mcp_server.py +71 -0
  21. wspx/control/sessions.py +424 -0
  22. wspx/control/tracedb.py +183 -0
  23. wspx/control/ui/assets/index-BJFweZAn.css +1 -0
  24. wspx/control/ui/assets/index-DhUVhWIK.js +10 -0
  25. wspx/control/ui/index.html +13 -0
  26. wspx/control/views.py +180 -0
  27. wspx/diagnostics.py +146 -0
  28. wspx/driver/__init__.py +7 -0
  29. wspx/driver/loop.py +255 -0
  30. wspx/driver/messages.py +62 -0
  31. wspx/driver/providers/__init__.py +84 -0
  32. wspx/driver/providers/anthropic.py +149 -0
  33. wspx/driver/providers/compat.py +115 -0
  34. wspx/driver/providers/google.py +138 -0
  35. wspx/driver/providers/openai.py +125 -0
  36. wspx/driver/run.py +134 -0
  37. wspx/errors.py +69 -0
  38. wspx/gateway/__init__.py +8 -0
  39. wspx/gateway/app.py +626 -0
  40. wspx/gateway/ledger.py +536 -0
  41. wspx/gateway/prices.py +75 -0
  42. wspx/gateway/usage.py +284 -0
  43. wspx/handles.py +117 -0
  44. wspx/integrations/AGENTS.snippet.md +8 -0
  45. wspx/integrations/SKILL.md +52 -0
  46. wspx/integrations/__init__.py +17 -0
  47. wspx/integrations/claude-plugin/.claude-plugin/plugin.json +30 -0
  48. wspx/integrations/claude-plugin/skills/wspx/SKILL.md +52 -0
  49. wspx/integrations/codex-hooks.toml +9 -0
  50. wspx/lab/__init__.py +5 -0
  51. wspx/lab/analysis.py +485 -0
  52. wspx/lab/check.py +489 -0
  53. wspx/lab/evaluate.py +108 -0
  54. wspx/lab/export.py +275 -0
  55. wspx/lab/grep.py +754 -0
  56. wspx/lab/index.py +239 -0
  57. wspx/lab/ir/__init__.py +1 -0
  58. wspx/lab/ir/capture.py +299 -0
  59. wspx/lab/ir/graph.py +148 -0
  60. wspx/lab/ir/model_ir.py +522 -0
  61. wspx/lab/ir/semantics.py +1255 -0
  62. wspx/lab/ir/tape.py +853 -0
  63. wspx/lab/loader.py +204 -0
  64. wspx/lab/merge.py +200 -0
  65. wspx/lab/ops/__init__.py +76 -0
  66. wspx/lab/ops/builtin.py +379 -0
  67. wspx/lab/patch.py +320 -0
  68. wspx/lab/probe.py +206 -0
  69. wspx/lab/results.py +114 -0
  70. wspx/lab/sdk.py +120 -0
  71. wspx/lab/server.py +236 -0
  72. wspx/lab/session.py +1574 -0
  73. wspx/lab/tensors.py +119 -0
  74. wspx/lab/text.py +69 -0
  75. wspx/lab/tree.py +302 -0
  76. wspx/loops.py +127 -0
  77. wspx/project.py +143 -0
  78. wspx/py.typed +0 -0
  79. wspx/safety/__init__.py +15 -0
  80. wspx/safety/kill.py +47 -0
  81. wspx/safety/sweeper.py +68 -0
  82. wspx/store/__init__.py +64 -0
  83. wspx/store/objects.py +130 -0
  84. wspx/store/overlay.py +209 -0
  85. wspx/store/refs.py +150 -0
  86. wspx/testing/__init__.py +21 -0
  87. wspx/testing/api.py +155 -0
  88. wspx/testing/builtin.py +139 -0
  89. wspx/testing/runner.py +257 -0
  90. wspx/tools/__init__.py +17 -0
  91. wspx/tools/dispatch.py +129 -0
  92. wspx/tools/schemas.py +313 -0
  93. wspx/vcs/__init__.py +17 -0
  94. wspx/vcs/repo.py +431 -0
  95. wspx-0.1.0.dev0.dist-info/METADATA +278 -0
  96. wspx-0.1.0.dev0.dist-info/RECORD +99 -0
  97. wspx-0.1.0.dev0.dist-info/WHEEL +4 -0
  98. wspx-0.1.0.dev0.dist-info/entry_points.txt +10 -0
  99. wspx-0.1.0.dev0.dist-info/licenses/LICENSE +201 -0
wspx/config.py ADDED
@@ -0,0 +1,189 @@
1
+ """``wspx.toml``: project configuration (design §4.4).
2
+
3
+ Spend limits are deliberately *not* configurable here. Agents can edit files,
4
+ so limits live server-side in the gateway's ledger and change only through the
5
+ user's CLI or UI.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ import tomllib
12
+ from pathlib import Path
13
+ from typing import Annotated, Any, Literal
14
+
15
+ from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, ValidationError, model_validator
16
+
17
+ from wspx.errors import ConfigError
18
+
19
+ CONFIG_FILENAME = "wspx.toml"
20
+
21
+ _DURATION_RE = re.compile(r"(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)")
22
+ _DURATION_UNITS = {"ms": 0.001, "s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
23
+
24
+
25
+ def parse_duration(value: str | float | int) -> float:
26
+ """Parse ``"15m"``, ``"1h30m"``, ``"90s"`` or a number of seconds into seconds."""
27
+ if isinstance(value, bool):
28
+ raise ValueError("duration must be a string or a number of seconds")
29
+ if isinstance(value, int | float):
30
+ if value < 0:
31
+ raise ValueError("duration must not be negative")
32
+ return float(value)
33
+ text = value.strip().lower().replace(" ", "")
34
+ if not text:
35
+ raise ValueError("empty duration")
36
+ pos = 0
37
+ total = 0.0
38
+ for match in _DURATION_RE.finditer(text):
39
+ if match.start() != pos:
40
+ break
41
+ total += float(match.group(1)) * _DURATION_UNITS[match.group(2)]
42
+ pos = match.end()
43
+ if pos != len(text):
44
+ raise ValueError(f"invalid duration {value!r}; use e.g. '90s', '15m' or '1h30m'")
45
+ return total
46
+
47
+
48
+ def format_duration(seconds: float) -> str:
49
+ """Render seconds compactly: ``900`` → ``"15m"``, ``5400`` → ``"1h30m"``."""
50
+ if seconds < 1:
51
+ return f"{round(seconds * 1000)}ms"
52
+ remaining = round(seconds)
53
+ parts = []
54
+ for unit, size in (("d", 86400), ("h", 3600), ("m", 60), ("s", 1)):
55
+ count, remaining = divmod(remaining, size)
56
+ if count:
57
+ parts.append(f"{count}{unit}")
58
+ return "".join(parts) or "0s"
59
+
60
+
61
+ Duration = Annotated[float, BeforeValidator(parse_duration)]
62
+
63
+
64
+ class _Section(BaseModel):
65
+ model_config = ConfigDict(extra="forbid", frozen=True)
66
+
67
+
68
+ class ProjectSection(_Section):
69
+ name: str | None = None
70
+ """Shown next to its sessions; defaults to the project directory's name."""
71
+ exclude: list[str] = Field(default_factory=list)
72
+ """Paths kept out of the upload to the lab (``.dockerignore`` patterns), on top of
73
+ the defaults: version control, virtualenvs, caches, stores and weight files."""
74
+
75
+
76
+ class ModelSection(_Section):
77
+ id: str | None = None
78
+ revision: str | None = None
79
+ dtype: Literal["bfloat16", "float16", "float32", "auto"] = "bfloat16"
80
+ trust_remote_code: bool = False
81
+ code: str | None = None
82
+ """Custom architecture, e.g. ``"git+https://…#pkg.module:Class"`` or ``"pkg.module:Class"``."""
83
+
84
+
85
+ class DriverSection(_Section):
86
+ model: str | None = None
87
+
88
+
89
+ class LabSection(_Section):
90
+ gpu: str | None = None
91
+ """``None`` runs on CPU; otherwise a Modal GPU spec such as ``"H100"`` or ``"H100:8"``."""
92
+ grace: Duration = 15 * 60
93
+ keep_warm: Literal["auto", "always"] = "auto"
94
+
95
+
96
+ class LoopGuardSection(_Section):
97
+ """Repetition detection. Never looks at duration, turn count or spend (§5.14.4)."""
98
+
99
+ enabled: bool = True
100
+ repeat_threshold: int = Field(default=3, ge=2)
101
+ window: int = Field(default=10, ge=2)
102
+
103
+
104
+ class CheckSection(_Section):
105
+ max_rel_norm: float = Field(default=0.05, gt=0)
106
+ max_canary_kl: float = Field(default=0.10, gt=0)
107
+ subulp_error_at: float = Field(default=0.5, gt=0, le=1)
108
+ warn_dense_fraction: float = Field(default=0.05, gt=0, le=1)
109
+ max_ppl_increase: float = Field(default=0.10, gt=0)
110
+
111
+
112
+ class TestsSection(_Section):
113
+ paths: list[str] = Field(default_factory=lambda: ["wtests/"])
114
+
115
+
116
+ class PolicySection(_Section):
117
+ protected_branches: list[str] = Field(default_factory=lambda: ["main"])
118
+
119
+
120
+ class WspxConfig(_Section):
121
+ project: ProjectSection = Field(default_factory=ProjectSection)
122
+ model: ModelSection = Field(default_factory=ModelSection)
123
+ driver: DriverSection = Field(default_factory=DriverSection)
124
+ lab: LabSection = Field(default_factory=LabSection)
125
+ loop_guard: LoopGuardSection = Field(default_factory=LoopGuardSection)
126
+ check: CheckSection = Field(default_factory=CheckSection)
127
+ tests: TestsSection = Field(default_factory=TestsSection)
128
+ policy: PolicySection = Field(default_factory=PolicySection)
129
+
130
+ @model_validator(mode="before")
131
+ @classmethod
132
+ def _normalise(cls, data: Any) -> Any:
133
+ if not isinstance(data, dict):
134
+ return data
135
+ if "limits" in data:
136
+ raise ValueError(
137
+ "wspx.toml has no [limits] section: limits are stored server-side so agents "
138
+ "cannot change them. Use `wspx limits set` or the UI."
139
+ )
140
+ guard = data.get("loop_guard")
141
+ if isinstance(guard, str):
142
+ if guard.lower() != "off":
143
+ raise ValueError("loop_guard must be a table or the string 'off'")
144
+ data = {**data, "loop_guard": {"enabled": False}}
145
+ return data
146
+
147
+ @classmethod
148
+ def from_toml(cls, text: str, *, source: str = CONFIG_FILENAME) -> WspxConfig:
149
+ try:
150
+ raw = tomllib.loads(text)
151
+ except tomllib.TOMLDecodeError as exc:
152
+ raise ConfigError(f"{source}: {exc}") from exc
153
+ try:
154
+ return cls.model_validate(raw)
155
+ except ValidationError as exc:
156
+ raise ConfigError(_format_validation_error(source, exc)) from None
157
+
158
+ @classmethod
159
+ def load(cls, path: str | Path) -> WspxConfig:
160
+ path = Path(path)
161
+ try:
162
+ text = path.read_text(encoding="utf-8")
163
+ except OSError as exc:
164
+ raise ConfigError(f"cannot read {path}: {exc.strerror}") from exc
165
+ return cls.from_toml(text, source=str(path))
166
+
167
+ @classmethod
168
+ def discover(cls, start: str | Path | None = None) -> WspxConfig:
169
+ """Load the nearest ``wspx.toml`` at or above ``start``; defaults if there is none."""
170
+ found = find_config(start)
171
+ return cls.load(found) if found else cls()
172
+
173
+
174
+ def find_config(start: str | Path | None = None) -> Path | None:
175
+ here = Path(start or Path.cwd()).resolve()
176
+ for directory in (here, *here.parents):
177
+ candidate = directory / CONFIG_FILENAME
178
+ if candidate.is_file():
179
+ return candidate
180
+ return None
181
+
182
+
183
+ def _format_validation_error(source: str, exc: ValidationError) -> str:
184
+ lines = [f"{source}: invalid configuration"]
185
+ for err in exc.errors():
186
+ where = ".".join(str(p) for p in err["loc"]) or "(root)"
187
+ msg = err["msg"].removeprefix("Value error, ")
188
+ lines.append(f" {where}: {msg}")
189
+ return "\n".join(lines)
@@ -0,0 +1,5 @@
1
+ """The control plane (§3.1): API, UI, MCP endpoint, store and session lifecycle.
2
+
3
+ It runs on CPU, scales to zero, and is the store's single writer. It holds the
4
+ user's API token and the gateway admin token, never a provider key.
5
+ """
wspx/control/app.py ADDED
@@ -0,0 +1,488 @@
1
+ """The control plane's HTTP app: REST API, SSE timelines, hook ingest, MCP and the UI.
2
+
3
+ Who may call what:
4
+
5
+ * the **user token** (CLI, UI, MCP clients) may do anything the user can;
6
+ * a **runner token** may only call tools, post events and read commands and
7
+ the workspace for its own session;
8
+ * nobody but the user reaches limits, kill and resume. No agent tool exposes them.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import asyncio
14
+ import json
15
+ import os
16
+ import re
17
+ import threading
18
+ import time
19
+ from collections.abc import AsyncIterator, Callable
20
+ from contextlib import asynccontextmanager
21
+ from dataclasses import dataclass
22
+ from importlib.resources import files
23
+ from pathlib import Path
24
+ from typing import Any
25
+
26
+ from fastapi import Depends, FastAPI, HTTPException, Request
27
+ from fastapi.responses import HTMLResponse, JSONResponse, Response, StreamingResponse
28
+ from pydantic import BaseModel, Field
29
+ from starlette.types import Receive, Scope, Send
30
+
31
+ from wspx import __version__
32
+ from wspx import project as project_snapshot
33
+ from wspx.auth import TokenError, check_bearer, verify
34
+ from wspx.control.backend import Backend
35
+ from wspx.control.gateway_client import GatewayAdmin
36
+ from wspx.control.mcp_server import build_server
37
+ from wspx.control.sessions import SessionManager
38
+ from wspx.control.tracedb import TraceDB
39
+ from wspx.errors import WspxError
40
+ from wspx.store import Store
41
+
42
+ PROVIDER_CAPS = {
43
+ "anthropic": "https://platform.claude.com/settings/limits",
44
+ "openai": "https://platform.openai.com/settings/organization/limits",
45
+ "google": "https://aistudio.google.com/spend",
46
+ "modal": "https://modal.com/settings/usage",
47
+ }
48
+ _CALL_RE = re.compile(r"\[call (c_[0-9a-f]+)\]")
49
+
50
+
51
+ @dataclass
52
+ class ControlSettings:
53
+ store_root: str
54
+ api_token: str
55
+ secret: str
56
+ """Shared with the gateway; signs runner and LLM session tokens."""
57
+ gateway_url: str = ""
58
+ gateway_admin_token: str = ""
59
+ public_url: str = ""
60
+ tick_seconds: float = 30.0
61
+
62
+ @classmethod
63
+ def from_env(cls) -> ControlSettings:
64
+ return cls(
65
+ store_root=os.environ.get("WSPX_STORE", "/store"),
66
+ api_token=os.environ["WSPX_API_TOKEN"],
67
+ secret=os.environ["WSPX_GATEWAY_SECRET"],
68
+ gateway_url=os.environ.get("WSPX_GATEWAY_URL", ""),
69
+ gateway_admin_token=os.environ.get("WSPX_ADMIN_TOKEN", ""),
70
+ public_url=os.environ.get("WSPX_PUBLIC_URL", ""),
71
+ )
72
+
73
+
74
+ class NewSession(BaseModel):
75
+ model: str
76
+ driver: str | None = None
77
+ task: str = ""
78
+ gpu: str | None = None
79
+ branch: str | None = None
80
+ revision: str | None = None
81
+ dtype: str = "bfloat16"
82
+ trust_remote_code: bool = False
83
+ grace_s: float = Field(900.0, ge=0)
84
+ keep_warm: str = "auto"
85
+ project: str = ""
86
+ snapshot: str | None = Field(None, pattern=r"^sha256:[0-9a-f]{64}$")
87
+
88
+
89
+ class ToolCall(BaseModel):
90
+ args: dict[str, Any] = Field(default_factory=dict)
91
+ call_id: str | None = None
92
+ turn: int | None = None
93
+ source: str = "driver"
94
+
95
+
96
+ def create_app(
97
+ settings: ControlSettings,
98
+ backend: Backend,
99
+ *,
100
+ gateway: GatewayAdmin | None = None,
101
+ start_ticker: bool = True,
102
+ ) -> FastAPI:
103
+ store = Store(settings.store_root)
104
+ trace = TraceDB(Path(settings.store_root) / "trace.db")
105
+ if gateway is None and settings.gateway_url and settings.gateway_admin_token:
106
+ gateway = GatewayAdmin(settings.gateway_url, settings.gateway_admin_token)
107
+ manager = SessionManager(
108
+ store,
109
+ trace,
110
+ backend,
111
+ gateway=gateway,
112
+ secret=settings.secret,
113
+ control_url=settings.public_url,
114
+ gateway_url=settings.gateway_url,
115
+ )
116
+
117
+ def bearer(request: Request) -> str | None:
118
+ auth = request.headers.get("authorization", "")
119
+ if auth.lower().startswith("bearer "):
120
+ return auth[7:]
121
+ return request.query_params.get("token")
122
+
123
+ def user(request: Request) -> None:
124
+ if not check_bearer(settings.api_token, bearer(request)):
125
+ raise HTTPException(401, "user token required")
126
+
127
+ def session_caller(request: Request) -> str:
128
+ """``"user"`` or ``"runner"``; a runner token only works for its own session."""
129
+ token = bearer(request)
130
+ if check_bearer(settings.api_token, token):
131
+ return "user"
132
+ try:
133
+ claims = verify(settings.secret, token or "", scope="runner")
134
+ except TokenError:
135
+ raise HTTPException(401, "token required") from None
136
+ if claims.session != request.path_params.get("sid"):
137
+ raise HTTPException(403, "this runner token is for another session")
138
+ return "runner"
139
+
140
+ def guarded(fn: Callable[..., Any]) -> Any:
141
+ try:
142
+ return fn()
143
+ except WspxError as exc:
144
+ raise HTTPException(400, str(exc)) from None
145
+
146
+ # ------------------------------------------------------------------ MCP
147
+
148
+ def mcp_call(session: str | None, name: str, args: dict[str, Any]) -> dict[str, Any]:
149
+ if session is None:
150
+ running = [r.id for r in manager.records.values() if r.status in ("idle", "running")]
151
+ if len(running) != 1:
152
+ return {
153
+ "summary": "pick a session: set the X-Wspx-Session header (see `wspx connect`)",
154
+ "ok": False,
155
+ }
156
+ session = running[0]
157
+ try:
158
+ return manager.tool(session, name, args, source="mcp")
159
+ except WspxError as exc:
160
+ return {"summary": str(exc), "ok": False}
161
+
162
+ from mcp.server.transport_security import TransportSecuritySettings
163
+
164
+ mcp_server = build_server(mcp_call)
165
+ mcp_inner = mcp_server.streamable_http_app(
166
+ streamable_http_path="/",
167
+ stateless_http=True,
168
+ json_response=True,
169
+ transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
170
+ )
171
+
172
+ async def mcp_app(scope: Scope, receive: Receive, send: Send) -> None:
173
+ if scope["type"] == "http":
174
+ headers = {k.decode().lower(): v.decode() for k, v in scope.get("headers", [])}
175
+ auth = headers.get("authorization", "")
176
+ if not check_bearer(
177
+ settings.api_token, auth[7:] if auth.lower().startswith("bearer ") else None
178
+ ):
179
+ response = JSONResponse({"error": "user token required"}, status_code=401)
180
+ await response(scope, receive, send)
181
+ return
182
+ await mcp_inner(scope, receive, send)
183
+
184
+ # ------------------------------------------------------------------ lifecycle
185
+
186
+ stop = threading.Event()
187
+
188
+ def ticker() -> None:
189
+ while not stop.wait(settings.tick_seconds):
190
+ try:
191
+ manager.tick()
192
+ except Exception as exc:
193
+ print(f"wspx control: tick failed: {exc}", flush=True)
194
+
195
+ @asynccontextmanager
196
+ async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
197
+ async with mcp_inner.router.lifespan_context(mcp_inner):
198
+ thread = threading.Thread(target=ticker, daemon=True) if start_ticker else None
199
+ if thread is not None:
200
+ thread.start()
201
+ yield
202
+ stop.set()
203
+
204
+ app = FastAPI(
205
+ title="wspx", version=__version__, lifespan=lifespan, docs_url=None, redoc_url=None
206
+ )
207
+ app.state.manager = manager
208
+ app.state.trace = trace
209
+ app.mount("/mcp", mcp_app)
210
+
211
+ # ------------------------------------------------------------------ sessions
212
+
213
+ @app.get("/healthz")
214
+ def health() -> dict[str, Any]:
215
+ return {"ok": True, "version": __version__, "halted": manager.halted}
216
+
217
+ @app.get("/api/sessions", dependencies=[Depends(user)])
218
+ def list_sessions() -> dict[str, Any]:
219
+ return {"sessions": [r.to_dict() for r in manager.records.values()]}
220
+
221
+ @app.post("/api/sessions", dependencies=[Depends(user)])
222
+ def new_session(body: NewSession) -> dict[str, Any]:
223
+ record = guarded(lambda: manager.create(**body.model_dump()))
224
+ return record.to_dict() # type: ignore[no-any-return]
225
+
226
+ @app.post("/api/projects", dependencies=[Depends(user)])
227
+ async def upload_project(request: Request) -> dict[str, Any]:
228
+ """Store a project snapshot (a gzipped tar from ``wspx.project``) by content hash."""
229
+ data = await request.body()
230
+ if len(data) > project_snapshot.MAX_BYTES:
231
+ raise HTTPException(413, "project snapshot too large")
232
+ infos = guarded(lambda: project_snapshot.members(data))
233
+ return {"snapshot": store.objects.put(data), "files": len(infos)}
234
+
235
+ @app.get("/api/sessions/{sid}", dependencies=[Depends(user)])
236
+ def get_session(sid: str) -> dict[str, Any]:
237
+ record = guarded(lambda: manager.get(sid))
238
+ out = record.to_dict()
239
+ if manager.gateway is not None:
240
+ try:
241
+ out["usage"] = manager.gateway.usage(session=sid)
242
+ except WspxError as exc:
243
+ out["usage"] = {"error": str(exc)}
244
+ return out # type: ignore[no-any-return]
245
+
246
+ @app.post("/api/sessions/{sid}/tools/{name}")
247
+ def tool(
248
+ sid: str, name: str, body: ToolCall, caller: str = Depends(session_caller)
249
+ ) -> dict[str, Any]:
250
+ source = (
251
+ body.source
252
+ if caller == "runner"
253
+ else (body.source if body.source != "driver" else "human")
254
+ )
255
+ result: dict[str, Any] = guarded(
256
+ lambda: manager.tool(
257
+ sid, name, body.args, call_id=body.call_id, source=source, turn=body.turn
258
+ )
259
+ )
260
+ return result
261
+
262
+ @app.post("/api/sessions/{sid}/events")
263
+ async def runner_event(
264
+ sid: str, request: Request, _caller: str = Depends(session_caller)
265
+ ) -> dict[str, Any]:
266
+ manager.runner_event(sid, await request.json())
267
+ return {"ok": True}
268
+
269
+ @app.get("/api/sessions/{sid}/commands")
270
+ def commands(sid: str, _caller: str = Depends(session_caller)) -> dict[str, Any]:
271
+ manager.touch(sid)
272
+ return {"commands": manager.take_commands(sid)}
273
+
274
+ @app.get("/api/sessions/{sid}/workspace")
275
+ def workspace(sid: str, _caller: str = Depends(session_caller)) -> dict[str, Any]:
276
+ return {"workspace": manager.workspace.get(sid, "")}
277
+
278
+ @app.post("/api/sessions/{sid}/{action}", dependencies=[Depends(user)])
279
+ async def control(sid: str, action: str, request: Request) -> dict[str, Any]:
280
+ body = await request.json() if await request.body() else {}
281
+ if action == "pause":
282
+ guarded(lambda: manager.pause(sid, body.get("reason", "paused by user")))
283
+ elif action == "resume":
284
+ guarded(lambda: manager.resume(sid))
285
+ elif action == "stop":
286
+ guarded(lambda: manager.kill(sid))
287
+ elif action == "inject":
288
+ guarded(lambda: manager.command(sid, "inject", body.get("text", "")))
289
+ elif action == "start":
290
+ guarded(lambda: manager.start_driver(sid))
291
+ else:
292
+ raise HTTPException(404, f"unknown action {action}")
293
+ return {"ok": True, "session": manager.get(sid).to_dict()}
294
+
295
+ @app.get("/api/sessions/{sid}/timeline", dependencies=[Depends(user)])
296
+ def timeline(sid: str, since: int = 0) -> dict[str, Any]:
297
+ return {"events": trace.events(sid, since)}
298
+
299
+ @app.get("/api/sessions/{sid}/stream", dependencies=[Depends(user)])
300
+ async def stream(sid: str, request: Request, since: int = 0) -> StreamingResponse:
301
+ guarded(lambda: manager.get(sid))
302
+
303
+ async def events() -> AsyncIterator[bytes]:
304
+ manager.viewers[sid] += 1
305
+ last = since
306
+ try:
307
+ while not await request.is_disconnected():
308
+ manager.touch(sid)
309
+ rows = trace.events(sid, last)
310
+ for row in rows:
311
+ last = row["id"]
312
+ yield f"id: {row['id']}\nevent: {row['kind']}\ndata: {json.dumps(row)}\n\n".encode()
313
+ if not rows:
314
+ yield b": keep-alive\n\n"
315
+ await asyncio.sleep(0.5)
316
+ finally:
317
+ manager.viewers[sid] -= 1
318
+
319
+ return StreamingResponse(events(), media_type="text/event-stream")
320
+
321
+ @app.get("/api/calls/{call_id}", dependencies=[Depends(user)])
322
+ def call(call_id: str) -> dict[str, Any]:
323
+ found = trace.call(call_id)
324
+ if found is None:
325
+ raise HTTPException(404, "no such call")
326
+ return found
327
+
328
+ # ------------------------------------------------------------------ views for the UI
329
+
330
+ from wspx.control import views
331
+
332
+ def _fp(sid: str) -> str | None:
333
+ return guarded(lambda: manager.get(sid)).fingerprint # type: ignore[no-any-return]
334
+
335
+ @app.get("/api/sessions/{sid}/architecture", dependencies=[Depends(user)])
336
+ def architecture(sid: str) -> dict[str, Any]:
337
+ return views.architecture(store, _fp(sid))
338
+
339
+ @app.get("/api/sessions/{sid}/commits", dependencies=[Depends(user)])
340
+ def commits(sid: str) -> dict[str, Any]:
341
+ return views.commits(store, _fp(sid), sid)
342
+
343
+ @app.get("/api/sessions/{sid}/runs", dependencies=[Depends(user)])
344
+ def runs(sid: str) -> dict[str, Any]:
345
+ return views.runs(store, _fp(sid), sid)
346
+
347
+ @app.get("/api/sessions/{sid}/handles", dependencies=[Depends(user)])
348
+ def handles(sid: str) -> dict[str, Any]:
349
+ return views.handles(store, sid)
350
+
351
+ @app.get("/api/objects/{oid}", dependencies=[Depends(user)])
352
+ def json_object(oid: str) -> Any:
353
+ return guarded(lambda: views.json_object(store, oid))
354
+
355
+ # ------------------------------------------------------------------ spend and safety
356
+
357
+ def need_gateway() -> GatewayAdmin:
358
+ if manager.gateway is None:
359
+ raise HTTPException(503, "no gateway configured")
360
+ return manager.gateway
361
+
362
+ @app.get("/api/keys", dependencies=[Depends(user)])
363
+ def get_keys() -> dict[str, Any]:
364
+ return {"keys": guarded(lambda: need_gateway().keys())}
365
+
366
+ @app.post("/api/keys/reload", dependencies=[Depends(user)])
367
+ def reload_keys() -> dict[str, Any]:
368
+ return {"reloaded": guarded(lambda: need_gateway().recycle())}
369
+
370
+ @app.get("/api/limits", dependencies=[Depends(user)])
371
+ def get_limits() -> dict[str, Any]:
372
+ return {"limits": guarded(lambda: need_gateway().limits())}
373
+
374
+ @app.post("/api/limits", dependencies=[Depends(user)])
375
+ async def set_limit(request: Request) -> dict[str, Any]:
376
+ body = await request.json()
377
+ return guarded(lambda: need_gateway().set_limit(body)) # type: ignore[no-any-return]
378
+
379
+ @app.delete("/api/limits/{limit_id}", dependencies=[Depends(user)])
380
+ def remove_limit(limit_id: str) -> dict[str, Any]:
381
+ return {"removed": guarded(lambda: need_gateway().remove_limit(limit_id))}
382
+
383
+ @app.post("/api/prices", dependencies=[Depends(user)])
384
+ async def set_price(request: Request) -> dict[str, Any]:
385
+ body = await request.json()
386
+ guarded(
387
+ lambda: need_gateway().price(body["model"], float(body["input"]), float(body["output"]))
388
+ )
389
+ return {"ok": True}
390
+
391
+ @app.get("/api/usage", dependencies=[Depends(user)])
392
+ def usage(session: str | None = None, since: float = 0.0) -> dict[str, Any]:
393
+ return guarded(lambda: need_gateway().usage(session, since)) # type: ignore[no-any-return]
394
+
395
+ @app.post("/api/kill", dependencies=[Depends(user)])
396
+ async def kill(request: Request) -> dict[str, Any]:
397
+ body = await request.json() if await request.body() else {}
398
+ return {"stopped": guarded(lambda: manager.kill(body.get("session")))}
399
+
400
+ @app.post("/api/resume", dependencies=[Depends(user)])
401
+ async def resume(request: Request) -> dict[str, Any]:
402
+ body = await request.json() if await request.body() else {}
403
+ guarded(lambda: manager.resume(body.get("session")))
404
+ return {"ok": True}
405
+
406
+ @app.get("/api/doctor", dependencies=[Depends(user)])
407
+ def doctor() -> dict[str, Any]:
408
+ limits: list[dict[str, Any]] | str
409
+ try:
410
+ limits = need_gateway().limits()
411
+ except HTTPException as exc:
412
+ limits = str(exc.detail)
413
+ except WspxError as exc:
414
+ limits = str(exc)
415
+ running = [
416
+ r.to_dict()
417
+ for r in manager.records.values()
418
+ if r.tier != "cold" or r.status == "running"
419
+ ]
420
+ return {
421
+ "halted": manager.halted,
422
+ "limits": limits,
423
+ "active": running,
424
+ "provider_caps": PROVIDER_CAPS,
425
+ "note": "wspx sets no limits by default; provider caps are set in each provider's console",
426
+ }
427
+
428
+ # ------------------------------------------------------------------ hooks from external agents
429
+
430
+ @app.post("/api/ingest/{client}", dependencies=[Depends(user)])
431
+ async def ingest(client: str, request: Request, session: str | None = None) -> dict[str, Any]:
432
+ payload = await request.json()
433
+ sid = session or request.headers.get("x-wspx-session") or "external"
434
+ text = json.dumps(payload.get("tool_response") or payload.get("tool_output") or "")
435
+ joined = _CALL_RE.search(text)
436
+ trace.event(
437
+ sid,
438
+ "hook",
439
+ {
440
+ "client": client,
441
+ "event": payload.get("hook_event_name") or payload.get("event"),
442
+ "tool": payload.get("tool_name"),
443
+ "call_id": joined.group(1) if joined else None,
444
+ "payload": payload,
445
+ },
446
+ source=client,
447
+ )
448
+ return {"ok": True, "joined": joined.group(1) if joined else None}
449
+
450
+ # ------------------------------------------------------------------ UI
451
+
452
+ @app.get("/", response_class=HTMLResponse)
453
+ def index() -> Response:
454
+ ui = files("wspx.control").joinpath("ui/index.html")
455
+ if ui.is_file():
456
+ return HTMLResponse(ui.read_text(encoding="utf-8"))
457
+ return HTMLResponse(
458
+ "<!doctype html><title>wspx</title><p>wspx control plane is running.</p>"
459
+ )
460
+
461
+ @app.get("/assets/{name}")
462
+ def asset(name: str) -> Response:
463
+ path = files("wspx.control").joinpath(f"ui/assets/{name}")
464
+ if "/" in name or not path.is_file():
465
+ raise HTTPException(404)
466
+ kind = (
467
+ "text/javascript"
468
+ if name.endswith(".js")
469
+ else "text/css"
470
+ if name.endswith(".css")
471
+ else "application/octet-stream"
472
+ )
473
+ return Response(
474
+ path.read_bytes(),
475
+ media_type=kind,
476
+ headers={"cache-control": "public, max-age=31536000"},
477
+ )
478
+
479
+ app.state.started = time.time()
480
+ return app
481
+
482
+
483
+ def create_app_from_env() -> FastAPI:
484
+ """Factory for ``uvicorn --factory`` (self-hosting with in-process labs)."""
485
+ from wspx.control.backend import LocalBackend
486
+
487
+ settings = ControlSettings.from_env()
488
+ return create_app(settings, LocalBackend(settings.store_root))