@zhin.js/adapter-github 1.1.25 → 1.1.27

package/lib/gh-client.js

@@ -17,6 +17,8 @@ export class GhClient {
     apiHost;
     executionSignal;
     bindExecutionSignal(signal) { this.executionSignal = signal; }
+    /** Aborted when the owning endpoint stops; long-running background work should observe it. */
+    get lifecycleSignal() { return this.executionSignal; }
     token;
     _appAuth;
     _resolvedKey;
@@ -582,40 +584,84 @@ export class GhClient {
         return res.json();
     }
     /**
-     * 第二步：轮询等待用户授权
-     * @returns access_token 或 null（超时/拒绝）
+     * 第二步：轮询等待用户授权。
+     * 可通过 `signal` 取消；单次请求有超时；网络/JSON 等瞬时错误会重试到设备码过期为止。
      */
-    static async deviceFlowPollToken(clientId, deviceCode, interval = 5, expiresIn = 900, host) {
+    static async deviceFlowPollToken({ clientId, deviceCode, interval = 5, expiresIn = 900, host, signal, requestTimeoutMs = 15_000, }) {
         const baseUrl = host ? `https://${host}` : 'https://github.com';
         const deadline = Date.now() + expiresIn * 1000;
         let pollInterval = interval * 1000;
-        while (Date.now() < deadline) {
-            await new Promise(r => setTimeout(r, pollInterval));
-            const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Accept': 'application/json',
-                },
-                body: JSON.stringify({
-                    client_id: clientId,
-                    device_code: deviceCode,
-                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-                }),
-            });
-            const data = await res.json();
-            if (data.access_token) {
-                return { access_token: data.access_token, token_type: data.token_type, scope: data.scope };
+        while (true) {
+            if (signal?.aborted)
+                return { status: 'aborted' };
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return { status: 'expired' };
+            if (!await abortableDelay(Math.min(pollInterval, remaining), signal))
+                return { status: 'aborted' };
+            if (Date.now() >= deadline)
+                return { status: 'expired' };
+            let data;
+            try {
+                const timeout = AbortSignal.timeout(requestTimeoutMs);
+                const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        client_id: clientId,
+                        device_code: deviceCode,
+                        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                    }),
+                    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+                });
+                data = await res.json();
             }
-            if (data.error === 'slow_down') {
-                pollInterval = (data.interval || interval + 5) * 1000;
+            catch {
+                if (signal?.aborted)
+                    return { status: 'aborted' };
+                // Transient network / timeout / non-JSON response: keep polling until the deadline.
                 continue;
             }
+            if (!data || typeof data !== 'object')
+                continue;
+            if (typeof data.access_token === 'string' && data.access_token) {
+                return {
+                    status: 'authorized',
+                    access_token: data.access_token,
+                    token_type: typeof data.token_type === 'string' ? data.token_type : 'bearer',
+                    scope: typeof data.scope === 'string' ? data.scope : '',
+                };
+            }
             if (data.error === 'authorization_pending')
                 continue;
-            // expired_token / access_denied / 其他错误
-            return null;
+            if (data.error === 'slow_down') {
+                const next = Number(data.interval);
+                pollInterval = (Number.isFinite(next) && next > 0 ? next : pollInterval / 1000 + 5) * 1000;
+                continue;
+            }
+            if (data.error === 'expired_token')
+                return { status: 'expired' };
+            if (data.error === 'access_denied')
+                return { status: 'denied' };
+            if (typeof data.error === 'string') {
+                return { status: 'error', error: typeof data.error_description === 'string' ? data.error_description : data.error };
+            }
+            // No token and no error (e.g. a 5xx JSON body): treat as transient.
         }
-        return null;
     }
 }
+/** Resolves true after `ms`, or false as soon as `signal` aborts. */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); resolve(false); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(true); }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/lib/protocol.d.ts

@@ -1,5 +1,4 @@
 import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
-import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 import { type GenericWebhookPayload, type IssueCommentPayload, type PRReviewCommentPayload, type PRReviewPayload } from './types.js';
 export type { EventType, GenericWebhookPayload, GitHubComment, GitHubIssue, GitHubOAuthUser, GitHubPR, GitHubRepo, GitHubUser, IssueCommentPayload, ParsedChannel, PRReviewCommentPayload, PRReviewPayload, Subscription, } from './types.js';
