agents-relay 1.0.0 → 1.0.2

package/docs/github-app-rate-limit.md

@@ -1,124 +0,0 @@
-# GitHub App Authentication and API Consumption
-
-Agents Relay can authenticate GitHub API traffic with a GitHub App installation instead of consuming the interactive user account quota. This document also records the API-consumption changes that make webhook-driven reconciliation the normal path.
-
-## Goals
-
-- Separate automation API traffic from the developer's interactive GitHub identity.
-- Cache GitHub App installation tokens instead of minting one per request.
-- Apply the same rate-limit cooldown to REST and GraphQL calls.
-- Stop periodic dashboard refreshes from causing workspace-wide GitHub scans.
-- Keep webhook wakes targeted to a repository and pull request.
-- Retain a low-frequency watchdog and startup reconciliation for missed events/restarts.
-- Preserve existing `gh` authentication when GitHub App settings are not configured.
-
-## Authentication flow
-
-```mermaid
-sequenceDiagram
-    participant R as Agents Relay
-    participant K as App private key
-    participant G as GitHub App API
-    participant I as Installation API
-    R->>K: read configured PEM key
-    R->>R: create RS256 JWT
-    R->>I: POST installation access token
-    I-->>R: installation token + expiry
-    R->>R: cache token until near expiry
-    R->>G: REST / GraphQL using installation token
-    Note over R,G: existing gh login remains fallback when App auth is absent
-```
-
-The JWT uses a 60-second backdated `iat` and an expiry nine minutes in the future. Installation tokens are cached and refreshed only when fewer than five minutes remain. No private key or token is written to durable PR state.
-
-## Configuration
-
-All three GitHub App settings are required together. They can be provided as CLI flags or environment variables. CLI flags take precedence.
-
-| CLI flag | Environment variable | Meaning |
-| --- | --- | --- |
-| `--github-app-id` | `AGENTS_RELAY_GITHUB_APP_ID` | GitHub App ID |
-| `--github-app-installation-id` | `AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID` | Installation ID for the account/repositories |
-| `--github-app-private-key-file` | `AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE` | Local PEM private-key path |
-| `--trusted-authors` | `AGENTS_RELAY_TRUSTED_AUTHORS` | Extra trusted marker authors |
-
-Example:
-
-```bash
-export AGENTS_RELAY_GITHUB_APP_ID=123456
-export AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID=7890123
-export AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE=$HOME/.config/agents-relay/github-app.pem
-npx agents-relayd --workspace ~/Workspace
-```
-
-When App auth is enabled, Agents Relay trusts both the App bot identity and the current local `gh` user (when one exists). This keeps existing durable markers readable during migration from user auth to App auth.
-
-## Rate-limit behavior
-
-REST and GraphQL now share one cooldown circuit. A rate-limit/secondary-limit/HTTP 429 failure activates exponential cooldown (one minute initially, capped at fifteen minutes). While cooldown is active, workspace refresh/reconciliation uses cached state rather than continuing to spend requests.
-
-```mermaid
-flowchart TD
-    A[GitHub request] --> B{Cooldown active?}
-    B -->|yes| C[Return cached/degraded state]
-    B -->|no| D[REST or GraphQL request]
-    D --> E{Rate-limit failure?}
-    E -->|yes| F[Increase cooldown]
-    F --> C
-    E -->|no| G[Reset failure backoff]
-    G --> H[Persist/serve fresh state]
-```
-
-## Webhook-first consumption model
-
-The workspace daemon previously had several independent paths that could trigger broad GitHub reads: the five-minute watchdog, dashboard `/api/jobs` refreshes, startup discovery, and webhook reconciliation. The new flow keeps broad discovery exceptional.
-
-```mermaid
-flowchart LR
-    S[Daemon startup] --> A[One workspace discovery]
-    A --> B[Reconcile discovered state directly]
-    W[GitHub webhook] --> T[Target exact repository + PR]
-    T --> R[Targeted reconciliation]
-    R --> C[Update durable state]
-    D[Dashboard auto refresh] --> K[Read local cache]
-    M[Manual Jobs refresh] --> A
-    F[30-minute webhook watchdog] --> A
-```
-
-Key changes:
-
-- Startup discovery is reused directly for startup reconciliation, avoiding a second immediate workspace scan.
-- Dashboard automatic refresh reads the in-process/disk cache. Only an explicit Jobs refresh asks for a broad refresh.
-- Selected-job refresh remains targeted to that job's pull request.
-- Webhook mode uses a 30-minute watchdog by default instead of five minutes; `--interval` still overrides it.
-- Without webhook configuration, the existing five-minute watchdog remains for compatibility.
-- Full discovery queries every open PR but only the 20 most recently updated closed PRs; it no longer paginates the complete closed PR history.
-
-## Discovery query shape
-
-```mermaid
-flowchart TD
-    Q[Repository discovery] --> O[OPEN PR connection]
-    O -->|paginate until complete| OM[Managed open jobs]
-    Q --> C[20 most recent CLOSED PRs]
-    C --> CM[Recent terminal jobs]
-    OM --> D[Dashboard/reconciliation set]
-    CM --> D
-```
-
-This keeps all active managed jobs discoverable while bounding historical reads needed for dashboard history and missed terminal lifecycle recovery. Webhooks remain the primary path for immediate merge/close transitions.
-
-## Failure and migration behavior
-
-- Partial App configuration fails fast; Agents Relay will not silently mix identities.
-- If App authentication is not configured, existing local `gh` authentication is unchanged.
-- If GitHub becomes rate limited, dashboard data remains available from cache and the daemon stops broad retries until cooldown expires.
-- The private key is read locally and used only to sign App JWTs. Durable GitHub comments never contain the key, JWT, or installation token.
-
-## Validation
-
-Coverage includes App-config validation, RS256 JWT signature/claims, existing fixed/auth fallback behavior, dashboard manual-vs-cached refresh wiring, startup reconciliation reuse without a second workspace scan, targeted webhook reconciliation, and open-PR pagination with bounded closed history. Run the full suite with:
-
-```bash
-npm test
-```

