@zhin.js/adapter-github 3.0.2 → 4.0.0

package/README.md

@@ -1,19 +1,14 @@
 # @zhin.js/adapter-github
 
-把 GitHub 当聊天通道 — Issue/PR 评论区即群聊，通过 GitHub App 认证，纯 REST API 对接，零 CLI 依赖。
-
-查询 · 管理 · 通知 · OAuth 用户绑定 四合一。
+GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub App 认证，Webhook 入站经 `httpHostToken`。
 
 ## 功能特性
 
-- ✅ **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
-- ✅ **仓库管理**：PR 合并/创建/Review/关闭、Issue 创建/关闭/评论
-- ✅ **信息查询**：Star、Branch、Release、CI Workflow 等
-- ✅ **事件通知**：Webhook 订阅，跨平台推送到任意聊天
-- ✅ **GitHub App 认证**：JWT → Installation Token，自动刷新
-- ✅ **OAuth 用户绑定**：用户可绑定自己的 GitHub 账号，star/fork 以个人身份执行
-- ✅ **Bot 开发工作流**：托管 git 工作区 + App 身份 push/开 PR（HITL 确认）
-- ✅ **无 router 也能运行**：核心功能不依赖 HTTP 服务，有 router 时自动注册 Webhook 和 OAuth 路由
+- **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
+- **Webhook 入站**：HMAC-SHA256 验签 → `messageGatewayToken`
+- **出站**：`send({ target, payload })` → Issue/PR comment（target 为 channel ID）
+- **GitHub App 认证**：JWT → Installation Token
+- **Agent 工具**：`agent/` 下 star/bind/subscribe/workspace 等保留
 
 ## 安装
 
@@ -21,67 +16,52 @@
 pnpm add @zhin.js/adapter-github
 ```
 
-## 依赖
-
-- `@zhin.js/host-router`（可选）— 提供 Webhook 路由，用于接收 GitHub 事件推送
-
-## GitHub App 创建
-
-1. 访问 [GitHub Developer Settings](https://github.com/settings/apps)
-2. 点击 **New GitHub App**
-3. 填写基本信息：
-   - **App name**: 你的 bot 名称
-   - **Homepage URL**: 任意
-   - **Webhook URL**: `http://your-server:port/pub/github/webhook`（有 HTTP 服务时）
-   - **Webhook secret**: 自定义密钥
-4. 权限设置（Permissions）：
-   - **Repository → Issues**: Read & Write
-   - **Repository → Pull requests**: Read & Write
-   - **Repository → Contents**: Read & Write（Bot 提交代码）
-   - **Repository → Metadata**: Read
-   - **Repository → Actions**: Read（查看 CI）
-5. 订阅事件（Subscribe to events）：
-   - Issue comment、Pull request、Pull request review、Pull request review comment
-   - Push、Star、Fork（用于通知）
-6. 创建后记录 **App ID**，点击 **Generate a private key** 下载 `.pem` 文件
-7. 安装 App 到目标仓库/组织
-
-## 配置
+Webhook 需要 Root 提供 `@zhin.js/host-http`（`zhin runtime start` 默认装配）。
+
+## 配置（Plugin Runtime）
 
 ```yaml
 # zhin.config.yml
-endpoints:
-  - context: github
-    name: my-github-bot
-    app_id: 123456
-    private_key: ./data/github-app.pem   # PEM 文件路径或直接粘贴内容
-    webhook_secret: your-secret          # 可选；配置后启用 Webhook
-    webhook_path: /pub/github/webhook    # 可选
-    auto_reply_repos:                    # 可选：这些 repo 的评论自动触发 AI
-      - zhinjs/zhin
-    workspace_root: ./data/github-workspaces  # 可选：Bot git 工作区
-
 plugins:
-  - database
-  - "@zhin.js/adapter-github"
-  - "@zhin.js/host-router"                # Webhook 需要
+  github:
+    webhook_path: /github/webhook
+    auto_reply_repos:
+      - zhinjs/zhin
+    workspace_root: ./data/github-workspaces
+    endpoints:
+      - name: my-github-bot
+        app_id: 123456
+        private_key: ./data/github-app.pem
+        webhook_secret: your-secret
 ```
 
 ```env
 GITHUB_APP_ID=123456
 GITHUB_WEBHOOK_SECRET=your-secret
-# MCP server-github（可选；PAT = 人身份，默认关闭）
-# ai.githubMcp.enabled: true
-# GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
 ```
 