@@ -57,13 +56,8 @@ export declare function formatInboundContent(body: string): string;
 /** Build markdown body for Issue/PR comment send. */
 export declare function formatOutboundBody(payload: unknown): string;
 export declare function verifyWebhookSignature(secret: string, rawBody: string, signatureHeader: string | undefined): boolean;
-export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;
-export declare function readTextBody(request: IncomingMessage, options?: {
-    readonly limit?: number;
-}): Promise<string>;
+export declare function headerValue(headers: Headers, name: string): string;
 export declare function parseIssueCommentInbound(payload: IssueCommentPayload): GithubInboundComment | null;
 export declare function parsePrReviewCommentInbound(payload: PRReviewCommentPayload): GithubInboundComment | null;
 export declare function parsePrReviewInbound(payload: PRReviewPayload): GithubInboundComment | null;
 export declare function formatNotification(event: string, p: GenericWebhookPayload): string;
-/** Parse @mentions in markdown into a flat display string (gateway text path). */
-export declare function parseMarkdownMentions(md: string): string;

package/lib/protocol.js

@@ -158,25 +158,7 @@ export function verifyWebhookSignature(secret, rawBody, signatureHeader) {
     }
 }
 export function headerValue(headers, name) {
-    const raw = headers[name] ?? headers[name.toLowerCase()];
-    if (Array.isArray(raw))
-        return raw[0] ?? '';
-    return raw ?? '';
-}
-export async function readTextBody(request, options = {}) {
-    const limit = options.limit ?? 1_048_576;
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buffer.length;
-        if (size > limit) {
-            request.destroy();
-            throw new Error(`Request body exceeds ${limit} bytes`);
-        }
-        chunks.push(buffer);
-    }
-    return Buffer.concat(chunks).toString('utf8');
+    return headers.get(name) ?? '';
 }
 export function parseIssueCommentInbound(payload) {
     if (payload.action !== 'created' || !payload.comment)
@@ -275,7 +257,3 @@ export function formatNotification(event, p) {
             return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
     }
 }
-/** Parse @mentions in markdown into a flat display string (gateway text path). */
-export function parseMarkdownMentions(md) {
-    return md;
-}

package/lib/webhook.d.ts

