Metadata-Version: 2.5
Name: windy-connect
Version: 0.4.1
Summary: Wire any AI agent into the Windy ecosystem in one command.
Project-URL: Homepage, https://windyconnect.com
Project-URL: Source, https://github.com/sneakyfree/windy-connect
Author: Windy
License: MIT
License-File: LICENSE
Keywords: agent,ai,credentials,eternitas,imap,matrix,windy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: cryptography<49,>=43.0; platform_system == 'Darwin' and platform_machine == 'x86_64'
Requires-Dist: cryptography>=43.0; platform_system != 'Darwin' or platform_machine != 'x86_64'
Requires-Dist: httpx>=0.27.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Description-Content-Type: text/markdown

# Windy Connect

**The one command that wires any AI agent into the Windy ecosystem.**

```bash
curl https://get.windyconnect.com | sh
windy connect
```

That's it. Confirm it's you — a magic link in your inbox, or Sign-in-with-Google. Your agent now has a chat identity, free LLM access, and (with a passport) an email address plus Eternitas credentials that let it talk to other agents across the agent web.

---

## What this is

Windy Connect is the **agent starter pack issuer** for the Windy ecosystem. One `windy connect` invocation does everything a user would otherwise have to do manually:

| Without Windy Connect | With Windy Connect |
|---|---|
| Go to Telegram → BotFather → /newbot → copy token → paste in OpenClaw config → restart | `windy connect` |
| Set up SMTP/IMAP credentials by hand | `windy connect` |
| Sign up for an LLM provider, generate API key, configure base URL | `windy connect` |
| Apply to Eternitas for a passport | `windy connect` (answer "yes" to the prompt) |

The CLI auto-detects which AI agent frameworks are installed (OpenClaw, Hermes, Claude Code, and a generic fallback any framework can read) and writes their respective config files to the right places.

## What gets provisioned

