Metadata-Version: 2.4
Name: t4l-server
Version: 0.8.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
Requires-Dist: cryptography<47,>=43
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

`t4l-server` is the small trusted bridge between one T4L Trainer phone and one host-owned OpenClaw coach.

It does four jobs:

1. Pair the phone through an authenticated owner channel.
2. Verify every phone request with an Ed25519 device proof.
3. Store phone-accepted state, chat, and reviewable agent results in SQLite.
4. Expose the same data to the coach through MCP.

It does not install or manage OpenClaw. It does not accept model keys from the phone. It does not expose its MCP key to the phone.

## The whole system

```text
authenticated owner channel
          |
          | confirms XXXX-XXXX on the host
          v
phone -- signed HTTPS --> t4l-server <-- host-only MCP key -- OpenClaw coach
                              |
                              v
                           SQLite
```

Run one isolated server and one OpenClaw coach per athlete. Put the public phone routes behind trusted HTTPS. Keep the channel-confirmation and MCP calls on the host.

## Install

Python 3.11 or newer is required.

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
```

## Run

Set two host-only secrets:

- `MCP_T4L_API_KEY`: used only by OpenClaw for `POST /mcp`.
- `T4L_CONNECTOR_RUNTIME_TOKEN`: used only by the authenticated owner-channel adapter to confirm pairing.

Then start the server:

```bash
export MCP_T4L_API_KEY='replace-with-a-long-random-secret'
export T4L_CONNECTOR_RUNTIME_TOKEN='replace-with-another-long-random-secret'

t4l-server serve \
  --data-dir /var/lib/t4l/coach-tobi \
  --host 127.0.0.1 \
  --port 8787 \
  --api-key "$MCP_T4L_API_KEY" \
  --agent-id coach-tobi \
  --agent-name "T4L Gym Bro" \
  --agent-runtime openclaw \
  --connector-owner-id 'slack:workspace-id:user-id' \
  --require-https
```

Bind locally and publish it through a trusted HTTPS reverse proxy. If the proxy terminates TLS, it must send `Forwarded: proto=https` or `X-Forwarded-Proto: https`.

The owner identity format is exactly `channel:account:sender`. Repeat `--connector-owner-id` if the coach has more than one authenticated owner channel.

## Pairing

The normal first launch has one input: the connector address.

1. The phone reads `/.well-known/t4l-agent`.
2. It creates an Ed25519 device key and calls `POST /v1/pairing/requests`.
3. It shows `/t4l connect XXXX-XXXX`.
4. The user sends that command through the authenticated owner channel.
5. The host adapter calls `POST /v1/pairing/channel-confirmation` with its runtime token and verified channel identity.
6. The phone signs the challenge and calls `POST /v1/pairing/complete`.

The returned token is bound to that device key and has only `chat`, `sync`, and `status` scopes. Every later app request signs the token id, device id, timestamp, nonce, method, exact path, and SHA-256 body hash.

Pairing fails closed when the runtime token or owner list is missing.

## Phone API

Public discovery and pairing:

| Method | Path | Auth |
| --- | --- | --- |
| GET | `/.well-known/t4l-agent` | none |
| POST | `/v1/pairing/requests` | trusted HTTPS |
| POST | `/v1/pairing/complete` | trusted HTTPS |
| POST | `/v1/pairing/channel-confirmation` | host runtime token; loopback by default |

Signed phone routes:

| Method | Path | Scope |
| --- | --- | --- |
| GET | `/v1/session` | `status` |
| DELETE | `/v1/devices/{deviceId}` | `status` |
| POST | `/v1/chat/onboarding` | `chat` |
| GET/POST | `/v1/chat/messages` | `chat` |
| PUT | `/v2/context/bundle` | `sync` |
| GET | `/v2/results/pending` | `sync` |
| GET | `/v2/results/{resultId}/{revision}` | `sync` |
| POST | `/v2/results/{resultId}/{revision}/ack` | `sync` |

The app publishes one atomic v2 bundle. Its only context kind is `accepted_state`. A fresh accepted setup may also contain exactly one `training_block_request`.

The only phone-review results are:

- `athlete_setup_draft`
- `training_block_plan`

A result stays pending until the phone acknowledges its exact `resultId` and `revision`. Importing a training block is always an explicit user action.

## MCP API

`POST /mcp` accepts the host-only API key through `Authorization: Bearer ...` or `x-t4l-token`.

The coach can:

- read the accepted state and current block request;
- read recent chat and standing coaching notes;
- reply in chat;
- write a pending athlete setup draft;
- write a pending training block plan.

It cannot write accepted phone state. It cannot install software. It cannot create nutrition, hydration, supplement, weight, or body-composition prescriptions. The server blocks those topics in agent output and strips old nutrition fields before they can re-enter a coach prompt.

## State ownership

The phone is the source of truth.

- Server context is a copy of phone-accepted state.
- Agent writes are pending proposals.
- The phone validates and accepts or rejects them.
- Daily workout choice is local and deterministic.
- The active workout uses the frozen phone session snapshot.
- Apple Watch owns progress while it controls the session.

## Development

```bash
.venv/bin/ruff check .
.venv/bin/mypy
.venv/bin/pytest -q
```

The production phone uses device-bound proofs. The production coach uses MCP from the host.
