agents-relay 1.0.0

package/docs/autonomous-objective-jobs.md

@@ -0,0 +1,121 @@
+# Autonomous Objective-Driven Jobs
+
+This document records the design, implementation flow, recovery semantics, and validation of autonomous objective-driven jobs in Agents Relay.
+
+## Objective
+
+Existing jobs remain `fixed` by default. An `autonomous` job may grow its own durable task tree until the objective is satisfied. Planning is represented by real tasks rather than hidden generations or a second state store. GitHub-backed durable state remains authoritative.
+
+## Design principles
+
+- `executionMode` is explicitly `fixed` or `autonomous`; legacy jobs deserialize as `fixed`.
+- A planner is a real durable task (`kind: planner`) in the same parent/subtask hierarchy as execution work.
+- Reconciliation owns liveness: it decides when another planner is required, including after daemon restart or a missed wake-up.
+- The planner owns reasoning: it returns `objective_status`, an assessment, and typed `next_tasks`.
+- The default planner is the installable `skills/agents-relay/agents/planner.agent.md` agent contract shipped with the npm package; runtime command configuration is only an override.
+- `in_progress` creates durable child work; `satisfied` stops growth but does not bypass normal completion gates.
+- Failed or blocked work prevents autonomous completion and prevents blindly creating another planning round.
+- Planner and generated task creation are idempotent so repeated reconciliation does not duplicate work.
+
+## Autonomous lifecycle
+
+```mermaid
+flowchart TD
+    A[Job created] --> B{executionMode}
+    B -->|fixed| C[Existing fixed-job scheduler]
+    B -->|autonomous| D[Reconciliation]
+    D --> E{Runnable execution work?}
+    E -->|yes| F[Run durable tasks]
+    F --> D
+    E -->|no| G{Failed or blocked work?}
+    G -->|yes| H[Remain open for recovery]
+    G -->|no| I{Active planner?}
+    I -->|yes| J[Wait for planner outcome]
+    I -->|no| K[Create durable planner task]
+    K --> L[Run planner]
+    L --> M{objective_status}
+    M -->|in_progress| N[Create typed child tasks]
+    N --> D
+    M -->|satisfied| O[Existing completion gates]
+    O -->|pass| P[Eligible for normal completion]
+    O -->|fail| H
+```
+
+## Durable hierarchy
+
+Planning causality is visible directly in the existing task tree. No wave/generation abstraction is introduced.
+
+```mermaid
+graph TD
+    J[Autonomous Job] --> P1[planner-1]
+    P1 --> T1[implementation task]
+    P1 --> T2[test task]
+    P1 --> P2[planner-2]
+    P2 --> T3[remediation task]
+    P2 --> P3[planner-3: satisfied]
+```
+
+Each planner result is persisted with its assessment and generated work. Stable generated task IDs plus durable append semantics make replay safe.
+
+## Reconciliation and restart recovery
+
+The daemon does not depend on a planner remembering to schedule its successor. Reconciliation reconstructs the next action from durable state.
+
+```mermaid
+sequenceDiagram
+    participant W as Webhook/Startup/Watchdog
+    participant R as Reconciler
+    participant S as Durable Store
+    participant P as Planner
+    participant X as Worker
+    W->>R: wake/reconcile
+    R->>S: load job + task tree
+    alt lost or expired execution lease
+        R->>S: reclaim to READY or terminal failure
+    end
+    alt autonomous subtree settled
+        R->>S: append planner task idempotently
+        R->>P: execute planner
+        P-->>R: in_progress + next_tasks
+        R->>S: persist planner result + child tasks
+        R->>X: launch READY child work
+    else objective satisfied
+        R->>S: persist satisfied planner result
+        R->>R: apply normal completion gates
+    end
+```
+
+A restarted daemon can reclaim a durable planner lease owned by the previous runtime. Repeated reconciliation observes existing planner/task markers instead of creating duplicate work.
+
+## Completion semantics
+
+Planner satisfaction is evidence about the objective, not authority to close the job. The existing job lifecycle remains authoritative. An autonomous job can stop growing only after a planner reports `satisfied`; it can complete only when the normal completion conditions also allow it. Failed or blocked tasks remain visible and prevent accidental success.
+
+## Compatibility and surfaces
+
+Fixed jobs retain their previous scheduling behavior. Execution mode and planner state are serialized in durable markers, exposed through CLI/status data, and surfaced in the dashboard. Legacy markers without an execution mode are interpreted as `fixed`.
+
+## Implementation sequence
+
+```mermaid
+flowchart LR
+    A[Add durable execution mode] --> B[Add planner result/task model]
+    B --> C[Integrate planner with reconciler]
+    C --> D[Add idempotent child creation]
+    D --> E[Add restart recovery]
+    E --> F[Expose CLI/status/dashboard]
+    F --> G[Update documentation]
+    G --> H[Build + full test suite]
+```
+
+## Validation
+
+The completed branch was validated with `npm test`, which runs the TypeScript build before the Node test suite. Final result on 2026-09-19:
+
+- TypeScript build: passed.
+- Tests: **108 passed, 0 failed, 0 skipped/cancelled**.
+- Focused coverage includes marker round-trip and legacy defaults, fixed-job compatibility, autonomous task-tree growth, stable/idempotent generated task IDs, restart planner-lease recovery, objective satisfaction, and failed/blocked completion gates.
+
+## Follow-up
+
+GitHub API quota exhaustion prevented managed PR bootstrap during this implementation. The feature was therefore completed and validated on `feat/autonomous-objective-jobs`; managed PR/job bootstrap can be retried after quota recovery. The next P0 work is intentionally separate: GitHub App authentication and reducing residual GitHub API consumption while retaining webhook-driven targeted reconciliation.