package/docs/service.md

@@ -1,43 +0,0 @@
-# Running the service
-
-`agents-relayd` starts the repository worker pool, event-driven reconciler, periodic recovery watchdog, and dashboard. With no `--pr`/`--id`, it discovers Git repositories under `~/Workspace` (or `--workspace PATH`), maps GitHub `origin` remotes to repositories, and watches all discovered repositories together. It listens on `127.0.0.1:8787` by default. With a GitHub webhook configured, targeted webhook reconciliation is primary and the broad recovery watchdog runs every 30 minutes by default; without a webhook, the compatibility watchdog remains 5 minutes. Dashboard auto-refresh and periodic SSE snapshots use cached workspace state instead of broad GitHub reads. Explicit Jobs refresh performs broad discovery, while selected-job refresh is targeted to one pull request.
-
-The dashboard reads a bounded window (one day by default, or `--usage-window-days`) of local Codex JSONL session telemetry at `/api/usage`. Requests recorded with GLM models are shown as Z.ai runtime usage; account quota and remaining balance are marked unavailable unless a supported source is added.
-
-```sh
-npx agents-relayd --repo OWNER/REPO
-```
-
-Workspace mode (the default):
-
-```sh
-npx agents-relayd --workspace ~/Workspace
-```
-
-Use `--repo OWNER/REPO` to retain the single-repository worker pool. Legacy single-job daemon mode remains available with `--repo OWNER/REPO --pr NUMBER --id JOB_ID`.
-
-Use service overrides as needed:
-
-```sh
-npx agents-relayd --repo OWNER/REPO \
-  --port 8787 --interval 1800000 --refresh-ms 300000 \
-  --events nats --nats-url nats://127.0.0.1:4222
-```
-
-For an installed package, launch through the package binary rather than a checkout path:
-
-```sh
-npx --package agents-relay agents-relayd --repo OWNER/REPO
-```
-
-With PM2:
-
-```sh
-npx --package agents-relay --package pm2 pm2 start agents-relayd --name agents-relayd -- \
-  --repo OWNER/REPO \
-  --events nats --nats-url nats://127.0.0.1:4222
-```
-
-PM2 forwards `SIGINT` and `SIGTERM`. The service clears its watchdog, unsubscribes from wake events, closes the local dashboard server, and exits only after cleanup.
-
-GitHub App installation authentication and the webhook/cache consumption model are documented in [github-app-rate-limit.md](github-app-rate-limit.md).