@@ -1,7 +1,6 @@
 /**
  * GitHub webhook HTTP: verify → parse → admit inbound comments.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
 export interface GithubWebhookHandler {
@@ -10,5 +9,5 @@ export interface GithubWebhookHandler {
     admit(comment: GithubInboundComment, nativeEvent?: unknown): void;
 }
 export declare function registerGithubWebhookRoutes(http: HttpHost, handler: GithubWebhookHandler): HttpRouteRegistration[];
-export declare function handleGithubWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: GithubWebhookHandler): Promise<void>;
+export declare function handleGithubWebhookRequest(request: Request, handler: GithubWebhookHandler): Promise<Response>;
 export declare function dispatchGithubWebhookPayload(event: string, payload: unknown, handler: GithubWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -1,28 +1,23 @@
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, readTextBody, verifyWebhookSignature, } from './protocol.js';
+import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, verifyWebhookSignature, } from './protocol.js';
 const logger = getLogger('github');
 export function registerGithubWebhookRoutes(http, handler) {
     const routePath = handler.config.webhookPath;
     return [
-        http.route('POST', routePath, async (request, response) => {
-            await handleGithubWebhookRequest(request, response, handler);
-        }, { summary: 'GitHub webhook', tags: ['github'] }),
+        http.route('POST', routePath, (request) => handleGithubWebhookRequest(request, handler), { summary: 'GitHub webhook', tags: ['github'] }),
     ];
 }
-export async function handleGithubWebhookRequest(request, response, handler) {
+export async function handleGithubWebhookRequest(request, handler) {
     const secret = handler.config.webhookSecret;
     if (!secret) {
-        response.writeHead(503, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ error: 'Webhook not configured' }));
-        return;
+        return new Response(JSON.stringify({ error: 'Webhook not configured' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
     }
     const signature = headerValue(request.headers, 'x-hub-signature-256');
     const event = headerValue(request.headers, 'x-github-event');
     const deliveryId = headerValue(request.headers, 'x-github-delivery');
     if (!signature || !event) {
-        response.writeHead(400, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ error: 'Missing signature or event header' }));
-        return;
+        return new Response(JSON.stringify({ error: 'Missing signature or event header' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
     }
     try {
         const rawBody = await readTextBody(request);
@@ -33,31 +28,23 @@ export async function handleGithubWebhookRequest(request, response, handler) {
                 error: 'invalid signature',
                 delivery: deliveryId,
             }));
-            response.writeHead(401, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Invalid signature' }));
-            return;
+            return new Response(JSON.stringify({ error: 'Invalid signature' }), { status: 401, headers: { 'Content-Type': 'application/json' } });
         }
         let payload;
         try {
             payload = rawBody ? JSON.parse(rawBody) : {};
         }
         catch {
-            response.writeHead(400, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Invalid JSON' }));
-            return;
+            return new Response(JSON.stringify({ error: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
         }
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ ok: true }));
         void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
             logger.error(`Webhook 事件处理失败 (${event}):`, e);
         });
+        return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
     catch (error) {
         logger.error('Webhook error:', error);
-        if (!response.headersSent) {
-            response.writeHead(500, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Internal Server Error' }));
-        }
+        return new Response(JSON.stringify({ error: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
     }
 }
 export async function dispatchGithubWebhookPayload(event, payload, handler) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "1.1.25",
+  "version": "1.1.27",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,27 +39,28 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.31",
-    "@zhin.js/agent-feature": "1.1.16",
-    "@zhin.js/console-contract": "1.1.5",
-    "@zhin.js/core": "1.1.59",
-    "@zhin.js/feature-kit": "1.1.15",
-    "@zhin.js/host-http": "1.1.17",
-    "@zhin.js/im-contract": "1.1.13",
-    "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.17",
-    "@zhin.js/skill": "1.1.16",
-    "@zhin.js/tool": "1.1.18"
+    "zod": "^4.6.7",
+    "@zhin.js/adapter": "1.1.33",
+    "@zhin.js/agent-feature": "1.1.17",
+    "@zhin.js/console-contract": "1.1.6",
+    "@zhin.js/core": "1.2.0",
+    "@zhin.js/feature-kit": "1.1.16",
+    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/host-http-contract": "1.2.0",
+    "@zhin.js/im-contract": "1.1.14",
+    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/page": "1.1.18",
+    "@zhin.js/skill": "1.1.17",
+    "@zhin.js/tool": "1.1.19"
   },
   "peerDependencies": {
-    "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.31",
-    "@zhin.js/agent": "^1.1.50",
-    "@zhin.js/command": "^1.1.17",
-    "@zhin.js/core": "^1.1.59",
-    "@zhin.js/host-http": "^1.1.17",
-    "@zhin.js/prompt-section": "^1.1.15",
-    "zhin.js": "^1.1.24"
+    "@zhin.js/adapter": "^1.1.33",
+    "@zhin.js/agent": "^1.2.0",
+    "@zhin.js/command": "^1.2.0",
+    "@zhin.js/core": "^1.2.0",
+    "@zhin.js/host-http": "^1.2.0",
+    "@zhin.js/prompt-section": "^1.1.16",
+    "zhin.js": "^1.1.26"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -73,19 +74,15 @@
     },
     "zhin.js": {
       "optional": true
-    },
-    "zod": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.50",
-    "@zhin.js/prompt-section": "1.1.15",
-    "zhin.js": "1.1.24"
+    "@zhin.js/agent": "1.2.0",
+    "@zhin.js/prompt-section": "1.1.16",
+    "zhin.js": "1.1.26"
   },
   "files": [
     "adapters",
@@ -137,6 +134,11 @@
       {
         "package": "@zhin.js/page",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/prompt-section",
+        "api": "^1.0.0",
+        "optional": true
       }
     ],
     "plugins": []
@@ -144,6 +146,6 @@
   "scripts": {
     "build": "tsc",
     "clean": "rimraf lib",
-    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/github/tests"
+    "test": "vitest run --root ../../.. plugins/adapters/github/tests"
   }
 }

package/schema.json

@@ -26,34 +26,6 @@
       "type": "string",
       "description": "Managed git workspace root"
     },
-    "master": {
-      "type": [
-        "string",
-        "number"
-      ],
-      "description": "框架 master（GitHub user login or id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖",
-      "x-i18n": {
-        "en": {
-          "description": "Framework masters (GitHub user login or id; AI/tool permissions and endpoint management). endpoints[i].master can override this value."
-        }
-      }
-    },
-    "trusted": {
-      "type": "array",
-      "items": {
-        "type": [
-          "string",
-          "number"
-        ],
-        "description": "Trusted GitHub user login or id"
-      },
-      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加",
-      "x-i18n": {
-        "en": {
-          "description": "Framework trusted users, below master authority. endpoints[i].trusted can add users."
-        }
-      }
-    },
     "endpoints": {
       "type": "array",
       "minItems": 1,
@@ -62,34 +34,6 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "master": {
-            "type": [
-              "string",
-              "number"
-            ],
-            "description": "本 endpoint 的框架 master（GitHub user login or id）；覆盖顶层 master",
-            "x-i18n": {
-              "en": {
-                "description": "Framework masters for this endpoint (GitHub user login or id), overriding the top-level master list."
-              }
-            }
-          },
-          "trusted": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ],
-              "description": "Trusted GitHub user login or id"
-            },
-            "description": "本 endpoint 的 trusted 列表",
-            "x-i18n": {
-              "en": {
-                "description": "Trusted users for this endpoint."
-              }
-            }
-          },
           "app_id": {
             "type": [
               "string",

package/src/console-spec.ts

@@ -7,9 +7,42 @@ export const githubConsoleSpec = {
   adapterKey: 'github',
   adapterDisplayName: 'GitHub',
   fields: [
-    { key: 'app_id', required: true, env: true, description: 'GitHub App ID' },
-    { key: 'private_key', required: true, secret: true, description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容', descriptionI18n: { en: 'PEM file path (recommended) or PEM content' } },
-    { key: 'webhook_secret', env: true, description: 'webhook 签名密钥（不配则 API-only）', descriptionI18n: { en: 'Webhook signing secret (API-only when omitted)' } },
+    {
+      key: 'app_id',
+      required: true,
+      env: true,
+      label: 'GitHub App ID',
+      labelI18n: { en: 'GitHub App ID' },
+      group: '应用凭证与私钥',
+      groupI18n: { en: 'App Credentials & Key' },
+      placeholder: '123456',
+      description: 'GitHub App 设置页中的 App ID',
+      descriptionI18n: { en: 'GitHub App ID' },
+    },
+    {
+      key: 'private_key',
+      required: true,
+      secret: true,
+      label: '私钥路径或 PEM 内容',
+      labelI18n: { en: 'Private Key Path or PEM' },
+      group: '应用凭证与私钥',
+      groupI18n: { en: 'App Credentials & Key' },
+      placeholder: './data/github-app.pem',
+      description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容',
+      descriptionI18n: { en: 'PEM file path (recommended) or PEM content' },
+    },
+    {
+      key: 'webhook_secret',
+      env: true,
+      label: 'Webhook Secret (签名密钥)',
+      labelI18n: { en: 'Webhook Secret' },
+      group: 'Webhook 回调',
+      groupI18n: { en: 'Webhook Callback' },
+      placeholder: '留空则仅作为 API-only 出站模式运行',
+      placeholderI18n: { en: 'Optional webhook secret (API-only if omitted)' },
+      description: 'webhook 签名密钥（不配则 API-only）',
+      descriptionI18n: { en: 'Webhook signing secret (API-only when omitted)' },
+    },
   ] as readonly AdapterConsoleField[],
   docsUrl: 'https://zhin.js.org/adapters/github',
   readPermission: 'github:read',

package/src/gh-client.ts

@@ -67,6 +67,8 @@ export class GhClient {
   protected apiHost?: string;
   protected executionSignal?: AbortSignal;
   protected bindExecutionSignal(signal: AbortSignal): void { this.executionSignal = signal; }
+  /** Aborted when the owning endpoint stops; long-running background work should observe it. */
+  get lifecycleSignal(): AbortSignal | undefined { return this.executionSignal; }
   private token?: string;
   private _appAuth?: AppAuth;
   private _resolvedKey?: string;
