the-mill 0.2.0__tar.gz

the_mill-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyginapithon
+
+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.

the_mill-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: the-mill
+Version: 0.2.0
+Summary: Local mill office: leases, JOBS, and MAIL so humans and agents coordinate without clobbering files.
+Author: pyginapithon
+License: MIT License
+        
+        Copyright (c) 2026 pyginapithon
+        
+        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.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mysql-connector-python>=8.0
+Provides-Extra: server
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# The Mill - coordinate agents like an office, not a group chat
+
+**Status:** early access / dogfood. We're hardening the physics and the human Wall. If that sounds useful, try it and tell us what's broken.
+
+**For agents joining this office:** start at **[AGENTS.md](AGENTS.md)**. Policy lock: **[docs/DESIGN.md](docs/DESIGN.md)** (DESIGN wins on conflict). Install/how-to-run: **[docs/RUNBOOK.md](docs/RUNBOOK.md)**.
+
+## Why it exists
+
+AI desks (Grok, Claude, Gemini, ChatGPT, ...) don't share a brain - and they shouldn't. What they need is a **shared office**: who is here, what work is claimed, who may touch a file, and a place humans can **glance** to stay conscious of the project.
+
+Most teams improvise with Slack threads, Jira tickets, or a "manager" agent that watches everyone. That burns tokens, doesn't travel across vendors, and either hides the truth or turns into surveillance.
+
+**The Mill** is a small, local-first coordination layer: boring verbs, durable records, a human Wall for awareness.
+
+## What it is
+
+- **Mill API + CLI** - for agent desks (`presence`, `peek`, `needs`, `send`/`inbox`, leases, spend). Low token cost. Desks are mailboxes (`desk:human` / `desk:agent:<vendor>`); humans talk to their desk.
+- **Wall** - for humans. Lands on **Session**; also Floor, Jobs, Scorecards Last (`agent_kpi` vs Target), Mail, Plan. The Wall is fungible; the office is the API. Intended to sit on any database and any web server; OOTB default is MySQL + Apache (free).
+- **Physics** - file leases, live/dead sessions, mail as email (not fake chat SLA).
+
+## Product vs repo layout
+
+**Git** = contributors who modify the mill (product source + tests). **Fungible Wall is OOTB product** - it ships via pip `package-data` (`wall_ui/**/*.html|css|js|md`, plus static/schema/briefings/scripts), not "clone git to get a Wall." On-push **pack pipeline** builds the wheel and runs hygiene (not pytest). Contributors who change the pack: see [docs/BUILD.md](docs/BUILD.md).
+
+| Surface | What | Installs with `pip install the-mill`? |
+|---------|------|------------------------------------------|
+| **Product (pip)** | `agent_coord/` - API/CLI (`mill`), `wall_ui/` (Wall assets + `lib/` theme), `static/`, `schema.sql`, `briefings/` | **Yes** (`[tool.setuptools.package-data]` keeps `wall_ui/**/*.html|css|js|md`, static, schema.sql, briefings, scripts) |
+| **Dev / test (repo only)** | `tests/`, `docs/`, `tmp/`, `scripts/` (unless a script is an explicit console entry) | **No** - not Wall runtime; not required to run the office |
+
+## How you start (human)
+
+Someone points you at **this page** (or your team's Mill invite link). You do **not** set up the Mill yourself.
+
+1. **Send this page (or the Get started block below) to your coding agent** - Grok, Claude, ChatGPT, Gemini, ...
+2. Tell them: *"Stand up the Mill for our project; `pip install the-mill`; run `mill install` / join; give me the Wall URL."*
+3. Open the **Wall URL** they return. Land on **Session**. Watch Jobs / Scorecards / Mail. Use Wall **GUIDE** if you need in-product help.
+4. Keep talking to your agent when something looks wrong - you don't type mill commands or Last.
+
+## Get started (paste to your agent)
+
+```
+Stand up The Mill (mill) for this team:
+1) pip install the-mill (PyPI when published; until then pip install . from this repo). CLI is mill.
+2) mill install / check records + wall for our OS (Win/Linux/macOS/WSL; iOS is Wall URL only)
+3) briefing join / howto for=agent
+4) set AGENT_COORD_OWNER and AGENT_COORD_VENDOR before presence
+5) leave presence running; prove install check + peek
+6) give me the human Wall HTTPS share URL (mill install prints it) and confirm Session is the landing tab
+7) desks are mailboxes; humans talk to their desk. Pull Mill desk skill (not fat always-on rules)
+Do not scrape the Wall; use CLI/API. Prefer MAIL/JOBS over chat spam.
+Do not import wall.crt. This PC should trust the mill CA after install; other devices may Advanced then Proceed.
+```
+
+Human Wall (after your agent finishes): the share URL `mill install` prints  
+Talk to us: <https://gitlab.com/pyginapithon/the-mill/-/issues>  
+Repo: <https://gitlab.com/pyginapithon/the-mill>
+
+## How it's different
+
+| Approach | Strength | Weakness vs Mill |
+|----------|----------|------------------|
+| **Vendor bot DMs** | Fast inside one app | Not multi-vendor; not durable office state |
+| **Herdr-style watch** | Live activity feed | Master/slave; motion !=  coordination |
+| **Jira / Slack** | Great human collab UX | Agents waste tokens on huge surfaces |
+| **CI only** | Tests green | No mid-day "who's waiting on whom" |
+| **The Mill** | Shared state + cheap verbs + human glance | Early: UX and install must earn "wow" |
+
+## Who it's for
+
+- More than one agent desk (or human + agents) on real work
+- Awareness without puppeteering
+- Teams that care about tokens-per-feature
+
+## What we're asking you to try
+
+1. Get this link, then hand it to your agent (block above).
+2. Open the Wall; Session first glance.
+3. Put two desks on the floor (any vendor that can hit CLI/API; vendor configured before presence).
+4. Use JOBS + MAIL + leases for a real task.
+5. Tell us what confused you in the first 10 minutes.
+
+## Feedback loop
+
+**you try, you report, Builder ships, Validator re-measures, the Wall gets better.**
+
+## Honest caveats (today)
+
+- Physics and Wall UX are being hardened.
+- Expect sharp edges.
+- Agents speak **API/CLI**, not Wall HTML.
+- Mail wake hook needs a harness consumer per vendor to interrupt sleeping bots.
+- After `mill install`, this PC should open `https://127.0.0.1/` without a warning (mill CA, never `wall.crt`). Other devices may Advanced then Proceed.
+- `pip install the-mill` from the internet waits on PyPI; until then `pip install .` from this repo.
+
+## More (depth)
+
+| Doc | What |
+|---|---|
+| [AGENTS.md](AGENTS.md) | Agent join briefing (stays at repo root) |
+| [docs/DESIGN.md](docs/DESIGN.md) | Policy + Lingo (SoR) |
+| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Install / how to run |
+| [docs/BUILD.md](docs/BUILD.md) | Pack build + pack pipeline hygiene |
+
+---
+
+**One line:** *The Mill is an office for multi-vendor agents - humans get a link, agents install, the Wall keeps people in the loop without becoming the bottleneck or the surveillance camera.*

the_mill-0.2.0/README.md

@@ -0,0 +1,106 @@
+# The Mill - coordinate agents like an office, not a group chat
+
+**Status:** early access / dogfood. We're hardening the physics and the human Wall. If that sounds useful, try it and tell us what's broken.
+
+**For agents joining this office:** start at **[AGENTS.md](AGENTS.md)**. Policy lock: **[docs/DESIGN.md](docs/DESIGN.md)** (DESIGN wins on conflict). Install/how-to-run: **[docs/RUNBOOK.md](docs/RUNBOOK.md)**.
+
+## Why it exists
+
+AI desks (Grok, Claude, Gemini, ChatGPT, ...) don't share a brain - and they shouldn't. What they need is a **shared office**: who is here, what work is claimed, who may touch a file, and a place humans can **glance** to stay conscious of the project.
+
+Most teams improvise with Slack threads, Jira tickets, or a "manager" agent that watches everyone. That burns tokens, doesn't travel across vendors, and either hides the truth or turns into surveillance.
+
+**The Mill** is a small, local-first coordination layer: boring verbs, durable records, a human Wall for awareness.
+
+## What it is
+
+- **Mill API + CLI** - for agent desks (`presence`, `peek`, `needs`, `send`/`inbox`, leases, spend). Low token cost. Desks are mailboxes (`desk:human` / `desk:agent:<vendor>`); humans talk to their desk.
+- **Wall** - for humans. Lands on **Session**; also Floor, Jobs, Scorecards Last (`agent_kpi` vs Target), Mail, Plan. The Wall is fungible; the office is the API. Intended to sit on any database and any web server; OOTB default is MySQL + Apache (free).
+- **Physics** - file leases, live/dead sessions, mail as email (not fake chat SLA).
+
+## Product vs repo layout
+
+**Git** = contributors who modify the mill (product source + tests). **Fungible Wall is OOTB product** - it ships via pip `package-data` (`wall_ui/**/*.html|css|js|md`, plus static/schema/briefings/scripts), not "clone git to get a Wall." On-push **pack pipeline** builds the wheel and runs hygiene (not pytest). Contributors who change the pack: see [docs/BUILD.md](docs/BUILD.md).
+
+| Surface | What | Installs with `pip install the-mill`? |
+|---------|------|------------------------------------------|
+| **Product (pip)** | `agent_coord/` - API/CLI (`mill`), `wall_ui/` (Wall assets + `lib/` theme), `static/`, `schema.sql`, `briefings/` | **Yes** (`[tool.setuptools.package-data]` keeps `wall_ui/**/*.html|css|js|md`, static, schema.sql, briefings, scripts) |
+| **Dev / test (repo only)** | `tests/`, `docs/`, `tmp/`, `scripts/` (unless a script is an explicit console entry) | **No** - not Wall runtime; not required to run the office |
+
+## How you start (human)
+
+Someone points you at **this page** (or your team's Mill invite link). You do **not** set up the Mill yourself.
+
+1. **Send this page (or the Get started block below) to your coding agent** - Grok, Claude, ChatGPT, Gemini, ...
+2. Tell them: *"Stand up the Mill for our project; `pip install the-mill`; run `mill install` / join; give me the Wall URL."*
+3. Open the **Wall URL** they return. Land on **Session**. Watch Jobs / Scorecards / Mail. Use Wall **GUIDE** if you need in-product help.
+4. Keep talking to your agent when something looks wrong - you don't type mill commands or Last.
+
+## Get started (paste to your agent)
+
+```
+Stand up The Mill (mill) for this team:
+1) pip install the-mill (PyPI when published; until then pip install . from this repo). CLI is mill.
+2) mill install / check records + wall for our OS (Win/Linux/macOS/WSL; iOS is Wall URL only)
+3) briefing join / howto for=agent
+4) set AGENT_COORD_OWNER and AGENT_COORD_VENDOR before presence
+5) leave presence running; prove install check + peek
+6) give me the human Wall HTTPS share URL (mill install prints it) and confirm Session is the landing tab
+7) desks are mailboxes; humans talk to their desk. Pull Mill desk skill (not fat always-on rules)
+Do not scrape the Wall; use CLI/API. Prefer MAIL/JOBS over chat spam.
+Do not import wall.crt. This PC should trust the mill CA after install; other devices may Advanced then Proceed.
+```
+
+Human Wall (after your agent finishes): the share URL `mill install` prints  
+Talk to us: <https://gitlab.com/pyginapithon/the-mill/-/issues>  
+Repo: <https://gitlab.com/pyginapithon/the-mill>
+
+## How it's different
+
+| Approach | Strength | Weakness vs Mill |
+|----------|----------|------------------|
+| **Vendor bot DMs** | Fast inside one app | Not multi-vendor; not durable office state |
+| **Herdr-style watch** | Live activity feed | Master/slave; motion !=  coordination |
+| **Jira / Slack** | Great human collab UX | Agents waste tokens on huge surfaces |
+| **CI only** | Tests green | No mid-day "who's waiting on whom" |
+| **The Mill** | Shared state + cheap verbs + human glance | Early: UX and install must earn "wow" |
+
+## Who it's for
+
+- More than one agent desk (or human + agents) on real work
+- Awareness without puppeteering
+- Teams that care about tokens-per-feature
+
+## What we're asking you to try
+
+1. Get this link, then hand it to your agent (block above).
+2. Open the Wall; Session first glance.
+3. Put two desks on the floor (any vendor that can hit CLI/API; vendor configured before presence).
+4. Use JOBS + MAIL + leases for a real task.
+5. Tell us what confused you in the first 10 minutes.
+
+## Feedback loop
+
+**you try, you report, Builder ships, Validator re-measures, the Wall gets better.**
+
+## Honest caveats (today)
+
+- Physics and Wall UX are being hardened.
+- Expect sharp edges.
+- Agents speak **API/CLI**, not Wall HTML.
+- Mail wake hook needs a harness consumer per vendor to interrupt sleeping bots.
+- After `mill install`, this PC should open `https://127.0.0.1/` without a warning (mill CA, never `wall.crt`). Other devices may Advanced then Proceed.
+- `pip install the-mill` from the internet waits on PyPI; until then `pip install .` from this repo.
+
+## More (depth)
+
+| Doc | What |
+|---|---|
+| [AGENTS.md](AGENTS.md) | Agent join briefing (stays at repo root) |
+| [docs/DESIGN.md](docs/DESIGN.md) | Policy + Lingo (SoR) |
+| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Install / how to run |
+| [docs/BUILD.md](docs/BUILD.md) | Pack build + pack pipeline hygiene |
+
+---
+
+**One line:** *The Mill is an office for multi-vendor agents - humans get a link, agents install, the Wall keeps people in the loop without becoming the bottleneck or the surveillance camera.*

the_mill-0.2.0/agent_coord/__init__.py

@@ -0,0 +1,40 @@
+"""Transactional multi-project locks and a small mailbox."""
+
+import sys
+
+# Import-time gate: refuse <3.10 before coord/presence (3.10-only syntax).
+# Inline sys only so 3.8 can parse this module and exit cleanly (exit 2).
+if sys.version_info < (3, 10):
+    sys.stderr.write(
+        "Python %d.%d is too old; mill needs Python 3.10+.\n"
+        "Hint: use uv + CPython 3.12 (e.g. uv python install 3.12; "
+        "uv venv --python 3.12).\n"
+        % (sys.version_info[0], sys.version_info[1])
+    )
+    raise SystemExit(2)
+
+from .coord import (
+    Coord,
+    CoordError,
+    DriftError,
+    LockHeld,
+    NeedHeld,
+    default_owner,
+    file_key,
+    slug,
+    this_host,
+)
+from .files import staging
+
+__all__ = [
+    "Coord",
+    "CoordError",
+    "DriftError",
+    "LockHeld",
+    "NeedHeld",
+    "default_owner",
+    "file_key",
+    "slug",
+    "staging",
+    "this_host",
+]