package/pack.json

@@ -1,326 +0,0 @@
-[
-  {
-    "id": "agents-relay@1.0.0",
-    "name": "agents-relay",
-    "version": "1.0.0",
-    "size": 139459,
-    "unpackedSize": 558932,
-    "shasum": "5226a077ca94674bad5c7ceb2755d2dee30a4a16",
-    "integrity": "sha512-EV0VBLgoqprIeDjTm+cW/0sefNFLGoPMSFYluWknICMaUOV6uxXiR6E/WJRuP+mTkXc9XmcmBeJbnSQtGtZbcQ==",
-    "filename": "agents-relay-1.0.0.tgz",
-    "files": [
-      {
-        "path": ".github/workflows/publish.yml",
-        "size": 3469,
-        "mode": 420
-      },
-      {
-        "path": "AGENTS.md",
-        "size": 955,
-        "mode": 420
-      },
-      {
-        "path": "LICENSE",
-        "size": 1065,
-        "mode": 420
-      },
-      {
-        "path": "README.md",
-        "size": 8465,
-        "mode": 420
-      },
-      {
-        "path": "dist/adapters.js",
-        "size": 13461,
-        "mode": 420
-      },
-      {
-        "path": "dist/cli.js",
-        "size": 26305,
-        "mode": 493
-      },
-      {
-        "path": "dist/continuation.js",
-        "size": 1476,
-        "mode": 420
-      },
-      {
-        "path": "dist/dashboard.js",
-        "size": 39154,
-        "mode": 420
-      },
-      {
-        "path": "dist/events.js",
-        "size": 2789,
-        "mode": 420
-      },
-      {
-        "path": "dist/github-auth.js",
-        "size": 1746,
-        "mode": 420
-      },
-      {
-        "path": "dist/github-webhook.js",
-        "size": 2038,
-        "mode": 420
-      },
-      {
-        "path": "dist/markers.js",
-        "size": 1996,
-        "mode": 420
-      },
-      {
-        "path": "dist/planner.js",
-        "size": 8790,
-        "mode": 420
-      },
-      {
-        "path": "dist/pool.js",
-        "size": 5469,
-        "mode": 420
-      },
-      {
-        "path": "dist/reconciler.js",
-        "size": 25047,
-        "mode": 420
-      },
-      {
-        "path": "dist/registry.js",
-        "size": 1800,
-        "mode": 420
-      },
-      {
-        "path": "dist/relayd.js",
-        "size": 10056,
-        "mode": 493
-      },
-      {
-        "path": "dist/scheduler.js",
-        "size": 2869,
-        "mode": 420
-      },
-      {
-        "path": "dist/store.js",
-        "size": 30955,
-        "mode": 420
-      },
-      {
-        "path": "dist/types.js",
-        "size": 1043,
-        "mode": 420
-      },
-      {
-        "path": "dist/usage.js",
-        "size": 16829,
-        "mode": 420
-      },
-      {
-        "path": "dist/workspace.js",
-        "size": 2684,
-        "mode": 420
-      },
-      {
-        "path": "docs/agent-network.md",
-        "size": 2556,
-        "mode": 420
-      },
-      {
-        "path": "docs/architecture.md",
-        "size": 7632,
-        "mode": 420
-      },
-      {
-        "path": "docs/autonomous-objective-jobs.md",
-        "size": 5702,
-        "mode": 420
-      },
-      {
-        "path": "docs/example.md",
-        "size": 1413,
-        "mode": 420
-      },
-      {
-        "path": "docs/github-app-rate-limit.md",
-        "size": 6030,
-        "mode": 420
-      },
-      {
-        "path": "docs/service.md",
-        "size": 2255,
-        "mode": 420
-      },
-      {
-        "path": "pack.json",
-        "size": 0,
-        "mode": 420
-      },
-      {
-        "path": "package.json",
-        "size": 562,
-        "mode": 420
-      },
-      {
-        "path": "scripts/npm-version.mjs",
-        "size": 420,
-        "mode": 493
-      },
-      {
-        "path": "skills/agents-relay/agents/planner.agent.md",
-        "size": 1265,
-        "mode": 420
-      },
-      {
-        "path": "skills/agents-relay/SKILL.md",
-        "size": 6747,
-        "mode": 420
-      },
-      {
-        "path": "src/adapters.ts",
-        "size": 13759,
-        "mode": 420
-      },
-      {
-        "path": "src/cli.ts",
-        "size": 27102,
-        "mode": 420
-      },
-      {
-        "path": "src/continuation.ts",
-        "size": 1842,
-        "mode": 420
-      },
-      {
-        "path": "src/dashboard.ts",
-        "size": 38466,
-        "mode": 420
-      },
-      {
-        "path": "src/events.ts",
-        "size": 3820,
-        "mode": 420
-      },
-      {
-        "path": "src/github-auth.ts",
-        "size": 2083,
-        "mode": 420
-      },
-      {
-        "path": "src/github-webhook.ts",
-        "size": 2353,
-        "mode": 420
-      },
-      {
-        "path": "src/markers.ts",
-        "size": 2145,
-        "mode": 420
-      },
-      {
-        "path": "src/planner.ts",
-        "size": 9322,
-        "mode": 420
-      },
-      {
-        "path": "src/pool.ts",
-        "size": 5653,
-        "mode": 420
-      },
-      {
-        "path": "src/reconciler.ts",
-        "size": 23541,
-        "mode": 420
-      },
-      {
-        "path": "src/registry.ts",
-        "size": 2288,
-        "mode": 420
-      },
-      {
-        "path": "src/relayd.ts",
-        "size": 9864,
-        "mode": 493
-      },
-      {
-        "path": "src/scheduler.ts",
-        "size": 2877,
-        "mode": 420
-      },
-      {
-        "path": "src/store.ts",
-        "size": 33718,
-        "mode": 420
-      },
-      {
-        "path": "src/types.ts",
-        "size": 4184,
-        "mode": 420
-      },
-      {
-        "path": "src/usage.ts",
-        "size": 17314,
-        "mode": 420
-      },
-      {
-        "path": "src/workspace.ts",
-        "size": 2734,
-        "mode": 420
-      },
-      {
-        "path": "test/adapters.test.js",
-        "size": 12940,
-        "mode": 420
-      },
-      {
-        "path": "test/autonomous.test.js",
-        "size": 8417,
-        "mode": 420
-      },
-      {
-        "path": "test/core.test.js",
-        "size": 37282,
-        "mode": 420
-      },
-      {
-        "path": "test/dashboard.test.js",
-        "size": 9291,
-        "mode": 420
-      },
-      {
-        "path": "test/github-auth.test.js",
-        "size": 2848,
-        "mode": 420
-      },
-      {
-        "path": "test/github-webhook.test.js",
-        "size": 1341,
-        "mode": 420
-      },
-      {
-        "path": "test/service.test.js",
-        "size": 6766,
-        "mode": 420
-      },
-      {
-        "path": "test/store.test.js",
-        "size": 22991,
-        "mode": 420
-      },
-      {
-        "path": "test/usage.test.js",
-        "size": 4797,
-        "mode": 420
-      },
-      {
-        "path": "test/workspace.test.js",
-        "size": 5871,
-        "mode": 420
-      },
-      {
-        "path": "tsconfig.json",
-        "size": 280,
-        "mode": 420
-      }
-    ],
-    "entryCount": 62,
-    "bundled": []
-  }
-]

package/scripts/npm-version.mjs

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-export function nextPatchVersion(current) {
-  if (!current) return '1.0.0';
-  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(current.trim());
-  if (!match) throw new Error(`Unsupported npm version: ${current}`);
-  return `${match[1]}.${match[2]}.${Number(match[3]) + 1}`;
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  process.stdout.write(`${nextPatchVersion(process.argv[2] ?? '')}\n`);
-}