-`private_key` 支持两种写法：
-- 文件路径：`./data/github-app.pem`
-- 直接内容：`"-----BEGIN RSA PRIVATE KEY-----\n..."`
+`private_key` 支持文件路径或 PEM 内容。未配置 `webhook_secret` 时仅 API 出站 / agent 工具可用（无入站）。
 
-## Channel ID 格式
+多 App：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
 
-GitHub adapter 将 Issue/PR 映射为聊天频道：
+```yaml
+plugins:
+  github:
+    endpoints:
+      - name: app-a
+        app_id: 123456
+        private_key: ./data/app-a.pem
+      - name: app-b
+        app_id: 234567
+        private_key: ./data/app-b.pem
+```
+
+## 已移除的配置
+
+- **`ai.githubMcp.enabled` / `ai.githubMcp.token`**：Plugin Runtime 迁移后 `register-github-mcp`（stdio `@modelcontextprotocol/server-github`，PAT 人身份）已移除，该配置不再生效。如需 MCP 工具，请按新运行时 `mcp/<name>.ts`（`@zhin.js/mcp-feature`）约定自行装配。
+- **`poll_interval`**：轮询降级已删除，仅 webhook 入站；该字段目前解析但不生效（deferred）。
+
+## Channel ID
 
 | 类型 | Channel ID | 示例 |
 |------|-----------|------|
@@ -90,151 +70,23 @@ GitHub adapter 将 Issue/PR 映射为聊天频道：
 
 ## AI 工具
 
-### 适配器内置（Zhin 专有）
-
-| 工具 | 说明 |
-|------|------|
-| `github_star` | Star / Unstar / 检查（per-user OAuth 或 Endpoint 默认） |
-| `github_bind` / `github_unbind` / `github_whoami` | 用户 GitHub 账号绑定 |
-| `github_install` | GitHub App 安装链接 |
-| `github_subscribe` / `github_unsubscribe` / `github_subscriptions` | 频道级 Webhook 订阅 |
-| `github_prepare_workspace` | Clone/fetch 托管工作区并 checkout 分支 |
-| `github_patch_file` | Contents API 单文件更新（Bot 身份） |
-| `github_push_branch` | git commit + push（**需 HITL**） |
-| `github_create_pr` | 创建 PR（**需 HITL**） |
-
-### Bot 工作流（App 身份）
-
-- 评论回复：Webhook → `$reply`，Installation Token，UI 显示 `{slug}[bot]` + **Bot** 徽章
-- 开发提交：`github_prepare_workspace` → bash 改代码 → `github_push_branch`（确认）→ Issue 场景 `github_create_pr`
-- PR 线程：push 到现有 PR head 分支，不新开 PR
-- 工作区默认：`data/github-workspaces/{owner}/{repo}`
-
-### MCP（`@modelcontextprotocol/server-github`，可选）
-
-仅当 `ai.githubMcp.enabled: true` 且配置 PAT 时注册。`mcp_github_*` 以**用户 PAT** 操作，**不能**作为 Bot 写仓库。Bot 写操作请用上方 `github_*` 工具。
-
-### 使用示例
-
-```
-AI: 列出 zhinjs/zhin 的 PR
-AI: 合并 zhinjs/zhin 的 PR #108
-AI: 查看 zhinjs/zhin 的 star 数
-AI: 订阅 zhinjs/zhin 的 push 和 pr 事件
-AI: 搜索 zhinjs 相关的仓库
-AI: 给 zhinjs/zhin 的 issue #42 加上 bug 标签
-AI: 查看 zhinjs/zhin 的 README.md 文件
-AI: 对比 zhinjs/zhin 的 main 和 dev 分支
-AI: 编辑 zhinjs/zhin 的 issue #42 标题
-AI: 绑定我的 GitHub 账号
-AI: star zhinjs/zhin
-AI: fork zhinjs/zhin   # 使用 mcp_github_fork_repository
-```
-
-## Webhook 事件通知
-
-配置好 Webhook 后，支持以下事件的跨平台推送：
-
-| 事件 | 参数 | 说明 |
-|------|------|------|
-| Push | `push` | 代码推送 |
-| Issue | `issue` | Issue 创建/更新/关闭 |
-| Star | `star` | 仓库被 star |
-| Unstar | `unstar` | 仓库被 unstar |
-| Fork | `fork` | 仓库被 fork |
-| Pull Request | `pr` / `pull_request` | PR 创建/更新/合并 |
-
-### Webhook 端点
+见 `agent/tools/`：`github_star`、`github_bind`、`github_subscribe`、`github_prepare_workspace` 等。
 
