Metadata-Version: 2.4
Name: w10w225
Version: 0.1.14
Summary: Local-first personal work agent
Requires-Python: >=3.12
Requires-Dist: aiohttp<4.0.0,>=3.12.0
Requires-Dist: aiosqlite<1.0.0,>=0.21.0
Requires-Dist: alembic<2.0.0,>=1.16.0
Requires-Dist: croniter<4.0.0,>=3.0.3
Requires-Dist: fastapi<1.0.0,>=0.128.0
Requires-Dist: greenlet<4.0.0,>=3.1.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: keyring<26.0.0,>=25.0.0
Requires-Dist: pydantic<3.0.0,>=2.11.0
Requires-Dist: python-socketio[client]<6.0.0,>=5.11.0
Requires-Dist: questionary<3.0.0,>=2.1.0
Requires-Dist: sqlalchemy<3.0.0,>=2.0.40
Requires-Dist: tomli-w<2.0.0,>=1.2.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.35.0
Description-Content-Type: text/markdown

# personal-work-agent

Local-first personal work agent prototype.

Quick start:

```bash
uv tool install git+https://github.com/HHC225/pwa.git
uv tool update-shell
w10w225
```

If `uv` already manages your shell `PATH`, `uv tool update-shell` is not required. If `w10w225` is not found after install, run it once and open a new terminal.

By default, the installed tool targets the production review server at `https://w10w225.uk`. For local development, override `WORKAGENT_REVIEW_BASE_URL` in your environment or local `.env`.

## After install

Use the installed `w10w225` command for all normal actions.

1. Install the local agent on their own machine with `uv tool install`.
2. Run `w10w225 installation-id` and copy the generated UUID.
3. Open `w10w225` Assistant Settings and save that value in `Local Agent Installation ID`.
4. Start the local daemon with `w10w225 serve --background`.
5. Use `/agent ...` in `w10w225`.

If the user has not installed/configured their own local agent, `/agent ...` should not route to any local runtime.

## Useful commands

- Show registration values: `w10w225 installation-id`
- Start the local daemon: `w10w225 serve --background`
- Run the setup wizard again: `w10w225 config wizard`
- Check daemon health: `w10w225 status`
- Run diagnostics: `w10w225 doctor`
- Stop the daemon: `w10w225 stop`
- Run one sync cycle: `w10w225 sync once`
- Update the installed tool: `uv tool upgrade w10w225`
- Remove the installed tool: `uv tool uninstall w10w225`

## Required Secret Match

The server and the local agent must share the same HMAC secret.

- `nk304` server env: `ASSISTANT_LOCAL_AGENT_SHARED_SECRET`
- local agent env: `WORKAGENT_REVIEW_SHARED_SECRET`

Those two values must be identical.

## Transport Model

`w10w225` and the local agent now use:

- outbound Socket.IO / WebSocket as the primary transport
- HTTP polling and HTTP ack/result as fallback when the socket is unavailable

The local agent never requires an inbound public port. It opens the connection to `w10w225` itself.

Docs:

- `docs/install.md` shows the standard `uv tool install` / upgrade / uninstall flow.
- `docs/examples/config.toml` shows a local sample config file.
- `docs/bootstrap/quick-start.md` shows the source-checkout bootstrap entrypoint and doctor flow.
- `docs/bootstrap/contract.md` defines the supported matrix, statuses, privilege boundaries, and shell profile handoff.
- `docs/bootstrap/macos.md`, `docs/bootstrap/linux.md`, and `docs/bootstrap/wsl.md` cover platform-specific notes.
- `docs/bootstrap/unsupported.md` explains unsupported source-bootstrap environments and where bootstrap logs/receipts live.
- `docs/bootstrap/troubleshooting.md` covers source-bootstrap rerun/recovery, bootstrap boundaries, and first-run handoff.
- `docs/operations/uv-distribution-release.md` tracks the temporary Git-source install contract and the later published-package release contract.
- `docs/operations/mvp1-local-recovery.md` covers local backup and recovery steps.
- `docs/operations/mvp2-memory-repair.md` covers local memory export/compact/integrity steps.
- `docs/operations/mvp2-w10w225bot.md` covers `w10w225bot` service user requirements.
