# Spaces: Collaborative Agent Workspace Service

## PURPOSE
The episode names **Spaces** as one of the DevDay launches: "Spaces gives your dot a place to actually write its thoughts and a place for you to collaborate with your dot. He has everything in a space right now that he's preparing for us, and we're just going to look at the space, follow the steps, and see what happens." It also describes **Codex Cloud** as "your own environment that you and your team can fully set up and customize so that you can close your laptop." This project is the persistence and integration layer behind that idea: a SQLAlchemy-backed workspace service where an agent appends timestamped *thoughts* to a space's timeline, humans drop notes beside them, and every write is mirrored to a long-running "dot" through an authenticated **httpx** client.

## WHY THIS MATTERS
A shared space is only useful if both parties trust it. That means append-only ordering, an event log you can replay, attribution of every entry to agent or human, and a sync path that survives the tab being closed. Students meet the real questions: who owns the write, what happens on a failed sync, and how do you avoid the agent and the human overwriting each other.

## HOW TO BUILD
1. `pip install -r requirements.txt` (SQLAlchemy, httpx, pydantic, python-dotenv).
2. Declare three models in one SQLite file: `Space`, `Entry` (`actor`, `kind`, `body`, `seq`), `Team` — with `Entry.space_id` as a foreign key and `seq` a monotonic per-space counter.
3. Write repository helpers: `open_space`, `append`, `timeline`, `since`.
4. Add `DotSyncClient` using `httpx.Client` with a bearer token from `DOT_TOKEN`; POST to `/dot/spaces/{id}/sync` and inspect the response.
5. Keep a `pending_sync` flag so an offline write is retried, not lost.

Key snippet — the sync seam with the retry flag:

```python
def push(self, entry: Entry) -> bool:
    try:
        r = self.client.post(f"/dot/spaces/{entry.space_id}/sync",
                             json={"seq": entry.seq, "actor": entry.actor,
                                   "kind": entry.kind, "body": entry.body},
                             timeout=5.0)
        r.raise_for_status()
        return True
    except httpx.HTTPError:      # # TODO: backoff + dead-letter queue in prod
        return False
```

## WHEN TO USE IN PRODUCTION
Use this pattern for shared agent workspaces, audit-replayable copilot memory, or any place where a background agent and a team edit the same artifact over hours. It is also the right home for "consult your existing side projects before starting another" — a queryable index of past work. **Do not** use SQLite for concurrent production writers across hosts; move to Postgres. Do not use polling sync at high volume — use webhooks or a message queue.

## HOW IT HELPS STUDENTS
Students learn SQLAlchemy ORM modelling and session lifecycle, atomic sequence allocation, JSON APIs over httpx with auth and timeouts, and failure handling for background integrations — the full path from schema to synced service.

## STARTER CODE
See `starter/main.py`: models, repository helpers, the httpx sync client with a deterministic offline fallback, and `# TODO` markers for real dot auth and retry.