-```
-POST /pub/github/webhook
-```
-
-Headers:
-- `X-GitHub-Event`: 事件类型
-- `X-Hub-Signature-256`: 签名（配置了 secret 时）
-
-## OAuth 用户绑定（Device Flow）
-
-用户通过工具 **`github_bind`** 绑定 GitHub 账号（[OAuth Device Flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)），**不是**浏览器 OAuth 回调页面。
-
-### 认证策略
-
-| 操作类型 | 使用的 Token | 原因 |
-|---------|------------|------|
-| 读取 issue/PR/repo 信息 | App JWT | 不涉及用户身份 |
-| 评论（bot 发言） | App Installation Token | 以 `{slug}[bot]` 机器人身份发言 |
-| push / 开 PR | App Installation Token + git author | UI **Bot** 徽章（非 Member） |
-| star / unstar | User OAuth | 个人行为 |
-| fork | User OAuth | 个人行为 |
-
-### 绑定流程
-
-1. 用户在聊天中触发 `github_bind`（或说「绑定 GitHub」）
-2. Endpoint 返回 **verification URI** 与 **user code**（GitHub Device Flow）
-3. 用户在浏览器打开链接并输入 code 完成授权
-4. Token 写入 `github_oauth_users` 表；可用 `github_whoami` / `github_unbind` 管理
-
-**Client ID**：从 GitHub App 的 `/app` API 自动获取（`GhClient.getClientId()`），**无需**在 Endpoint 配置里写 `client_id` / `client_secret`。
-
-### 前置条件
-
-- 需要 **`database`** 插件（`github_oauth_users` 模型）
-- Device Flow 在 IM 内完成，**不依赖** `/pub/github/oauth` HTTP 路由
-
-## 数据库表
+## 架构
 
-### github_subscriptions
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| repo | text | 仓库名 (owner/repo) |
-| events | json | 订阅的事件列表 |
-| target_id | text | 目标频道 ID |
-| target_type | text | 类型 (private/group/channel) |
-| adapter | text | 适配器名称 |
-| endpoint | text | 机器人名称 |
-
-### github_events
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| repo | text | 仓库名 |
-| event_type | text | 事件类型 |
-| payload | json | 事件载荷 |
-
-### github_oauth_users
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| platform | text | 聊天平台 |
-| platform_uid | text | 平台用户 ID |
-| github_login | text | GitHub 用户名 |
-| access_token | text | Device Flow 获得的 token |
-| created_at | integer | 创建时间戳 |
-
-## 架构说明
-
-```
-adapter-github/
-├── src/
-│   ├── index.ts              # 插件入口：provide、useContext、模型表
-│   ├── adapter.ts            # GitHubAdapter
-│   ├── endpoint.ts                # GitHubEndpoint（Issue/PR 频道）
-│   ├── gh-client.ts          # GitHub REST（App JWT / Installation Token）
-│   ├── register-github-mcp.ts # orchestrator.addMcp(server-github)
-│   ├── agent-prompt.ts       # 平台 prompt / deferred 工具筛选
-│   └── types.ts              # EndpointConfig、Webhook payload、Channel ID
-├── package.json
-└── README.md
-```
-
-- **无 `@zhin.js/host-router` 时**：REST 工具与轮询仍可用，但无法注册 Webhook
-- **有 `@zhin.js/host-router` 时**：注册 Webhook；MCP 通过 `orchestrator.addMcp`（需 PAT 或 `ai.githubMcp.token`）
-
-## 许可证
+| 路径 | 职责 |
+|------|------|
+| `plugin.ts` | 插件元数据；有 DatabaseHost 时定义 `github_oauth_users` |
+| `adapters/github.ts` | 薄 `defineAdapter` 入口（发现约定） |
+| `src/endpoint.ts` | Endpoint 生命周期、出站、admit |
+| `src/webhook.ts` | HMAC 验签与事件分发 |
+| `src/oauth-users.ts` | OAuth 表 SSOT + token 查找 |
+| `src/protocol.ts` | 协议纯函数（channel / payload） |
+| `src/gh-client.ts` | GitHub API 客户端 |
+
+- 入站：`httpHostToken` POST → `messageGatewayToken.receive`
+- 出站：`send({ target, payload })`
+
+## License
 
 MIT

package/adapters/github.ts