@@ -691,46 +693,99 @@ export class GhClient {
   }
 
   /**
-   * 第二步：轮询等待用户授权
-   * @returns access_token 或 null（超时/拒绝）
+   * 第二步：轮询等待用户授权。
+   * 可通过 `signal` 取消；单次请求有超时；网络/JSON 等瞬时错误会重试到设备码过期为止。
    */
-  static async deviceFlowPollToken(
-    clientId: string,
-    deviceCode: string,
-    interval: number = 5,
-    expiresIn: number = 900,
-    host?: string,
-  ): Promise<{ access_token: string; token_type: string; scope: string } | null> {
+  static async deviceFlowPollToken({
+    clientId,
+    deviceCode,
+    interval = 5,
+    expiresIn = 900,
+    host,
+    signal,
+    requestTimeoutMs = 15_000,
+  }: GhDeviceFlowPollRequest): Promise<GhDeviceFlowPollResult> {
     const baseUrl = host ? `https://${host}` : 'https://github.com';
     const deadline = Date.now() + expiresIn * 1000;
     let pollInterval = interval * 1000;
 
-    while (Date.now() < deadline) {
-      await new Promise(r => setTimeout(r, pollInterval));
-      const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Accept': 'application/json',
-        },
-        body: JSON.stringify({
-          client_id: clientId,
-          device_code: deviceCode,
-          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-        }),
-      });
-      const data = await res.json() as Record<string, any>;
-      if (data.access_token) {
-        return { access_token: data.access_token, token_type: data.token_type, scope: data.scope };
+    while (true) {
+      if (signal?.aborted) return { status: 'aborted' };
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return { status: 'expired' };
+      if (!await abortableDelay(Math.min(pollInterval, remaining), signal)) return { status: 'aborted' };
+      if (Date.now() >= deadline) return { status: 'expired' };
+
+      let data: Record<string, unknown>;
+      try {
+        const timeout = AbortSignal.timeout(requestTimeoutMs);
+        const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+          },
+          body: JSON.stringify({
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+          }),
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+        });
+        data = await res.json() as Record<string, unknown>;
+      } catch {
+        if (signal?.aborted) return { status: 'aborted' };
+        // Transient network / timeout / non-JSON response: keep polling until the deadline.
+        continue;
       }