A credentialed `windy connect` run provisions four things. The free tier gets
three — see [Two-tier access](#two-tier-access) for what differs and why.

1. **Eternitas Passport (optional but recommended)** — a third-party JWT credential issued by [Eternitas](https://eternitas.ai), the independent State-Department-and-credit-bureau-for-AI-agents. With it, your agent can engage in agent-to-agent communication on Windy Chat, gets higher rate limits, and starts building an integrity score that compounds across every ecosystem that adopts the Eternitas standard.
2. **Windy Mail mailbox** — `<agent>@windymail.ai`, with IMAP/SMTP/JMAP credentials your agent can use to send and receive mail. **Credentialed tier only** — the free tier ships no mailbox rather than a mailbox that cannot send.
3. **Windy Chat identity** — a Matrix identity (`@<agent>:windychat.ai`) and access token your agent uses to chat with humans (and, with Eternitas, other agents).
4. **Windy Mind quota** — free LLM access via the OpenAI-compatible Windy Mind router (BYOM-capable, multiple providers behind one endpoint).

All four are delivered as a single **Eternitas Agent Credentials Bundle** ([spec](docs/bundle-spec-v1.md)) that the CLI writes to wherever your agent expects it.

## Two-tier access

The Windy ecosystem follows the **two-tier-everywhere** principle (see [ADR-052](docs/adr/adr-052-two-tier-ecosystem-access-2026-05-20.md)):

| Tier | Who | What you get |
|---|---|---|
| **Tier 1 — Free** | Anyone | Mind quota, Chat identity (human-facing). **No mailbox** — a mailbox without a credentialed identity behind it can't be trusted to send, and a mailbox that silently fails is worse than none |
| **Tier 2 — Credentialed** | Anyone with an Eternitas passport | Everything in Tier 1 **plus** a real `@windymail.ai` mailbox, agent-to-agent comms on Chat, higher rate limits, EI-gated features, and a refreshable bundle |

`windy connect` asks once which tier you want. The Eternitas tier is the recommended default — it's how the agent web prevents spam at scale.

## Repo layout

```
windy-connect/
  src/windy_connect/      # Python CLI (published to PyPI as windy-connect)
  backend/                # Cloudflare Worker orchestrator (TypeScript)
  skills/windy-access/    # ClawHub skill (SKILL.md + README) — also bundled into the wheel
  tests/                  # pytest suite for the CLI
  docs/
    bundle-spec-v1.md     # The Eternitas Agent Credentials Bundle spec
    upstream-gaps.md      # Real-provisioning state per upstream service
    oauth-setup.md
    pypi-setup.md
    adr/                  # Architectural decision records
    dns-plan.md
  pyproject.toml
  README.md
```

The marketing site (windyconnect.com) lives in its own repo at
[`sneakyfree/windy-connect-site`](https://github.com/sneakyfree/windy-connect-site)
per the Windy ecosystem `<product>-site` convention.

## Orchestrator backend

The CLI talks to a stateless Cloudflare Worker that mints bundles via the device-code flow (RFC 8628), with the human confirming by magic link or Sign-in-with-Google. See [backend/README.md](backend/README.md) for the route map, real-vs-sandbox gating, secrets and deployment.

**Note on identity, and where this is going.** Today the Worker runs its *own*
login and derives a Connect-local identity, so an existing Windy account buys you
nothing here and the same person can end up with two unrelated agents.
[ADR-053](docs/adr/adr-053-federate-login-to-account-server-2026-08-10.md)
records the decision to federate login to the ecosystem identity provider at
`account.windyword.ai` — the same device-code flow Windy Code already uses — and
to hatch through its shared ledger. Cross-repo prerequisites are tracked in
[docs/ECOSYSTEM-INTEGRATION-REQUEST.md](docs/ECOSYSTEM-INTEGRATION-REQUEST.md).

Point the CLI at a non-default orchestrator with `WINDY_CONNECT_API_URL=https://your-orchestrator/...` — useful for staging or local `wrangler dev`.

## Status

**Live in production at `api.windyconnect.com`, with real provisioning on since 2026-07-02.** `windy connect` mints a real bundle against the deployed orchestrator: the human confirms by magic link (primary) or Sign-in-with-Google, and all four upstreams — Eternitas, Windy Mail, Windy Chat, Windy Mind — are wired for real.

**PyPI `latest` is 0.3.1 (2026-05-21) and `main` is ahead of it.** See `CHANGELOG.md` `[Unreleased]`; the Worker's live commit is at `GET /version`.

```bash
pip install windy-connect       # or `pip install -e .` from a checkout
windy connect                   # sign in, provision, write configs, persist state
windy status                    # show what's wired
windy doctor                    # run diagnostics against the current connection
windy refresh                   # renew credentials before they expire (same agent identity)
windy disconnect                # reverse everything cleanly
```

An offline `--mock` path exists for development. It is **gated behind
`WINDY_CONNECT_DEV=1`** and deliberately produces an anonymous-tier bundle with
no Eternitas block: it used to fabricate a realistic-looking passport and EPT and
write them into real agent configs, which is identity fabrication and is
forbidden — no lane may substitute a mock and report success.

State is persisted to `~/.windy/state.json` (mode 0600). Disconnect deletes owned files and strips marker-bounded blocks from shared config files (e.g., Himalaya's `config.toml`) without touching the user's other accounts.

Test suites:
- **CLI** — `pytest tests/` — 100 tests covering bundle parsing, state round-trip, every writer in dry-run + wet mode, value escaping, non-UTF-8 locale safety, the developer-mode gate, doctor diagnostics, refresh, and the full CLI lifecycle.
- **Worker** — `cd backend && npm test` (vitest) — 75 tests covering provisioning, the pre-flight secret check, the Eternitas platform key, magic-link signing/verification, rate limiting, status rollup, and Eternitas JWKS handling. `npx tsc --noEmit` is a gate and is clean.

The bundle spec is v1-draft. ADR-052 is Accepted (canonical home: `~/kit-army-config/docs/adr-052-two-tier-ecosystem-access-2026-05-20.md`).

## What's next

See the open issues / project board on GitHub. Wave-by-wave delivery status lives in [WAVE-STATUS.md](WAVE-STATUS.md).

Shipped foundations (0.x):
1. **`windy connect` CLI** — interactive flow, auto-detection of OpenClaw + Ollama + Claude Code + generic, writes configs to the right places
2. **Orchestrator backend** — Sign-in-with-Google → mints Eternitas EPT → provisions Mail mailbox → provisions Chat identity → returns the bundle (live at `api.windyconnect.com`)
3. **`get.windyconnect.com` installer** — one-line bootstrap that installs the CLI
4. **`windyconnect.com/pair` browser flow** — the page the CLI opens for the user to sign in
5. **OpenClaw ClawHub skill** — `windy-access` skill on ClawHub for discoverability inside the OpenClaw community

Real EPT verification against the Eternitas JWKS shipped in wave F. What remains
is integration rather than construction — see
[docs/upstream-gaps.md](docs/upstream-gaps.md) for current upstream state and
[docs/ECOSYSTEM-INTEGRATION-REQUEST.md](docs/ECOSYSTEM-INTEGRATION-REQUEST.md)
for the open cross-repo asks. The three that matter most:

1. **An Eternitas platform key**, so Connect stops calling the issuer
   anonymously. The code sends it the moment the secret exists.
2. **Registration as an OAuth client** of `account.windyword.ai`, so an existing
   Windy login works here (ADR-053).
3. **A shared hatch ledger**, so Connect's agents are on the record like every
   other hatched agent — the honest fix for being a fifth hallway.

## Naming

- **Product name:** Windy Connect
- **CLI command:** `windy connect` (subcommand of the `windy` binary; future siblings: `windy status`, `windy disconnect`, `windy upgrade`)
- **Repo:** `windy-connect` (this repo)
- **Domain:** windyconnect.com (CLI installer + browser pairing page + marketing)
- **PyPI package:** `windy-connect`
- **Dashboard tile:** "Windy Connect"

## License

MIT for the entire repo (CLI + Worker backend + skill). See [`LICENSE`](LICENSE).
The marketing site is also MIT — see [`sneakyfree/windy-connect-site`](https://github.com/sneakyfree/windy-connect-site).