package/docs/example.md

@@ -0,0 +1,30 @@
+# Local dogfood
+
+```sh
+npx agents-relay init --file /tmp/agents-relay.json --id dogfood --title "Local dogfood"
+npx agents-relay submit --file /tmp/agents-relay.json --task-id build --input "echo build" --adapter shell
+npx agents-relay reconcile --file /tmp/agents-relay.json
+npx agents-relay status --file /tmp/agents-relay.json
+```
+
+Autonomous local jobs use the same file and task tree. The mode is durable and
+defaults to fixed:
+
+```sh
+npx agents-relay init --file /tmp/agents-relay-auto.json --id auto --title "Objective" --mode autonomous
+npx agents-relay reconcile --file /tmp/agents-relay-auto.json --planner-command ./planner.sh
+npx agents-relay status --file /tmp/agents-relay-auto.json
+```
+
+`planner.sh` reads the current objective/task snapshot from stdin and prints a
+typed planner result. Its `next_tasks` IDs must remain stable across retries.
+
+For a nested task, submit `--parent build --deps build`; reconciliation releases it only after `build` succeeds.
+
+The same flow against the dogfood PR is:
+
+```sh
+npx agents-relay init --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302 --title "Dogfood"
+npx agents-relay submit --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302 --task-id safe-shell --input "printf dogfood" --adapter shell --capabilities shell
+npx agents-relay reconcile --repo lalalic/agents-relay --pr 1 --id agents-relay-dev-20260918-1302
+```

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

@@ -0,0 +1,124 @@
+# 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

@@ -0,0 +1,43 @@
+# 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

@@ -0,0 +1,326 @@
+[
+  {
+    "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/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "agents-relay",
+  "version": "1.0.0",
+  "description": "Durable async agent jobs coordinated through GitHub pull requests",
+  "type": "module",
+  "bin": { "agents-relay": "dist/cli.js", "agents-relayd": "dist/relayd.js" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js dist/relayd.js",
+    "test": "npm run build && node --test test/*.test.js",
+    "dev": "tsx src/cli.ts"
+  },
+  "devDependencies": { "@types/node": "^22.10.2", "tsx": "^4.19.2", "typescript": "^5.7.2" },
+  "optionalDependencies": { "nats": "^2.29.0" }
+}

package/scripts/npm-version.mjs

@@ -0,0 +1,11 @@
+#!/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`);
+}