@@ -0,0 +1,51 @@
+/**
+ * Convention entry: discover `adapters/github.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / oauth / protocol).
+ */
+import { defineAdapter, type AdapterContext } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  databaseHostToken,
+  type DatabaseHost,
+} from '@zhin.js/plugin-runtime';
+import { GithubEndpoint } from '../src/endpoint.js';
+import {
+  resolveGithubConfig,
+  type GithubAdapterConfig,
+} from '../src/protocol.js';
+
+export { GithubEndpoint } from '../src/endpoint.js';
+export type { GithubEndpointOptions } from '../src/endpoint.js';
+
+function optionalDatabase(context: AdapterContext): DatabaseHost | undefined {
+  try {
+    return context.use(databaseHostToken);
+  } catch {
+    return undefined;
+  }
+}
+
+export default defineAdapter<GithubAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    const config = resolveGithubConfig(context.config);
+    const database = optionalDatabase(context);
+    if (config.webhookSecret) {
+      return new GithubEndpoint({
+        id: context.id,
+        gateway: context.use(messageGatewayToken),
+        http: context.use(httpHostToken),
+        database,
+        config,
+      });
+    }
+    // API-only: Issue/PR send + agent tools without webhook.
+    return new GithubEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      database,
+      config,
+    });
+  },
+});

package/agent/skills/github.md

@@ -77,7 +77,7 @@ requires:
 本技能提供三种操作方式：
 - **适配器内置工具**（`github_*`）：用户交互类操作，具备账号绑定、Device Flow 授权、频道级订阅等适配器专有逻辑
 - **Bot 写仓库工具**（`github_prepare_workspace` / `github_patch_file` / `github_push_branch` / `github_create_pr`）：Installation Token，UI 显示 **Bot** 身份；push/开 PR 需 HITL
-- **MCP server-github**（`mcp_github_*`，可选）：需 `ai.githubMcp.enabled: true` + PAT，**人身份**，勿用于 Bot 写仓库
+- **MCP server-github**（`mcp_github_*`，可选）：`ai.githubMcp.*` 配置已随 Plugin Runtime 迁移移除；如需 MCP 工具，按 `mcp/<name>.ts` 约定自行装配（PAT 为**人身份**，勿用于 Bot 写仓库）
 - **bash + gh CLI**：仓库自动化操作，灵活覆盖 GitHub API 全场景
 
 ## 一、适配器内置工具
@@ -129,7 +129,7 @@ Issue 线程：新分支 → 开发 → push → 开 PR。PR 线程：push 到
 
 1. `github_star` 优先使用用户绑定的 GitHub 账号，未绑定则降级为 Endpoint 默认账号
 2. Bot 写仓库用 `github_*` 工具，不用 `mcp_github_*` 写操作
-3. MCP 仅 opt-in（`ai.githubMcp.enabled: true`），PAT 为人身份
+3. MCP（`mcp_github_*`）仅在你按 `mcp/<name>.ts` 约定装配后可用（旧 `ai.githubMcp.enabled` 已移除），PAT 为人身份
 4. 当用户想操作自己的 GitHub 账号进行 Star 时，先引导用户使用 `github_bind` 绑定
 5. Webhook 订阅关联到当前聊天通道，仅在该通道接收事件通知
 

package/agent/tools/bind.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubBind } from '../../src/github-tool-handlers.js';
 
