@elizaos/plugin-github 2.0.0-beta.1 → 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @elizaos/plugin-github
+
+GitHub integration for elizaOS agents. Enables agents to manage pull requests, issues, and notifications using the GitHub REST API via Octokit.
+
+## What it does
+
+- **List pull requests** — open/closed/all for a specific repo or across accessible repos, with optional author filter.
+- **Review pull requests** — submit approve, request-changes, or comment reviews (requires confirmation).
+- **Issue management** — create, assign, close, reopen, comment on, or label issues (all write ops require confirmation).
+- **Notification triage** — fetch unread GitHub notifications and return them ranked by priority score (reason, subject type, repo freshness). Read-only, no confirmation needed.
+- **PAT management** — REST endpoints for storing/removing a GitHub Personal Access Token from local disk (`<state-dir>/credentials/github.json`).
+
+## Enabling the plugin
+
+Add `"@elizaos/plugin-github"` to the agent's `plugins` array in its character file or runtime configuration. The plugin is opt-in.
+
+## Required configuration
+
+At least one GitHub token must be configured. The plugin supports two roles:
+
+- **`user`** — acts on behalf of the human (used for reviews and notifications by default).
+- **`agent`** — acts on behalf of the Eliza agent (used for issue and PR ops by default).
+
+### Multi-account (recommended)
+
+Set `GITHUB_ACCOUNTS` to a JSON array:
+
+```json
+[
+  { "accountId": "user", "role": "user", "token": "ghp_..." },
+  { "accountId": "agent", "role": "agent", "token": "ghp_..." }
+]
+```
+
+### Legacy single-account
+
+| Env var | Role |
+|---|---|
+| `GITHUB_USER_PAT` | user |
+| `GITHUB_AGENT_PAT` | agent |
+
+### OAuth (optional)
+
+To enable OAuth-app flows through the connector account manager, also set:
+
+- `GITHUB_OAUTH_CLIENT_ID`
+- `GITHUB_OAUTH_CLIENT_SECRET`
+- `GITHUB_OAUTH_REDIRECT_URI`
+
+## Actions
+
+The plugin exposes one umbrella action `GITHUB` that dispatches to sub-operations via an `action` parameter:
+
+| `action` value | What it does |
+|---|---|
+| `pr_list` | List pull requests |
+| `pr_review` | Submit a PR review (requires `review_action`: approve / request-changes / comment) |
+| `issue_create` | Create a new issue (`title` required) |
+| `issue_assign` | Assign users to an issue |
+| `issue_close` | Close an issue |
+| `issue_reopen` | Reopen a closed issue |
+| `issue_comment` | Add a comment to an issue |
+| `issue_label` | Apply labels to an issue |
+| `notification_triage` | Fetch and rank unread notifications |
+
+All write operations require confirmation before they execute.
+
+## HTTP routes
+
+The plugin registers three routes on the agent's server for PAT management:
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/github/token` | Returns connection status (token never exposed) |
+| `POST` | `/api/github/token` | Save a PAT (validated against GitHub `/user` before save) |
+| `DELETE` | `/api/github/token` | Remove the saved PAT |
+
+## Development
+
+```bash
+bun run --cwd plugins/plugin-github build
+bun run --cwd plugins/plugin-github test
+bun run --cwd plugins/plugin-github typecheck
+```
+
+See [CLAUDE.md](CLAUDE.md) for agent-facing layout and extension guide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-github",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.2",
   "description": "GitHub integration plugin for elizaOS agents — PRs, issues, notifications via the GitHub REST API",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,24 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
@@ -18,23 +34,24 @@
   "scripts": {
     "build": "tsup src/index.ts src/register-routes.ts --format esm --dts --clean",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "clean": "rm -rf dist .turbo"
   },
   "dependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.3-beta.2",
     "@octokit/rest": "^22.0.0"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1"
+    "@elizaos/core": "2.0.3-beta.2"
   },
   "devDependencies": {
     "@types/node": "24.12.2",
     "tsup": "8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "4.1.5"
+    "vitest": "4.1.9"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
 }

package/dist/chunk-KU2MGW2W.js

@@ -1,6 +0,0 @@
-// src/register-routes.ts
-import { registerAppRoutePluginLoader } from "@elizaos/core";
-registerAppRoutePluginLoader("@elizaos/plugin-github", async () => {
-  const { githubPlugin } = await import("./index.js");
-  return githubPlugin;
-});

package/dist/index.d.ts

@@ -1,294 +0,0 @@
-import { Action, IAgentRuntime, ConnectorAccountProvider, Service, Plugin } from '@elizaos/core';
-import { Octokit } from '@octokit/rest';
-
-/**
- * @module issue-op
- * @description Single router action covering GitHub issue lifecycle ops:
- * create, assign, close, reopen, comment, label. Replaces the old
- * CREATE_ISSUE / ASSIGN_ISSUE actions and absorbs the issue-management ops
- * previously implemented in plugin-agent-orchestrator's MANAGE_ISSUES.
- *
- * All ops are write ops gated on `confirmed: true`.
- */
-
-declare const issueOpAction: Action;
-
-declare const githubAction: Action;
-
-/**
- * @module notification-triage
- * @description Fetches unread GitHub notifications and returns them sorted
- * by a composite priority score derived from `reason`, subject type, and
- * the notifying repo's `pushed_at` freshness.
- *
- * Read-only — no confirmation gate.
- */
-
-interface TriagedNotification {
-    id: string;
-    reason: string;
-    repo: string;
-    title: string;
-    subjectType: string;
-    url: string | null;
-    updatedAt: string;
-    score: number;
-}
-declare function scoreNotification(params: {
-    reason: string;
-    subjectType: string;
-    repoPushedAtMs: number | null;
-    nowMs: number;
-}): number;
-
-declare const notificationTriageAction: Action;
-
-/**
- * @module pr-op
- * @description Single router action covering GitHub pull request ops:
- * list and review.
- */
-
-declare const prOpAction: Action;
-
-/**
- * @module types
- * @description Shared types for the GitHub plugin
- */
-
-type OctokitEndpoint<T, Data> = T extends (...args: infer Args) => unknown ? (...args: Args) => Promise<{
-    data: Data;
-}> : never;
-/**
- * Identifies which configured token (user-acting or agent-acting) an action
- * should execute under. The plugin loads two independent PATs so the user
- * and agent personas can act separately on the same repo.
- */
-type GitHubIdentity = "user" | "agent";
-type GitHubUserSummary = {
-    login?: string | null;
-};
-type GitHubPullRequestSummary = {
-    number: number;
-    title: string;
-    state: string;
-    html_url: string;
-    user?: GitHubUserSummary | null;
-};
-type GitHubSearchIssueSummary = {
-    repository_url: string;
-    number: number;
-    title: string;
-    state: string;
-    html_url: string;
-    user?: GitHubUserSummary | null;
-};
-type GitHubReviewResult = {
-    id: number;
-};
-type GitHubIssueResult = {
-    number: number;
-    html_url: string;
-};
-type GitHubAssigneesResult = {
-    assignees?: Array<GitHubUserSummary | null> | null;
-};
-type GitHubLabelSummary = string | {
-    name?: string | null;
-};
-type GitHubIssueDetail = {
-    number: number;
-    title: string;
-    state: string;
-    html_url: string;
-    body?: string | null;
-    labels?: Array<GitHubLabelSummary | null> | null;
-    user?: GitHubUserSummary | null;
-};
-type GitHubIssueCommentResult = {
-    id: number;
-    html_url: string;
-};
-type GitHubAddLabelsResult = Array<GitHubLabelSummary | null>;
-type GitHubNotificationSummary = {
-    id: string;
-    reason?: string | null;
-    repository?: {
-        full_name?: string | null;
-        pushed_at?: string | null;
-    };
-    subject?: {
-        title?: string | null;
-        type?: string | null;
-        url?: string | null;
-    };
-    updated_at: string;
-};
-/**
- * Narrow Octokit surface used by this plugin's actions. Keeping the service
- * contract structural makes tests and local API mocks straightforward without
- * depending on the full Octokit class shape.
- */
-interface GitHubOctokitClient {
-    activity: {
-        listNotificationsForAuthenticatedUser: OctokitEndpoint<Octokit["activity"]["listNotificationsForAuthenticatedUser"], GitHubNotificationSummary[]>;
-    };
-    issues: {
-        addAssignees: OctokitEndpoint<Octokit["issues"]["addAssignees"], GitHubAssigneesResult>;
-        addLabels: OctokitEndpoint<Octokit["issues"]["addLabels"], GitHubAddLabelsResult>;
-        create: OctokitEndpoint<Octokit["issues"]["create"], GitHubIssueResult>;
-        createComment: OctokitEndpoint<Octokit["issues"]["createComment"], GitHubIssueCommentResult>;
-        get: OctokitEndpoint<Octokit["issues"]["get"], GitHubIssueDetail>;
-        listForRepo: OctokitEndpoint<Octokit["issues"]["listForRepo"], GitHubIssueDetail[]>;
-        update: OctokitEndpoint<Octokit["issues"]["update"], GitHubIssueDetail>;
-    };
-    pulls: {
-        createReview: OctokitEndpoint<Octokit["pulls"]["createReview"], GitHubReviewResult>;
-        list: OctokitEndpoint<Octokit["pulls"]["list"], GitHubPullRequestSummary[]>;
-    };
-    search: {
-        issuesAndPullRequests: OctokitEndpoint<Octokit["search"]["issuesAndPullRequests"], {
-            items: GitHubSearchIssueSummary[];
-        }>;
-    };
-}
-/**
- * Service contract exposed to actions. Actions resolve their Octokit client
- * via this interface and never read environment variables directly.
- */
-interface IGitHubService {
-    getOctokit(selector: GitHubIdentity | {
-        as?: GitHubIdentity;
-        role?: GitHubIdentity;
-        accountId?: string;
-    }): GitHubOctokitClient | null;
-}
-declare const GITHUB_SERVICE_TYPE = "github";
-declare const GitHubActions: {
-    readonly GITHUB_ISSUE_OP: "GITHUB_ISSUE";
-    readonly GITHUB_PR_OP: "GITHUB_PR";
-    readonly GITHUB_NOTIFICATION_TRIAGE: "GITHUB_NOTIFICATION_TRIAGE";
-};
-/** Issue ops accepted by GITHUB_ISSUE_OP. */
-type GitHubIssueOp = "create" | "assign" | "close" | "reopen" | "comment" | "label";
-/** PR ops accepted by GITHUB_PR_OP. */
-type GitHubPrOp = "list" | "review";
-/**
- * Structured result returned by action handlers. Actions never throw —
- * recoverable problems are surfaced as `{ success: false }` with a reason,
- * and destructive actions surface a confirmation request distinctly.
- */
-type GitHubActionResult<T = unknown> = {
-    success: true;
-    data: T;
-} | {
-    success: false;
-    error: string;
-} | {
-    success: false;
-    requiresConfirmation: true;
-    preview: string;
-};
-interface RateLimitError {
-    kind: "rate-limit";
-    resetAtMs: number | null;
-    message: string;
-}
-/** Parameters shared by every action invocation. */
-interface BaseActionOptions {
-    as?: GitHubIdentity;
-    accountId?: string;
-    confirmed?: boolean;
-}
-
-declare const DEFAULT_GITHUB_USER_ACCOUNT_ID = "user";
-declare const DEFAULT_GITHUB_AGENT_ACCOUNT_ID = "agent";
-interface GitHubAccountConfig {
-    accountId: string;
-    role: GitHubIdentity;
-    token: string;
-    label?: string;
-}
-interface GitHubAccountSelection {
-    accountId?: string;
-    role: GitHubIdentity;
-}
-declare function defaultGitHubAccountIdForRole(role: GitHubIdentity): string;
-declare function normalizeGitHubAccountId(value: unknown): string | undefined;
-declare function resolveGitHubAccountSelection(options: Record<string, unknown> | undefined, defaultRole: GitHubIdentity): GitHubAccountSelection;
-declare function readGitHubAccounts(runtime: IAgentRuntime): GitHubAccountConfig[];
-declare function readGitHubAccountsWithConnectorCredentials(runtime: IAgentRuntime): Promise<GitHubAccountConfig[]>;
-declare function resolveGitHubAccount(accounts: readonly GitHubAccountConfig[], selection: GitHubAccountSelection): GitHubAccountConfig | null;
-
-/**
- * GitHub ConnectorAccountManager provider.
- *
- * Bridges plugin-github to the @elizaos/core ConnectorAccountManager so the
- * generic HTTP CRUD + OAuth surface can list, create, patch, delete, and run
- * the OAuth flow for GitHub accounts. PATs remain supported as a legacy code
- * path; OAuth-app installations are exposed via startOAuth/completeOAuth.
- *
- * Account model:
- *   - role "OWNER" — the user persona acting on their own behalf (legacy GITHUB_USER_PAT)
- *   - role "AGENT" — the agent persona acting on its own behalf (legacy GITHUB_AGENT_PAT)
- * accountKey = GitHub username (login).
- */
-
-/**
- * Build the GitHub ConnectorAccountManager provider.
- */
-declare function createGitHubConnectorAccountProvider(runtime: IAgentRuntime): ConnectorAccountProvider;
-
-/**
- * @module github-service
- * @description Service that owns GitHub REST clients for the plugin.
- *
- * Role-tagged account records are supported, with the legacy user/agent PAT
- * split preserved as the default account set. Actions request an Octokit
- * client by role and optionally by accountId; the service returns `null` when
- * the requested account has no token configured.
- */
-
-declare class GitHubService extends Service implements IGitHubService {
-    private readonly createClient;
-    static serviceType: string;
-    capabilityDescription: string;
-    private clients;
-    constructor(runtime?: IAgentRuntime, createClient?: (auth: string) => GitHubOctokitClient);
-    static start(runtime: IAgentRuntime, createClient?: (auth: string) => GitHubOctokitClient): Promise<Service>;
-    private initialize;
-    getOctokit(selector: GitHubIdentity | {
-        as?: GitHubIdentity;
-        role?: GitHubIdentity;
-        accountId?: string;
-    }): GitHubOctokitClient | null;
-    /**
-     * Allows tests to inject an Octokit-shaped mock without going through
-     * environment variables. Not part of the public runtime contract.
-     */
-    setClientForTesting(as: GitHubIdentity, client: GitHubOctokitClient | null, accountId?: string): void;
-    stop(): Promise<void>;
-}
-
-/**
- * @module plugin-github
- * @description elizaOS plugin for GitHub integration.
- *
- * Actions:
- *   - GITHUB (PR, issue, and notification operations)
- *
- * Auth: role-tagged account records with legacy PAT fallback.
- *   - GITHUB_ACCOUNTS   — JSON account records ({accountId, role, token})
- *   - GITHUB_USER_PAT   — legacy user acting on their own behalf
- *   - GITHUB_AGENT_PAT  — legacy agent acting on its own behalf
- *   E2E fallbacks: ELIZA_E2E_GITHUB_USER_PAT / ELIZA_E2E_GITHUB_AGENT_PAT.
- *
- * Each action takes an `as: "user" | "agent"` option and may take accountId
- * to select a specific account. GITHUB_PR_OP review and
- * GITHUB_NOTIFICATION_TRIAGE default to `"user"`; the other ops default to
- * `"agent"`.
- */
-
-declare const githubPlugin: Plugin;
-
-export { type BaseActionOptions, DEFAULT_GITHUB_AGENT_ACCOUNT_ID, DEFAULT_GITHUB_USER_ACCOUNT_ID, GITHUB_SERVICE_TYPE, type GitHubAccountConfig, type GitHubAccountSelection, type GitHubActionResult, GitHubActions, type GitHubIdentity, type GitHubIssueOp, type GitHubOctokitClient, type GitHubPrOp, GitHubService, type IGitHubService, type RateLimitError, type TriagedNotification, createGitHubConnectorAccountProvider, githubPlugin as default, defaultGitHubAccountIdForRole, githubAction, githubPlugin, issueOpAction, normalizeGitHubAccountId, notificationTriageAction, prOpAction, readGitHubAccounts, readGitHubAccountsWithConnectorCredentials, resolveGitHubAccount, resolveGitHubAccountSelection, scoreNotification };