+      if (!data || typeof data !== 'object') continue;
+      if (typeof data.access_token === 'string' && data.access_token) {
+        return {
+          status: 'authorized',
+          access_token: data.access_token,
+          token_type: typeof data.token_type === 'string' ? data.token_type : 'bearer',
+          scope: typeof data.scope === 'string' ? data.scope : '',
+        };
+      }
+      if (data.error === 'authorization_pending') continue;
       if (data.error === 'slow_down') {
-        pollInterval = (data.interval || interval + 5) * 1000;
+        const next = Number(data.interval);
+        pollInterval = (Number.isFinite(next) && next > 0 ? next : pollInterval / 1000 + 5) * 1000;
         continue;
       }
-      if (data.error === 'authorization_pending') continue;
-      // expired_token / access_denied / 其他错误
-      return null;
+      if (data.error === 'expired_token') return { status: 'expired' };
+      if (data.error === 'access_denied') return { status: 'denied' };
+      if (typeof data.error === 'string') {
+        return { status: 'error', error: typeof data.error_description === 'string' ? data.error_description : data.error };
+      }
+      // No token and no error (e.g. a 5xx JSON body): treat as transient.
     }
-    return null;
   }
 }
+
+export interface GhDeviceFlowPollRequest {
+  readonly clientId: string;
+  readonly deviceCode: string;
+  /** Seconds between polls (GitHub default 5). */
+  readonly interval?: number;
+  /** Seconds until the device code expires (GitHub default 900). */
+  readonly expiresIn?: number;
+  readonly host?: string;
+  readonly signal?: AbortSignal;
+  readonly requestTimeoutMs?: number;
+}
+
+export type GhDeviceFlowPollResult =
+  | { readonly status: 'authorized'; readonly access_token: string; readonly token_type: string; readonly scope: string }
+  | { readonly status: 'expired' | 'denied' | 'aborted' }
+  | { readonly status: 'error'; readonly error: string };
+
+/** Resolves true after `ms`, or false as soon as `signal` aborts. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) { resolve(false); return; }
+    const onAbort = () => { clearTimeout(timer); resolve(false); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(true); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}