feat: add organization sessions mode for Devin self-serve usage tracking

Add `DEVIN_MODE` configuration supporting `enterprise` (default) and `organization_sessions` modes. Organization sessions mode uses `/v3/organizations/{org_id}/sessions` API with `ViewOrgSessions` permission, suitable for non-Enterprise organizations. Sums session ACUs consumed within configurable rolling window (1-365 days via `DEVIN_SESSION_WINDOW_DAYS`). Mode does not show quota, percentage, credit, or reset fields as these are unav

README.md

@@ -60,8 +60,10 @@ Copy `.env.example` to `.env`. Unknown environment variables are ignored and nam
 | `DEVIN_ENABLED` | `true` | Enable Devin |
 | `DEVIN_API_KEY` | empty | Devin Bearer token, kept as a secret value |
 | `DEVIN_API_URL` | `https://api.devin.ai` | Devin API base URL |
-| `DEVIN_ORG_ID` | empty | Organization scope, used when no user scope is configured |
-| `DEVIN_USER_ID` | empty | User scope, takes precedence over organization |
+| `DEVIN_MODE` | `enterprise` | `enterprise` billing consumption or `organization_sessions` rolling session usage |
+| `DEVIN_ORG_ID` | empty | Organization scope, required by organization sessions mode |
+| `DEVIN_USER_ID` | empty | Enterprise user scope; optional user filter in organization sessions mode |
+| `DEVIN_SESSION_WINDOW_DAYS` | `30` | Rolling organization-session window from 1 to 365 days |
 | `DEVIN_TIMEOUT` | `8` | Devin HTTP timeout in seconds |
 | `PROVIDER_CACHE_TTL` | `8` | Successful provider cache duration in seconds |
 | `REFRESH_INTERVAL` | `10` | Browser refresh period in seconds |
@@ -82,9 +84,22 @@ The app-server interface is official, but is documented as a development/debug i
 
 ### Devin
 
-The provider uses the official Devin API v3 Enterprise consumption endpoints. It selects the active cycle from `/v3/enterprise/consumption/cycles`, then requests daily consumption using user scope, organization scope, or the account endpoint in that precedence order. User and organization IDs are URL-quoted. Organization usage additionally attempts the organization max cycle ACU limit; an unavailable optional organization-details request does not discard consumption.
+The provider has two official Devin modes. `enterprise` uses the API v3 Enterprise consumption endpoints: it selects the active billing cycle from `/v3/enterprise/consumption/cycles`, then requests daily consumption using user scope, organization scope, or the account endpoint in that precedence order. It can show true billing-cycle usage and limits when available. Enterprise consumption requires a service user with `ViewAccountConsumption`; reading the organization max limit may require extra organization-read permissions.
 
-Devin v3 consumption is Enterprise-only and requires a service user with `ViewAccountConsumption`. Reading the organization max limit may require extra organization-read permissions. Self-serve has no supported machine-readable provider endpoint; use demo mode until Devin publishes an official endpoint. Do not claim real-time freshness beyond vendor behavior: the dashboard cache and refresh schedule only control when it asks the vendors again.
+`organization_sessions` uses `GET /v3/organizations/{org_id}/sessions` with a `cog_` service-user key, `DEVIN_ORG_ID`, and the `ViewOrgSessions` permission. It is suitable for non-Enterprise/self-serve organizations when that endpoint is permitted. The mode sums each returned session's cumulative `acus_consumed` for sessions whose `created_at` falls inside the rolling N-day query. It is not billing-cycle usage, does not apportion a long session's ACUs by date, and cannot show self-serve quota remaining, credit balance, percentage, or reset because Devin does not expose those values through this API. The endpoint's `created_after` filter defines which sessions are included.
+
+Example setup:
+
+```env
+DEVIN_ENABLED=true
+DEVIN_MODE=organization_sessions
+DEVIN_API_KEY=cog_your_service_user_key
+DEVIN_ORG_ID=org-your-id
+DEVIN_USER_ID=
+DEVIN_SESSION_WINDOW_DAYS=30
+```
+
+A successful `200` response from `/v3/organizations/{org_id}/sessions?first=1` confirms that the organization-session endpoint is permitted for the configured service user. Do not claim real-time freshness beyond vendor behavior: the dashboard cache and refresh schedule only control when it asks the vendors again.
 
 ## Security and behavior
 
@@ -190,8 +205,9 @@ A window-manager session may instead run `/opt/usage-kiosk/start-kiosk.sh` from
 ## Troubleshooting
 
 - **Codex error:** verify `codex` is installed, `codex login` completed, and `CODEX_COMMAND` points to one executable. Run the CLI manually outside the dashboard to confirm its availability.
-- **Devin error:** verify Enterprise entitlement, service-user permissions, token scope, API URL, and configured user or organization scope. A 401/403/404 on optional organization metadata only removes the max-limit fields.
-- **No Devin limit:** the consumption endpoint remains valid, but no numeric limit is invented when the organization max limit is unavailable.
+- **Devin Enterprise error:** verify Enterprise entitlement, service-user `ViewAccountConsumption` permission, token scope, API URL, and configured user or organization scope. A 401/403/404 on optional organization metadata only removes the max-limit fields.
+- **Devin organization sessions 403:** verify that `DEVIN_MODE=organization_sessions`, `DEVIN_ORG_ID`, the `cog_` service-user key, and `ViewOrgSessions` are correct. Confirm access with `/v3/organizations/{org_id}/sessions?first=1`; this mode does not use Enterprise consumption permissions.
+- **No Devin limit:** Enterprise consumption remains valid, but no numeric limit is invented when the organization max limit is unavailable. Organization sessions mode intentionally has no quota, percentage, credit, or reset fields.
 - **Connection error in the header:** the browser could not complete the dashboard request; existing provider rows remain on screen and retries continue on the configured interval.
 - **Stale-looking values:** successful provider results are cached for `PROVIDER_CACHE_TTL`; vendor processing and reporting delays are outside this dashboard's control.
 - **Container health failure:** inspect `docker compose logs dashboard`, verify `.env`, and test `http://localhost:8080/health`.