-export default defineTool({
+export default defineAgentTool({
   description: '绑定你的 GitHub 账号 — 使用 Device Flow 授权，无需输入密码',
   inputSchema: z.object({}),
   tags: ['github'],

package/agent/tools/create_pr.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubCreatePr } from '../../src/github-bot-handlers.js';
 
-export default defineTool<{ repo?: string; title: string; body?: string; head?: string; base?: string }>({
+export default defineAgentTool<{ repo?: string; title: string; body?: string; head?: string; base?: string }>({
   description: '以 GitHub App Bot 身份创建 Pull Request（需 HITL 确认；Issue 场景常用）',
   inputSchema: z.object({
     repo: z.string().optional().describe('owner/repo'),

package/agent/tools/install.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubInstall } from '../../src/github-tool-handlers.js';
 
-export default defineTool({
+export default defineAgentTool({
   description: '获取安装 GitHub App 的链接 — 安装后 Endpoint 可以访问你的仓库，你也可以使用更多功能',
   inputSchema: z.object({}),
   tags: ['github'],

package/agent/tools/patch_file.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubPatchFile } from '../../src/github-bot-handlers.js';
 
-export default defineTool<{ repo?: string; path: string; content: string; message: string; branch?: string }>({
+export default defineAgentTool<{ repo?: string; path: string; content: string; message: string; branch?: string }>({
   description: '通过 Contents API 单文件更新（小改；Bot Installation Token 身份）',
   inputSchema: z.object({
     repo: z.string().optional().describe('owner/repo'),

package/agent/tools/prepare_workspace.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubPrepareWorkspace } from '../../src/github-bot-handlers.js';
 
-export default defineTool<{ repo?: string }>({
+export default defineAgentTool<{ repo?: string }>({
   description: 'Clone/fetch 托管工作区并 checkout 到 Issue/PR 对应分支（GitHub App Bot 身份）',
   inputSchema: z.object({
     repo: z.string().optional().describe('owner/repo，缺省从当前 Issue/PR 频道推断'),

package/agent/tools/push_branch.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubPushBranch } from '../../src/github-bot-handlers.js';
 
-export default defineTool<{ repo?: string; branch?: string; message: string }>({
+export default defineAgentTool<{ repo?: string; branch?: string; message: string }>({
   description: '在托管工作区 git commit 并 push 到远程分支（需 HITL 确认；Bot 身份）',
   inputSchema: z.object({
     repo: z.string().optional().describe('owner/repo'),

package/agent/tools/star.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubStar } from '../../src/github-tool-handlers.js';
 
-export default defineTool<{ action: 'star' | 'unstar' | 'check'; repo: string }>({
+export default defineAgentTool<{ action: 'star' | 'unstar' | 'check'; repo: string }>({
   description: 'Star 或取消 Star 一个 GitHub 仓库（使用你绑定的 GitHub 账号，未绑定则用 Endpoint 默认账号）',
   inputSchema: z.object({
     action: z.enum(['star', 'unstar', 'check']),

package/agent/tools/subscribe.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubSubscribe } from '../../src/github-tool-handlers.js';
 
-export default defineTool<{ repo: string; events?: string }>({
+export default defineAgentTool<{ repo: string; events?: string }>({
   description: '订阅 GitHub 仓库的 Webhook 事件，事件将推送到当前聊天通道',
   inputSchema: z.object({
     repo: z.string().min(1),

package/agent/tools/subscriptions.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubSubscriptions } from '../../src/github-tool-handlers.js';
 
-export default defineTool({
+export default defineAgentTool({
   description: '查看当前聊天通道的 GitHub 仓库订阅列表',
   inputSchema: z.object({}),
   platforms: ['github'],

package/agent/tools/unbind.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubUnbind } from '../../src/github-tool-handlers.js';
 
-export default defineTool({
+export default defineAgentTool({
   description: '解除你绑定的 GitHub 账号',
   inputSchema: z.object({}),
   tags: ['github'],

package/agent/tools/unsubscribe.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubUnsubscribe } from '../../src/github-tool-handlers.js';
 
-export default defineTool<{ repo: string }>({
+export default defineAgentTool<{ repo: string }>({
   description: '取消订阅 GitHub 仓库的 Webhook 事件',
   inputSchema: z.object({
     repo: z.string().min(1),

package/agent/tools/whoami.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubWhoami } from '../../src/github-tool-handlers.js';
 
-export default defineTool({
+export default defineAgentTool({
   description: '查看你绑定的 GitHub 账号信息',
   inputSchema: z.object({}),
   tags: ['github'],

package/lib/agent-prompt.d.ts

@@ -0,0 +1,2 @@
+import type { AgentPromptContributor } from 'zhin.js';
+export declare function createGithubAgentPromptContributor(): AgentPromptContributor;

package/lib/{src/agent-prompt.js → agent-prompt.js}

@@ -82,4 +82,3 @@ export function createGithubAgentPromptContributor() {
         },
     };
 }
-//# sourceMappingURL=agent-prompt.js.map

package/lib/endpoint.d.ts

@@ -0,0 +1,48 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId, DatabaseHost } from '@zhin.js/plugin-runtime';
+import { GhClient } from './gh-client.js';
+import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
+import { WorkspaceManager } from './workspace-manager.js';
+export interface GithubEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http?: HttpHost;
+    readonly database?: DatabaseHost;
+    readonly config: ResolvedGithubConfig;
+    readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
+}
+export declare class GithubEndpoint implements EndpointInstance {
+    #private;
+    readonly gh: GhClient;
+    readonly config: ResolvedGithubConfig;
+    readonly name: string;
+    constructor(options: GithubEndpointOptions);
+    getAPI(): GhClient;
+    getUserOrDefaultAPI(platform?: string, platformUid?: string): Promise<GhClient | null>;
+    getClientId(): string | null;
+    getHost(): string | undefined;
+    getAppSlug(): string | null;
+    getInstallations(): {
+        id: number;
+        account: {
+            login: string;
+            type: string;
+        };
+        target_type: string;
+    }[];
+    getWorkspaceManager(): WorkspaceManager;
+    getDatabase(): DatabaseHost | undefined;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a parsed comment when open. */
+    admit(comment: GithubInboundComment): void;
+}
+export declare function defaultCreateClient(config: ResolvedGithubConfig): GhClient;