t4l-server 0.1.0__py3-none-any.whl

t4l_server/__init__.py

@@ -0,0 +1,5 @@
+"""Self-hosted REST and MCP server for T4L Trainer."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

t4l_server/cli.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import argparse
+import secrets
+import socket
+from pathlib import Path
+
+from .server import ServerConfig, run_server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="t4l-server")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    serve = subparsers.add_parser("serve", help="Start the self-hosted T4L server.")
+    serve.add_argument(
+        "--data-dir",
+        type=Path,
+        help="Server data directory. Stores t4l.sqlite and blobs.",
+    )
+    serve.add_argument(
+        "--dir",
+        type=Path,
+        help="Compatibility alias for --data-dir.",
+    )
+    serve.add_argument("--host", default="0.0.0.0", help="Bind host.")
+    serve.add_argument("--port", default=8787, type=int, help="Bind port.")
+    serve.add_argument(
+        "--api-key",
+        default=None,
+        help="API key. Defaults to a new key for every start.",
+    )
+    serve.add_argument(
+        "--token",
+        default=None,
+        help="Compatibility alias for --api-key.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        data_dir = args.data_dir or args.dir
+        if data_dir is None:
+            parser.error("serve requires --data-dir")
+        token = args.api_key or args.token or _new_api_key()
+        config = ServerConfig(
+            exchange_dir=data_dir.expanduser().resolve(),
+            host=args.host,
+            port=args.port,
+            token=token,
+        )
+        _print_startup(config)
+        run_server(config)
+        return 0
+    return 1
+
+
+def _bridge_main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        import sys
+
+        argv = sys.argv[1:]
+    translated = ["serve" if item == "serve" else item for item in argv]
+    if "--data-dir" not in translated and "--dir" in translated:
+        # The parser accepts --dir directly; this keeps the old command shape.
+        pass
+    return main(translated)
+
+
+def _new_api_key() -> str:
+    return secrets.token_urlsafe(24)
+
+
+def _print_startup(config: ServerConfig) -> None:
+    lan_host = _lan_ip() if config.host in {"0.0.0.0", "::"} else config.host
+    print("T4L Self-Hosted Server")
+    print(f"Data dir: {config.data_dir}")
+    print(f"Server URL: http://{lan_host}:{config.port}")
+    print(f"MCP URL: http://{lan_host}:{config.port}/mcp")
+    print(f"API key: {config.token}")
+    print("Enter the server URL and API key in the T4L Trainer Settings screen.")
+
+
+def _lan_ip() -> str:
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        try:
+            sock.connect(("8.8.8.8", 80))
+            return str(sock.getsockname()[0])
+        except OSError:
+            return "127.0.0.1"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

t4l_server/mcp.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Any
+
+from . import __version__
+from .store import Artifact, ArtifactStore
+
+
+def handle_mcp_message(store: ArtifactStore, message: dict[str, Any]) -> dict[str, Any]:
+    method = str(message.get("method") or "")
+    request_id = message.get("id")
+    if method == "initialize":
+        return _result(
+            request_id,
+            {
+                "protocolVersion": "2025-06-18",
+                "serverInfo": {"name": "t4l-server", "version": __version__},
+                "capabilities": {"tools": {}},
+            },
+        )
+    if method == "tools/list":
+        return _result(request_id, {"tools": _tools()})
+    if method == "tools/call":
+        params = message.get("params")
+        if not isinstance(params, dict):
+            return _error(request_id, -32602, "Invalid params.")
+        return _call_tool(store, request_id, params)
+    return _error(request_id, -32601, f"Unsupported MCP method: {method}")
+
+
+def _call_tool(
+    store: ArtifactStore,
+    request_id: object,
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    name = str(params.get("name") or "")
+    arguments = params.get("arguments")
+    args = arguments if isinstance(arguments, dict) else {}
+    if name == "get_day_context":
+        return _artifact_result(request_id, store.latest("day_context"))
+    if name == "get_app_snapshot":
+        return _artifact_result(request_id, store.latest("app_snapshot"))
+    if name == "get_profile":
+        return _artifact_result(request_id, store.latest("athlete_profile"))
+    if name == "get_pending_requests":
+        return _payload_result(
+            request_id,
+            {
+                "requests": [
+                    artifact.summary()
+                    for artifact in [
+                        store.latest("training_block_request"),
+                        store.latest("nutrition_analysis_request"),
+                    ]
+                    if artifact is not None
+                ]
+            },
+        )
+    write_kinds = {
+        "write_training_block_plan": "training_block_plan",
+        "write_fuel_guidance": "fuel_guidance",
+        "write_nutrition_analysis_result": "nutrition_analysis_result",
+    }
+    if name in write_kinds:
+        payload = args.get("payload")
+        if not isinstance(payload, dict):
+            return _error(request_id, -32602, "Tool requires object argument: payload.")
+        artifact = store.upsert_artifact(write_kinds[name], payload, status="pending")
+        return _payload_result(request_id, {"stored": artifact.summary()})
+    return _error(request_id, -32602, f"Unknown tool: {name}")
+
+
+def _artifact_result(request_id: object, artifact: Artifact | None) -> dict[str, Any]:
+    if artifact is None:
+        return _payload_result(request_id, None)
+    return _payload_result(request_id, artifact.payload)
+
+
+def _payload_result(request_id: object, payload: object) -> dict[str, Any]:
+    return _result(
+        request_id,
+        {
+            "content": [
+                {
+                    "type": "text",
+                    "text": _json_text(payload),
+                }
+            ],
+            "structuredContent": payload,
+        },
+    )
+
+
+def _json_text(payload: object) -> str:
+    import json
+
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _tools() -> list[dict[str, Any]]:
+    object_schema = {
+        "type": "object",
+        "properties": {"payload": {"type": "object"}},
+        "required": ["payload"],
+    }
+    return [
+        {
+            "name": "get_day_context",
+            "description": "Read latest day context.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_app_snapshot",
+            "description": "Read latest full app snapshot.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_profile",
+            "description": "Read latest athlete profile.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_pending_requests",
+            "description": "List pending app requests.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "write_training_block_plan",
+            "description": "Write a pending training block plan.",
+            "inputSchema": object_schema,
+        },
+        {
+            "name": "write_fuel_guidance",
+            "description": "Write pending fuel guidance.",
+            "inputSchema": object_schema,
+        },
+        {
+            "name": "write_nutrition_analysis_result",
+            "description": "Write a pending nutrition result.",
+            "inputSchema": object_schema,
+        },
+    ]
+
+
+def _result(request_id: object, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: object, code: int, message: str) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": code, "message": message},
+    }

t4l_server/server.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+from .mcp import handle_mcp_message
+from .store import ArtifactStore
+
+APP_UPLOAD_FILES = {
+    "day_context.json": "day_context",
+    "daily_snapshot.json": "daily_snapshot",
+    "athlete_profile.json": "athlete_profile",
+    "training_block_request.json": "training_block_request",
+    "nutrition_analysis_request.json": "nutrition_analysis_request",
+}
+AGENT_RESULT_FILES = {
+    "training_block_plan.json": "training_block_plan",
+    "next_day_plan.json": "next_day_plan",
+    "nutrition_analysis_result.json": "nutrition_analysis_result",
+    "fuel_guidance.json": "fuel_guidance",
+}
+ALL_EXCHANGE_FILES = APP_UPLOAD_FILES | AGENT_RESULT_FILES
+REST_CONTEXT_PATHS = {
+    "/v1/context/day": "day_context",
+    "/v1/context/daily-snapshot": "daily_snapshot",
+    "/v1/profile": "athlete_profile",
+}
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    exchange_dir: Path
+    host: str
+    port: int
+    token: str
+
+    @property
+    def data_dir(self) -> Path:
+        return self.exchange_dir
+
+
+def run_server(config: ServerConfig) -> None:
+    server = create_server(config)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+def create_server(config: ServerConfig) -> ThreadingHTTPServer:
+    config.data_dir.mkdir(parents=True, exist_ok=True)
+    store = ArtifactStore(config.data_dir)
+    handler = _handler_factory(config, store)
+    return ThreadingHTTPServer((config.host, config.port), handler)
+
+
+def _handler_factory(
+    config: ServerConfig,
+    store: ArtifactStore,
+) -> type[BaseHTTPRequestHandler]:
+    class T4LHandler(BaseHTTPRequestHandler):
+        server_version = "T4LServer/0.2"
+
+        def do_GET(self) -> None:
+            path = urlparse(self.path).path
+            if path == "/health":
+                self._send_json(
+                    {
+                        "status": "ok",
+                        "service": "t4l-server",
+                        "dataDir": str(config.data_dir),
+                        "sqlite": str(store.db_path),
+                    }
+                )
+                return
+            if path == "/manifest":
+                if not self._authorized():
+                    self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                    return
+                self._send_json(_manifest(store))
+                return
+            if path == "/v1/results/pending":
+                if not self._authorized():
+                    self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                    return
+                self._send_json(
+                    {
+                        "results": [
+                            artifact.summary() for artifact in store.pending_results()
+                        ]
+                    }
+                )
+                return
+            result_kind = _result_kind_from_path(path)
+            if result_kind is not None:
+                if not self._authorized():
+                    self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                    return
+                artifact = store.latest(result_kind)
+                if artifact is None or artifact.consumed_at is not None:
+                    self._send_error(HTTPStatus.NOT_FOUND, "Result not found.")
+                    return
+                self._send_json(artifact.payload)
+                return
+            file_name = _file_name_from_path(path)
+            if file_name is None:
+                self._send_error(HTTPStatus.NOT_FOUND, "Unknown endpoint.")
+                return
+            self._handle_file_get(file_name)
+
+        def do_POST(self) -> None:
+            path = urlparse(self.path).path
+            if path == "/mcp":
+                self._handle_mcp()
+                return
+            file_name = _file_name_from_path(path)
+            if file_name is None:
+                self._send_error(HTTPStatus.NOT_FOUND, "Unknown endpoint.")
+                return
+            self._handle_file_write(file_name)
+
+        def do_PUT(self) -> None:
+            path = urlparse(self.path).path
+            if not self._authorized():
+                self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                return
+            if path == "/v1/app/snapshot":
+                payload = self._read_json_body()
+                if payload is None:
+                    return
+                store.upsert_artifact("app_snapshot", payload, status="current")
+                self._send_json({"status": "stored", "kind": "app_snapshot"})
+                return
+            kind = REST_CONTEXT_PATHS.get(path)
+            if kind is not None:
+                payload = self._read_json_body()
+                if payload is None:
+                    return
+                store.upsert_artifact(kind, payload, status="current")
+                self._send_json({"status": "stored", "kind": kind})
+                return
+            self._send_error(HTTPStatus.NOT_FOUND, "Unknown endpoint.")
+
+        def do_DELETE(self) -> None:
+            path = urlparse(self.path).path
+            result_kind = _result_kind_from_path(path)
+            if result_kind is not None:
+                if not self._authorized():
+                    self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                    return
+                store.mark_consumed(result_kind)
+                self._send_json({"status": "consumed", "kind": result_kind})
+                return
+            file_name = _file_name_from_path(path)
+            if file_name is None:
+                self._send_error(HTTPStatus.NOT_FOUND, "Unknown endpoint.")
+                return
+            self._handle_file_delete(file_name)
+
+        def log_message(self, format: str, *args: object) -> None:
+            return
+
+        def _handle_mcp(self) -> None:
+            if not self._authorized():
+                self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                return
+            payload = self._read_json_body()
+            if payload is None:
+                return
+            self._send_json(handle_mcp_message(store, payload))
+
+        def _handle_file_get(self, file_name: str) -> None:
+            if not self._authorized():
+                self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                return
+            if file_name.startswith("meal_images/"):
+                target = _safe_blob_path(config.data_dir, file_name)
+                if target is None:
+                    self._send_error(HTTPStatus.FORBIDDEN, "File is not allowed.")
+                    return
+                if not target.exists():
+                    self._send_error(HTTPStatus.NOT_FOUND, "File not found.")
+                    return
+                self._send_bytes(target.read_bytes(), "application/octet-stream")
+                return
+            kind = ALL_EXCHANGE_FILES.get(file_name)
+            if kind is None:
+                self._send_error(HTTPStatus.FORBIDDEN, "File is not allowed.")
+                return
+            artifact = store.latest(kind)
+            if artifact is None or artifact.consumed_at is not None:
+                self._send_error(HTTPStatus.NOT_FOUND, "File not found.")
+                return
+            self._send_json(artifact.payload)
+
+        def _handle_file_write(self, file_name: str) -> None:
+            if not self._authorized():
+                self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                return
+            body = self._read_body()
+            if body is None:
+                return
+            if file_name.startswith("meal_images/"):
+                target = _safe_blob_path(config.data_dir, file_name)
+                if target is None:
+                    self._send_error(HTTPStatus.FORBIDDEN, "File is not allowed.")
+                    return
+                _atomic_write(target, body)
+                self._send_json({"status": "stored", "file": file_name})
+                return
+            kind = ALL_EXCHANGE_FILES.get(file_name)
+            if kind is None:
+                self._send_error(HTTPStatus.FORBIDDEN, "File is not allowed.")
+                return
+            payload = _decode_json(body)
+            if payload is None:
+                self._send_error(HTTPStatus.BAD_REQUEST, "Invalid JSON payload.")
+                return
+            status = "pending" if file_name in AGENT_RESULT_FILES else "current"
+            store.upsert_artifact(kind, payload, status=status)
+            self._send_json({"status": "stored", "file": file_name, "kind": kind})
+
+        def _handle_file_delete(self, file_name: str) -> None:
+            if not self._authorized():
+                self._send_error(HTTPStatus.UNAUTHORIZED, "Invalid API key.")
+                return
+            kind = AGENT_RESULT_FILES.get(file_name)
+            if kind is None:
+                self._send_error(HTTPStatus.FORBIDDEN, "File is not allowed.")
+                return
+            store.mark_consumed(kind)
+            self._send_json({"status": "deleted", "file": file_name, "kind": kind})
+
+        def _authorized(self) -> bool:
+            auth = self.headers.get("authorization", "")
+            bearer = auth.removeprefix("Bearer ").strip()
+            return (
+                self.headers.get("x-t4l-token") == config.token
+                or bearer == config.token
+            )
+
+        def _read_body(self) -> bytes | None:
+            length = int(self.headers.get("content-length", "0"))
+            if length <= 0:
+                self._send_error(HTTPStatus.BAD_REQUEST, "Request body is empty.")
+                return None
+            return self.rfile.read(length)
+
+        def _read_json_body(self) -> dict[str, Any] | None:
+            body = self._read_body()
+            if body is None:
+                return None
+            payload = _decode_json(body)
+            if payload is None:
+                self._send_error(HTTPStatus.BAD_REQUEST, "Invalid JSON payload.")
+                return None
+            return payload
+
+        def _send_json(self, payload: dict[str, Any]) -> None:
+            self._send_bytes(
+                json.dumps(payload, indent=2).encode("utf-8"),
+                "application/json",
+            )
+
+        def _send_bytes(self, body: bytes, content_type: str) -> None:
+            self.send_response(HTTPStatus.OK)
+            self.send_header("content-type", content_type)
+            self.send_header("content-length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _send_error(self, status: HTTPStatus, message: str) -> None:
+            body = json.dumps({"error": message}).encode("utf-8")
+            self.send_response(status)
+            self.send_header("content-type", "application/json")
+            self.send_header("content-length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+    return T4LHandler
+
+
+def _manifest(store: ArtifactStore) -> dict[str, Any]:
+    files = []
+    for file_name, kind in sorted(ALL_EXCHANGE_FILES.items()):
+        artifact = store.latest(kind)
+        if artifact is None or artifact.consumed_at is not None:
+            continue
+        files.append({"name": file_name, **artifact.summary()})
+    return {
+        "schema": "t4l_server_manifest.v1",
+        "appUploadFiles": sorted(APP_UPLOAD_FILES),
+        "agentResultFiles": sorted(AGENT_RESULT_FILES),
+        "files": files,
+    }
+
+
+def _file_name_from_path(path: str) -> str | None:
+    prefix = "/files/"
+    if not path.startswith(prefix):
+        return None
+    return unquote(path[len(prefix) :])
+
+
+def _result_kind_from_path(path: str) -> str | None:
+    prefix = "/v1/results/"
+    if not path.startswith(prefix):
+        return None
+    kind = path[len(prefix) :].strip("/")
+    return kind if kind in set(AGENT_RESULT_FILES.values()) else None
+
+
+def _safe_blob_path(data_dir: Path, file_name: str) -> Path | None:
+    if file_name.startswith("/") or "\\" in file_name:
+        return None
+    normalized = Path(file_name)
+    if any(part in {"", ".", ".."} for part in normalized.parts):
+        return None
+    if len(normalized.parts) < 2 or normalized.parts[0] != "meal_images":
+        return None
+    resolved = (data_dir / "blobs" / normalized).resolve()
+    try:
+        resolved.relative_to((data_dir / "blobs").resolve())
+    except ValueError:
+        return None
+    return resolved
+
+
+def _decode_json(body: bytes) -> dict[str, Any] | None:
+    try:
+        decoded = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return decoded if isinstance(decoded, dict) else None
+
+
+def _atomic_write(target: Path, body: bytes) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile(
+        "wb",
+        delete=False,
+        dir=target.parent,
+        prefix=f".{target.name}.",
+        suffix=".tmp",
+    ) as tmp:
+        tmp.write(body)
+        tmp_path = Path(tmp.name)
+    os.replace(tmp_path, target)

t4l_server/store.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+_ARTIFACT_COLUMNS = (
+    "id, kind, schema, payload_json, status, created_at, updated_at, consumed_at"
+)
+
+
+RESULT_KINDS = frozenset(
+    {
+        "training_block_plan",
+        "next_day_plan",
+        "nutrition_analysis_result",
+        "fuel_guidance",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Artifact:
+    id: str
+    kind: str
+    schema: str
+    payload: dict[str, Any]
+    status: str
+    created_at: str
+    updated_at: str
+    consumed_at: str | None
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "schema": self.schema,
+            "status": self.status,
+            "createdAt": self.created_at,
+            "updatedAt": self.updated_at,
+            "consumedAt": self.consumed_at,
+        }
+
+
+class ArtifactStore:
+    def __init__(self, data_dir: Path) -> None:
+        self.data_dir = data_dir
+        self.db_path = data_dir / "t4l.sqlite"
+        self.blobs_dir = data_dir / "blobs"
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.blobs_dir.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def upsert_artifact(
+        self,
+        kind: str,
+        payload: dict[str, Any],
+        *,
+        status: str | None = None,
+    ) -> Artifact:
+        now = _now()
+        schema = str(payload.get("schema") or f"{kind}.v1")
+        artifact_id = f"{kind}:latest"
+        artifact_status = status or ("pending" if kind in RESULT_KINDS else "current")
+        encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True)
+        with self._connect() as db:
+            existing = db.execute(
+                "SELECT created_at FROM artifacts WHERE id = ?",
+                [artifact_id],
+            ).fetchone()
+            created_at = str(existing["created_at"]) if existing else now
+            db.execute(
+                """
+                INSERT INTO artifacts(
+                  id, kind, schema, payload_json, status,
+                  created_at, updated_at, consumed_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, NULL)
+                ON CONFLICT(id) DO UPDATE SET
+                  schema = excluded.schema,
+                  payload_json = excluded.payload_json,
+                  status = excluded.status,
+                  updated_at = excluded.updated_at,
+                  consumed_at = NULL
+                """,
+                [
+                    artifact_id,
+                    kind,
+                    schema,
+                    encoded,
+                    artifact_status,
+                    created_at,
+                    now,
+                ],
+            )
+        return self.latest(kind) or Artifact(
+            id=artifact_id,
+            kind=kind,
+            schema=schema,
+            payload=payload,
+            status=artifact_status,
+            created_at=created_at,
+            updated_at=now,
+            consumed_at=None,
+        )
+
+    def latest(self, kind: str) -> Artifact | None:
+        with self._connect() as db:
+            row = db.execute(
+                f"""
+                SELECT {_ARTIFACT_COLUMNS}
+                FROM artifacts
+                WHERE kind = ?
+                ORDER BY updated_at DESC
+                LIMIT 1
+                """,
+                [kind],
+            ).fetchone()
+        return _artifact_from_row(row) if row else None
+
+    def pending_results(self) -> list[Artifact]:
+        placeholders = ",".join("?" for _ in RESULT_KINDS)
+        with self._connect() as db:
+            rows = db.execute(
+                f"""
+                SELECT {_ARTIFACT_COLUMNS}
+                FROM artifacts
+                WHERE kind IN ({placeholders}) AND consumed_at IS NULL
+                ORDER BY updated_at DESC
+                """,
+                sorted(RESULT_KINDS),
+            ).fetchall()
+        return [_artifact_from_row(row) for row in rows]
+
+    def mark_consumed(self, kind: str) -> bool:
+        now = _now()
+        with self._connect() as db:
+            cursor = db.execute(
+                """
+                UPDATE artifacts
+                SET status = 'consumed', consumed_at = ?, updated_at = ?
+                WHERE kind = ? AND consumed_at IS NULL
+                """,
+                [now, now, kind],
+            )
+            return cursor.rowcount > 0
+
+    def history(self, kind: str) -> list[Artifact]:
+        with self._connect() as db:
+            rows = db.execute(
+                f"""
+                SELECT {_ARTIFACT_COLUMNS}
+                FROM artifacts
+                WHERE kind = ?
+                ORDER BY updated_at DESC
+                """,
+                [kind],
+            ).fetchall()
+        return [_artifact_from_row(row) for row in rows]
+
+    def _init_db(self) -> None:
+        with self._connect() as db:
+            db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS artifacts (
+                  id TEXT PRIMARY KEY,
+                  kind TEXT NOT NULL,
+                  schema TEXT NOT NULL,
+                  payload_json TEXT NOT NULL,
+                  status TEXT NOT NULL,
+                  created_at TEXT NOT NULL,
+                  updated_at TEXT NOT NULL,
+                  consumed_at TEXT
+                )
+                """
+            )
+            db.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_artifacts_kind_updated
+                ON artifacts(kind, updated_at)
+                """
+            )
+            db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_artifacts_status ON artifacts(status)"
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        db = sqlite3.connect(self.db_path)
+        db.row_factory = sqlite3.Row
+        return db
+
+
+def _artifact_from_row(row: sqlite3.Row) -> Artifact:
+    decoded = json.loads(str(row["payload_json"]))
+    if not isinstance(decoded, dict):
+        raise ValueError("Artifact payload_json must decode to an object.")
+    return Artifact(
+        id=str(row["id"]),
+        kind=str(row["kind"]),
+        schema=str(row["schema"]),
+        payload=decoded,
+        status=str(row["status"]),
+        created_at=str(row["created_at"]),
+        updated_at=str(row["updated_at"]),
+        consumed_at=row["consumed_at"],
+    )
+
+
+def _now() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()

t4l_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: t4l-server
+Version: 0.1.0
+Summary: Self-hosted REST and MCP server for T4L Trainer agent workflows.
+Project-URL: Homepage, https://github.com/BigSlikTobi/t4l-server
+Project-URL: Repository, https://github.com/BigSlikTobi/t4l-server
+Project-URL: Issues, https://github.com/BigSlikTobi/t4l-server/issues
+Author: T4L Trainer
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: mypy>=1.18; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# T4L Server
+
+Self-hosted REST and MCP server for exchanging T4L Trainer JSON artifacts
+between the iPhone app and a coaching agent.
+
+The phone remains the source of truth for accepted training state. The server
+stores synced context and pending agent results in SQLite so local agents,
+home-server agents, and private VPS agents can work through the same protocol.
+
+## Install
+
+```bash
+pipx install t4l-server
+t4l-server serve --data-dir ~/T4LServerData
+```
+
+The command prints the server URL, MCP URL, and API key. Enter the server URL
+and API key in the T4L Trainer Settings screen.
+
+## Agent setup
+
+Agents should read the public instruction repo first:
+
+```text
+https://github.com/BigSlikTobi/t4l-agent-instructions
+```
+
+Those instructions explain how to start or verify this server, connect through
+MCP, wait for fresh phone context, and write app-consumed results safely.
+
+## Compatibility
+
+The old command remains available for one transition cycle:
+
+```bash
+t4l-bridge serve --dir ~/CodexFitnessExchange
+```
+
+New setups should use `t4l-server serve --data-dir ~/T4LServerData`.
+
+## Safety model
+
+- REST, MCP, and compatibility file endpoints require the API key.
+- JSON artifacts are stored in `t4l.sqlite`.
+- Image blobs are stored under `blobs/`.
+- Only known exchange files and `meal_images/` are accessible through
+  compatibility endpoints.
+- Path traversal and arbitrary file access are rejected.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff format --check .
+ruff check .
+mypy
+pytest
+python -m build
+twine check dist/*
+```

t4l_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+t4l_server/__init__.py,sha256=mRMiAJD-C59M5KZW63YZAu8Yky8uvmT6U_ypkM8rZHk,105
+t4l_server/cli.py,sha256=ZT4GZm47a_cZtL3f-3PQ0SGLuo-0h4BrdYysyMBzrEk,2803
+t4l_server/mcp.py,sha256=HPBAw4f0fD9U2hpFmTVr04DIKgggq1Y4o5xGlszUGcQ,5071
+t4l_server/server.py,sha256=clJOTTPWvt0pbaB0SuudHcd9tQVkiFM7AnV2tr3Gzcw,13386
+t4l_server/store.py,sha256=hbZiy0I4srAZbVe6xucmAD7wfEACt1kabhN18KCQa4M,6548
+t4l_server-0.1.0.dist-info/METADATA,sha256=byfEdkveyXcgMS9FdARDhd0GtzvGTBqJ9oqx-SOYGsc,2777
+t4l_server-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+t4l_server-0.1.0.dist-info/entry_points.txt,sha256=93klHUaS56Uos4PaB2Vida3nRcmSIaNloAScOFZCGeA,92
+t4l_server-0.1.0.dist-info/licenses/LICENSE,sha256=QXNV7JWcWDVZL0kZ_dWGM6lfZeRgZ6HBh5HOWuwQk3w,1068
+t4l_server-0.1.0.dist-info/RECORD,,

t4l_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

t4l_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+t4l-bridge = t4l_server.cli:_bridge_main
+t4l-server = t4l_server.cli:main

t4l_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 T4L Trainer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.