experimental-ash 0.56.0 → 0.57.0

package/dist/src/public/channels/github/api.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Minimal GitHub REST/GraphQL wrapper used by the GitHub channel.
+ *
+ * Ash exposes channel-owned helper types and functions instead of leaking a
+ * third-party SDK through public channel APIs.
+ */
+import { type GitHubAuthApiOptions, type GitHubChannelCredentials } from "#public/channels/github/auth.js";
+import { type JsonObject } from "#shared/json.js";
+/** JSON object accepted by GitHub helper calls. */
+export type GitHubJsonObject = JsonObject;
+/** HTTP methods supported by the low-level GitHub request helper. */
+export type GitHubApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+/** Shared GitHub API options. */
+export interface GitHubApiOptions extends GitHubAuthApiOptions {
+}
+/** Options for {@link GitHubHandle.request}. */
+export interface GitHubRequestOptions {
+    readonly auth?: boolean;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly installationId?: number;
+}
+/** Low-level GitHub API response. */
+export interface GitHubApiResponse<T = unknown> {
+    readonly body: T;
+    readonly ok: boolean;
+    readonly status: number;
+}
+/** Error thrown for non-2xx GitHub REST and GraphQL responses. */
+export declare class GitHubApiError extends Error {
+    readonly body: unknown;
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    constructor(input: {
+        readonly body: unknown;
+        readonly method: string;
+        readonly path: string;
+        readonly status: number;
+    });
+}
+/** Body accepted by GitHub comment-writing helpers. */
+export interface GitHubCommentBody {
+    readonly body: string;
+}
+/** Minimal posted-comment result returned by thread helpers. */
+export interface GitHubPostedComment {
+    readonly htmlUrl: string | undefined;
+    readonly id: number;
+    readonly raw: unknown;
+    readonly url: string | undefined;
+}
+/** GitHub reaction contents supported by the Reactions REST API. */
+export type GitHubReactionContent = "+1" | "-1" | "confused" | "eyes" | "heart" | "hooray" | "laugh" | "rocket";
+interface GitHubResourceInput {
+    readonly api?: GitHubApiOptions;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly installationId?: number;
+    readonly owner: string;
+    readonly repo: string;
+}
+/**
+ * Calls a GitHub REST API path with installation-token auth by default.
+ * Pass `options.auth: false` for public unauthenticated reads.
+ */
+export declare function callGitHubApi<T = unknown>(input: {
+    readonly api?: GitHubApiOptions;
+    readonly body?: GitHubJsonObject;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly installationId?: number;
+    readonly method: GitHubApiMethod;
+    readonly path: string;
+    readonly options?: GitHubRequestOptions;
+}): Promise<GitHubApiResponse<T>>;
+/** Creates an issue or PR timeline comment. */
+export declare function createGitHubIssueComment(input: GitHubResourceInput & {
+    readonly body: string | GitHubCommentBody;
+    readonly issueNumber: number;
+}): Promise<GitHubPostedComment>;
+/** Updates an issue or PR timeline comment. */
+export declare function updateGitHubIssueComment(input: GitHubResourceInput & {
+    readonly body: string | GitHubCommentBody;
+    readonly commentId: number;
+}): Promise<GitHubPostedComment>;
+/** Replies to an inline pull-request review comment thread. */
+export declare function createGitHubReviewCommentReply(input: GitHubResourceInput & {
+    readonly body: string | GitHubCommentBody;
+    readonly commentId: number;
+    readonly pullRequestNumber: number;
+}): Promise<GitHubPostedComment>;
+/** Updates an inline pull-request review comment or reply. */
+export declare function updateGitHubPullRequestReviewComment(input: GitHubResourceInput & {
+    readonly body: string | GitHubCommentBody;
+    readonly commentId: number;
+}): Promise<GitHubPostedComment>;
+/** Creates a pull-request review. */
+export declare function createGitHubPullRequestReview(input: GitHubResourceInput & {
+    readonly body: GitHubJsonObject;
+    readonly pullRequestNumber: number;
+}): Promise<GitHubApiResponse>;
+/** Creates an inline pull-request review comment. */
+export declare function createGitHubPullRequestReviewComment(input: GitHubResourceInput & {
+    readonly body: GitHubJsonObject;
+    readonly pullRequestNumber: number;
+}): Promise<GitHubPostedComment>;
+/** Minimal pull-request metadata returned by {@link getGitHubPullRequest}. */
+export interface GitHubPullRequestDetails {
+    readonly additions: number | undefined;
+    readonly author: GitHubPullRequestUser | undefined;
+    readonly base: GitHubPullRequestRefDetails;
+    readonly body: string | undefined;
+    readonly changedFiles: number | undefined;
+    readonly defaultBranch: string | undefined;
+    readonly deletions: number | undefined;
+    readonly draft: boolean;
+    readonly head: GitHubPullRequestRefDetails;
+    readonly htmlUrl: string | undefined;
+    readonly mergeable: boolean | null | undefined;
+    readonly number: number;
+    readonly raw: unknown;
+    readonly state: string | undefined;
+    readonly title: string;
+}
+/** Minimal pull-request author metadata. */
+export interface GitHubPullRequestUser {
+    readonly id: number;
+    readonly login: string;
+    readonly type: string;
+}
+/** Minimal pull-request branch metadata. */
+export interface GitHubPullRequestRefDetails {
+    readonly ref: string | undefined;
+    readonly repoFullName: string | undefined;
+    readonly sha: string | undefined;
+}
+/** Fetches pull-request metadata for context injection and checkout resolution. */
+export declare function getGitHubPullRequest(input: GitHubResourceInput & {
+    readonly pullRequestNumber: number;
+}): Promise<GitHubPullRequestDetails>;
+/** Minimal pull-request file metadata returned by {@link listGitHubPullRequestFiles}. */
+export interface GitHubPullRequestFile {
+    readonly additions: number | undefined;
+    readonly changes: number | undefined;
+    readonly deletions: number | undefined;
+    readonly filename: string;
+    readonly patch: string | undefined;
+    readonly status: string | undefined;
+}
+/** Lists files changed by a pull request. */
+export declare function listGitHubPullRequestFiles(input: GitHubResourceInput & {
+    readonly perPage?: number;
+    readonly pullRequestNumber: number;
+}): Promise<readonly GitHubPullRequestFile[]>;
+/** Creates a reaction on a GitHub issue or review comment. */
+export declare function createGitHubReaction(input: GitHubResourceInput & {
+    readonly commentId: number;
+    readonly content: GitHubReactionContent;
+    readonly subject: "issue_comment" | "pull_request_review_comment";
+}): Promise<GitHubApiResponse>;
+/** Fetches repository metadata, primarily to resolve `repository.id` for receive(). */
+export declare function getGitHubRepository(input: GitHubResourceInput & {
+    readonly auth?: boolean;
+}): Promise<{
+    readonly id: number;
+    readonly defaultBranch: string | undefined;
+}>;
+export {};

package/dist/src/public/channels/github/api.js

@@ -0,0 +1 @@
+import{isObject}from"#shared/guards.js";import{parseJsonObject}from"#shared/json.js";import{resolveGitHubInstallationToken}from"#public/channels/github/auth.js";var GitHubApiError=class extends Error{body;method;path;status;constructor(e){super(`GitHub ${e.method} ${e.path} failed with HTTP ${e.status}.`),this.name=`GitHubApiError`,this.body=e.body,this.method=e.method,this.path=e.path,this.status=e.status}};async function callGitHubApi(e){let r=e.api?.fetch??fetch,i=e.options?.auth!==!1,a={accept:`application/vnd.github+json`,"x-github-api-version":`2022-11-28`,...e.options?.headers};e.body!==void 0&&(a[`content-type`]=`application/json; charset=utf-8`),i&&(a.authorization=`Bearer ${await resolveGitHubInstallationToken({api:e.api,credentials:e.credentials,installationId:e.options?.installationId??e.installationId})}`);let o=await r(`${e.api?.apiBaseUrl??`https://api.github.com`}${e.path}`,{body:e.body===void 0?void 0:JSON.stringify(parseJsonObject(e.body)),headers:a,method:e.method}),s=await parseResponseBody(o);if(!o.ok)throw new GitHubApiError({body:s,method:e.method,path:e.path,status:o.status});return{body:s,ok:o.ok,status:o.status}}async function createGitHubIssueComment(e){return toPostedComment((await callGitHubApi({api:e.api,body:normalizeCommentBody(e.body),credentials:e.credentials,installationId:e.installationId,method:`POST`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/issues/${e.issueNumber}/comments`})).body)}async function updateGitHubIssueComment(e){return toPostedComment((await callGitHubApi({api:e.api,body:normalizeCommentBody(e.body),credentials:e.credentials,installationId:e.installationId,method:`PATCH`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/issues/comments/${e.commentId}`})).body)}async function createGitHubReviewCommentReply(e){return toPostedComment((await callGitHubApi({api:e.api,body:normalizeCommentBody(e.body),credentials:e.credentials,installationId:e.installationId,method:`POST`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/${e.pullRequestNumber}/comments/${e.commentId}/replies`})).body)}async function updateGitHubPullRequestReviewComment(e){return toPostedComment((await callGitHubApi({api:e.api,body:normalizeCommentBody(e.body),credentials:e.credentials,installationId:e.installationId,method:`PATCH`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/comments/${e.commentId}`})).body)}function createGitHubPullRequestReview(e){return callGitHubApi({api:e.api,body:e.body,credentials:e.credentials,installationId:e.installationId,method:`POST`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/${e.pullRequestNumber}/reviews`})}async function createGitHubPullRequestReviewComment(e){return toPostedComment((await callGitHubApi({api:e.api,body:e.body,credentials:e.credentials,installationId:e.installationId,method:`POST`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/${e.pullRequestNumber}/comments`})).body)}async function getGitHubPullRequest(e){return toPullRequestDetails((await callGitHubApi({api:e.api,credentials:e.credentials,installationId:e.installationId,method:`GET`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/${e.pullRequestNumber}`})).body)}async function listGitHubPullRequestFiles(e){let t=e.perPage===void 0?``:`?per_page=${Math.min(e.perPage,100)}`;return(await callGitHubApi({api:e.api,credentials:e.credentials,installationId:e.installationId,method:`GET`,path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/pulls/${e.pullRequestNumber}/files${t}`})).body.map(toPullRequestFile)}function createGitHubReaction(e){let t=e.subject===`issue_comment`?`issues/comments`:`pulls/comments`;return callGitHubApi({api:e.api,body:{content:e.content},credentials:e.credentials,installationId:e.installationId,method:`POST`,options:{headers:{accept:`application/vnd.github+json`}},path:`/repos/${encodePath(e.owner)}/${encodePath(e.repo)}/${t}/${e.commentId}/reactions`})}async function getGitHubRepository(t){let n=await callGitHubApi({api:t.api,credentials:t.credentials,installationId:t.installationId,method:`GET`,options:{auth:t.auth??t.installationId!==void 0},path:`/repos/${encodePath(t.owner)}/${encodePath(t.repo)}`}),r=isObject(n.body)?n.body:{},i=typeof r.id==`number`?r.id:0;return{defaultBranch:typeof r.default_branch==`string`?r.default_branch:void 0,id:i}}function normalizeCommentBody(e){return{body:typeof e==`string`?e:e.body}}function toPostedComment(t){let n=isObject(t)?t:{};return{htmlUrl:typeof n.html_url==`string`?n.html_url:void 0,id:typeof n.id==`number`?n.id:0,raw:t,url:typeof n.url==`string`?n.url:void 0}}function toPullRequestFile(t){let n=isObject(t)?t:{};return{additions:typeof n.additions==`number`?n.additions:void 0,changes:typeof n.changes==`number`?n.changes:void 0,deletions:typeof n.deletions==`number`?n.deletions:void 0,filename:typeof n.filename==`string`?n.filename:``,patch:typeof n.patch==`string`?n.patch:void 0,status:typeof n.status==`string`?n.status:void 0}}function toPullRequestDetails(t){let n=isObject(t)?t:{},r=toPullRequestRefDetails(n.base);return{additions:typeof n.additions==`number`?n.additions:void 0,author:toPullRequestUser(n.user),base:r,body:typeof n.body==`string`&&n.body.length>0?n.body:void 0,changedFiles:typeof n.changed_files==`number`?n.changed_files:void 0,defaultBranch:readDefaultBranch(n.base),deletions:typeof n.deletions==`number`?n.deletions:void 0,draft:n.draft===!0,head:toPullRequestRefDetails(n.head),htmlUrl:typeof n.html_url==`string`?n.html_url:void 0,mergeable:typeof n.mergeable==`boolean`||n.mergeable===null?n.mergeable:void 0,number:typeof n.number==`number`?n.number:0,raw:t,state:typeof n.state==`string`?n.state:void 0,title:typeof n.title==`string`?n.title:``}}function toPullRequestRefDetails(t){let n=isObject(t)?t:{},r=isObject(n.repo)?n.repo:{};return{ref:typeof n.ref==`string`?n.ref:void 0,repoFullName:typeof r.full_name==`string`?r.full_name:void 0,sha:typeof n.sha==`string`?n.sha:void 0}}function toPullRequestUser(t){if(!(!isObject(t)||typeof t.login!=`string`))return{id:typeof t.id==`number`?t.id:0,login:t.login,type:typeof t.type==`string`?t.type:`User`}}function readDefaultBranch(t){let n=isObject(t)?t:{},r=isObject(n.repo)?n.repo:{};return typeof r.default_branch==`string`?r.default_branch:void 0}async function parseResponseBody(e){let t=await e.text();if(!t)return null;try{return JSON.parse(t)}catch{return t}}function encodePath(e){return encodeURIComponent(e)}export{GitHubApiError,callGitHubApi,createGitHubIssueComment,createGitHubPullRequestReview,createGitHubPullRequestReviewComment,createGitHubReaction,createGitHubReviewCommentReply,getGitHubPullRequest,getGitHubRepository,listGitHubPullRequestFiles,updateGitHubIssueComment,updateGitHubPullRequestReviewComment};

package/dist/src/public/channels/github/auth.d.ts

@@ -0,0 +1,83 @@
+import type { GitHubWebhookVerifier } from "#public/channels/github/verify.js";
+/** GitHub App id, supplied directly or resolved lazily from a secret manager. */
+export type GitHubAppId = number | string | (() => number | string | Promise<number | string>);
+/** GitHub App private key, supplied directly or resolved lazily from a secret manager. */
+export type GitHubPrivateKey = string | (() => string | Promise<string>);
+/** GitHub webhook secret, supplied directly or resolved lazily from a secret manager. */
+export type GitHubWebhookSecret = string | (() => string | Promise<string>);
+/**
+ * Pre-resolved GitHub installation access token, supplied directly or
+ * resolved lazily from a secret manager. When present, ash skips the
+ * native `appId`/`privateKey`/`installationId` JWT-minting path entirely.
+ * Typically populated by integrations (e.g. Connect) that derive the
+ * installation token out-of-band.
+ */
+export type GitHubInstallationToken = string | (() => string | Promise<string>);
+/** Credentials used by the native GitHub channel. */
+export interface GitHubChannelCredentials {
+    readonly appId?: GitHubAppId;
+    readonly privateKey?: GitHubPrivateKey;
+    readonly webhookSecret?: GitHubWebhookSecret;
+    /**
+     * Pre-resolved GitHub installation access token. When supplied, ash uses
+     * it directly for authenticated GitHub API calls and skips the native
+     * `appId`/`privateKey` JWT exchange — `installationId` is not required.
+     * Typically populated by integrations (e.g. Connect) that derive the
+     * token out-of-band.
+     */
+    readonly installationToken?: GitHubInstallationToken;
+    /**
+     * Custom inbound webhook verifier. When supplied, ash skips the
+     * `GITHUB_WEBHOOK_SECRET` fallback and delegates verification to this
+     * function. Typically populated by integrations (e.g. Connect) that
+     * authenticate webhooks out-of-band.
+     */
+    readonly webhookVerifier?: GitHubWebhookVerifier;
+}
+/** Options needed by GitHub App auth helpers. */
+export interface GitHubAuthApiOptions {
+    readonly apiBaseUrl?: string;
+    readonly fetch?: typeof fetch;
+}
+/** Resolves a GitHub App id, falling back to `GITHUB_APP_ID`. */
+export declare function resolveGitHubAppId(appId?: GitHubAppId): Promise<string>;
+/** Resolves and normalizes a GitHub App private key. */
+export declare function resolveGitHubPrivateKey(privateKey?: GitHubPrivateKey): Promise<string>;
+/** Resolves a GitHub webhook secret, falling back to `GITHUB_WEBHOOK_SECRET`. */
+export declare function resolveGitHubWebhookSecret(webhookSecret?: GitHubWebhookSecret): Promise<string>;
+/** Converts hosted-platform escaped newlines back into PEM newlines. */
+export declare function normalizeGitHubPrivateKey(privateKey: string): string;
+/** Creates a short-lived RS256 GitHub App JWT. */
+export declare function createGitHubAppJwt(input: {
+    readonly appId?: GitHubAppId;
+    readonly now?: Date;
+    readonly privateKey?: GitHubPrivateKey;
+}): Promise<string>;
+/**
+ * Resolves an installation access token by minting and caching a GitHub App
+ * installation token in process memory.
+ */
+export declare function resolveGitHubInstallationToken(input: {
+    readonly api?: GitHubAuthApiOptions;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly installationId: number | undefined;
+}): Promise<string>;
+/**
+ * Exchanges a GitHub App JWT for an installation access token, cached until
+ * shortly before GitHub's reported expiry.
+ */
+export declare function createGitHubInstallationToken(input: {
+    readonly api?: GitHubAuthApiOptions;
+    readonly appId?: GitHubAppId;
+    readonly installationId: number;
+    readonly privateKey?: GitHubPrivateKey;
+}): Promise<string>;
+/** Clears the in-memory GitHub installation token cache. Intended for tests. */
+export declare function clearGitHubInstallationTokenCache(): void;
+/** Seeds the in-memory installation token cache. Intended for tests. */
+export declare function seedGitHubInstallationTokenForTests(input: {
+    readonly apiBaseUrl?: string;
+    readonly appId?: string;
+    readonly installationId: number;
+    readonly token: string;
+}): void;

package/dist/src/public/channels/github/auth.js

@@ -0,0 +1,2 @@
+import{isObject}from"#shared/guards.js";import{createSign}from"node:crypto";const installationTokenCache=new Map;async function resolveGitHubAppId(e){let t=e??process.env.GITHUB_APP_ID;if(t===void 0||t===``)throw Error(`githubChannel: GITHUB_APP_ID is required.`);let n=typeof t==`function`?await t():t;return String(n)}async function resolveGitHubPrivateKey(e){let t=e??process.env.GITHUB_APP_PRIVATE_KEY;if(!t)throw Error(`githubChannel: GITHUB_APP_PRIVATE_KEY is required.`);return normalizeGitHubPrivateKey(typeof t==`function`?await t():t)}async function resolveGitHubWebhookSecret(e){let t=e??process.env.GITHUB_WEBHOOK_SECRET;if(!t)throw Error(`githubChannel: GITHUB_WEBHOOK_SECRET is required.`);return typeof t==`function`?await t():t}function normalizeGitHubPrivateKey(e){return e.replace(/\\n/gu,`
+`)}async function createGitHubAppJwt(e){let n=await resolveGitHubAppId(e.appId),r=await resolveGitHubPrivateKey(e.privateKey),i=Math.floor((e.now?.getTime()??Date.now())/1e3),a={alg:`RS256`,typ:`JWT`},o={exp:i+600,iat:i-60,iss:n},s=`${base64UrlJson(a)}.${base64UrlJson(o)}`;return`${s}.${createSign(`RSA-SHA256`).update(s).sign(r,`base64url`)}`}async function resolveGitHubInstallationToken(e){let t=e.credentials?.installationToken;if(t!==void 0)return typeof t==`function`?await t():t;if(e.installationId===void 0)throw Error(`githubChannel: installationId is required for authenticated GitHub API calls.`);return createGitHubInstallationToken({api:e.api,appId:e.credentials?.appId,installationId:e.installationId,privateKey:e.credentials?.privateKey})}async function createGitHubInstallationToken(t){let r=await resolveGitHubAppId(t.appId),i=t.api?.apiBaseUrl??`https://api.github.com`,a=`${i}:${r}:${t.installationId}`,o=installationTokenCache.get(a);if(o!==void 0&&Date.now()<o.expiresAtMs-6e4)return o.token;let s=await createGitHubAppJwt({appId:r,privateKey:t.privateKey}),c=await(t.api?.fetch??fetch)(`${i}/app/installations/${t.installationId}/access_tokens`,{headers:{accept:`application/vnd.github+json`,authorization:`Bearer ${s}`,"x-github-api-version":`2022-11-28`},method:`POST`}),l=await parseJsonBody(c);if(!c.ok)throw Error(`githubChannel: create installation token failed with HTTP ${c.status}.`);if(!isObject(l)||typeof l.token!=`string`)throw Error(`githubChannel: installation token response did not include a token.`);let u=parseExpiryMs(l.expires_at);return installationTokenCache.set(a,{expiresAtMs:u,token:l.token}),l.token}function clearGitHubInstallationTokenCache(){installationTokenCache.clear()}function seedGitHubInstallationTokenForTests(e){let t=e.apiBaseUrl??`https://api.github.com`,r=e.appId??`test-app`;installationTokenCache.set(`${t}:${r}:${e.installationId}`,{expiresAtMs:Date.now()+3600*1e3,token:e.token})}function base64UrlJson(e){return Buffer.from(JSON.stringify(e)).toString(`base64url`)}async function parseJsonBody(e){let t=await e.text();if(!t)return null;try{return JSON.parse(t)}catch{return t}}function parseExpiryMs(e){if(typeof e==`string`){let t=Date.parse(e);if(Number.isFinite(t))return t}return Date.now()+3600*1e3}export{clearGitHubInstallationTokenCache,createGitHubAppJwt,createGitHubInstallationToken,normalizeGitHubPrivateKey,resolveGitHubAppId,resolveGitHubInstallationToken,resolveGitHubPrivateKey,resolveGitHubWebhookSecret,seedGitHubInstallationTokenForTests};

package/dist/src/public/channels/github/binding.d.ts

@@ -0,0 +1,49 @@
+import { type GitHubApiMethod, type GitHubApiOptions, type GitHubApiResponse, type GitHubJsonObject, type GitHubPostedComment, type GitHubReactionContent } from "#public/channels/github/api.js";
+import type { GitHubChannelCredentials } from "#public/channels/github/auth.js";
+import type { GitHubConversationKind, GitHubRepositoryRef } from "#public/channels/github/inbound.js";
+/** Minimal config needed to rebuild GitHub API handles. */
+export interface GitHubBindingConfig {
+    readonly api?: GitHubApiOptions;
+    readonly credentials?: GitHubChannelCredentials;
+}
+/** Serializable state fields needed to rebuild GitHub API handles. */
+export interface GitHubBindingState {
+    readonly conversationKind: GitHubConversationKind;
+    readonly installationId: number | null;
+    readonly issueNumber: number | null;
+    readonly owner: string;
+    readonly pullRequestNumber: number | null;
+    readonly repo: string;
+    readonly repositoryId: number;
+    readonly reviewCommentId: number | null;
+    readonly reviewThreadRootCommentId: number | null;
+    readonly triggeringCommentId: number | null;
+}
+/** GitHub operations exposed to hooks and events. */
+export interface GitHubHandle {
+    readonly installationId: number | undefined;
+    readonly repository: GitHubRepositoryRef;
+    /**
+     * Calls an arbitrary GitHub REST path with installation-token auth. Use this
+     * for any GitHub operation the channel does not wrap natively.
+     */
+    request<T = unknown>(input: {
+        readonly body?: GitHubJsonObject;
+        readonly method: GitHubApiMethod;
+        readonly path: string;
+    }): Promise<GitHubApiResponse<T>>;
+}
+/** Thread-scoped operations for the current GitHub conversation. */
+export interface GitHubThread {
+    readonly kind: GitHubConversationKind;
+    post(message: string): Promise<GitHubPostedComment>;
+    react(content: GitHubReactionContent): Promise<void>;
+}
+/** Rebuilds GitHub API and thread handles from durable channel state. */
+export declare function buildGitHubBinding(input: {
+    readonly config: GitHubBindingConfig;
+    readonly state: GitHubBindingState;
+}): {
+    readonly github: GitHubHandle;
+    readonly thread: GitHubThread;
+};

package/dist/src/public/channels/github/binding.js

@@ -0,0 +1 @@
+import{callGitHubApi,createGitHubIssueComment,createGitHubReaction,createGitHubReviewCommentReply}from"#public/channels/github/api.js";function buildGitHubBinding(n){let{config:r,state:i}=n,a={fullName:`${i.owner}/${i.repo}`,id:i.repositoryId,name:i.repo,owner:i.owner,private:!1},o=i.installationId??void 0;return{github:{installationId:o,repository:a,request(t){return callGitHubApi({api:r.api,body:t.body,credentials:r.credentials,installationId:o,method:t.method,path:t.path})}},thread:{kind:i.conversationKind,post(e){return i.conversationKind===`review_thread`?createGitHubReviewCommentReply({api:r.api,body:e,commentId:requiredStateNumber(i.reviewThreadRootCommentId??i.reviewCommentId,`reviewThreadRootCommentId`),credentials:r.credentials,installationId:o,owner:i.owner,pullRequestNumber:requiredStateNumber(i.pullRequestNumber,`pullRequestNumber`),repo:i.repo}):createGitHubIssueComment({api:r.api,body:e,credentials:r.credentials,installationId:o,issueNumber:requiredStateNumber(i.issueNumber??i.pullRequestNumber,`issueNumber`),owner:i.owner,repo:i.repo})},async react(e){let t=i.conversationKind===`review_thread`?i.reviewCommentId:i.triggeringCommentId;t!==null&&await createGitHubReaction({api:r.api,commentId:t,content:e,credentials:r.credentials,installationId:o,owner:i.owner,repo:i.repo,subject:i.conversationKind===`review_thread`?`pull_request_review_comment`:`issue_comment`})}}}}function requiredStateNumber(e,t){if(typeof e==`number`&&Number.isFinite(e))return e;throw Error(`githubChannel: missing ${t}.`)}export{buildGitHubBinding};

package/dist/src/public/channels/github/checkout.d.ts

@@ -0,0 +1,48 @@
+import { type GitHubApiOptions } from "#public/channels/github/api.js";
+import { type GitHubChannelCredentials } from "#public/channels/github/auth.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/** Options for cloning a GitHub repository ref into the active sandbox. */
+export interface GitHubCheckoutOptions {
+    readonly depth?: number;
+    readonly includeBase?: boolean;
+    readonly mode?: "full" | "shallow";
+    readonly path?: string;
+    readonly ref?: string;
+}
+/** Result returned after a GitHub checkout completes. */
+export interface GitHubCheckout {
+    readonly baseRef: string | null;
+    readonly path: string;
+    readonly ref: string;
+    readonly sha: string;
+}
+/** Internal descriptor used by channel-owned checkout paths. */
+export interface GitHubCheckoutInput extends GitHubCheckoutOptions {
+    readonly api?: GitHubApiOptions;
+    readonly baseRef?: string | null;
+    readonly baseSha?: string | null;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly defaultBranch?: string | null;
+    readonly headRef?: string | null;
+    readonly headSha?: string | null;
+    readonly installationId?: number | null;
+    readonly owner?: string;
+    readonly pullRequestNumber?: number | null;
+    readonly repo?: string;
+}
+/**
+ * Clones a described GitHub repository ref into the given sandbox.
+ *
+ * Runs on every turn via the channel's `turn.started` handler, which resolves
+ * the session sandbox from its `ctx` and passes it in. The sandbox persists for
+ * the session, so when the workspace is already at the target commit this is a
+ * no-op probe — no token is minted and nothing is fetched.
+ *
+ * The installation token is brokered at the sandbox firewall
+ * (`sandbox.setNetworkPolicy`) rather than embedded in the remote URL, so it
+ * never enters the sandbox process. Requires a firewall-capable backend; the
+ * local backend rejects `setNetworkPolicy`.
+ *
+ * Channel-internal; not part of the public GitHub channel API.
+ */
+export declare function checkoutGitHubRepository(sandbox: SandboxSession, input: GitHubCheckoutInput): Promise<GitHubCheckout>;

package/dist/src/public/channels/github/checkout.js

@@ -0,0 +1 @@
+import{resolveGitHubInstallationToken}from"#public/channels/github/auth.js";import{getGitHubPullRequest,getGitHubRepository}from"#public/channels/github/api.js";async function checkoutGitHubRepository(t,n){let r=await resolveCheckoutDescriptor(n),i=t.resolvePath(n.path??`/workspace`),a=resolveCheckoutRef(n.ref,r);if(isFullSha(a)){let e=await readCheckoutHead(t,i);if(e===a)return{baseRef:r.baseRef,path:i,ref:a,sha:e}}let o=normalizeCheckoutDepth(n.depth),s=n.mode===`full`?``:` --depth ${o}`,c=await resolveGitHubInstallationToken({api:n.api,credentials:n.credentials,installationId:r.installationId}),l=publicRemoteUrl({owner:r.owner,repo:r.repo}),u=isFullSha(a)?a:`FETCH_HEAD`;await t.setNetworkPolicy(buildBrokerNetworkPolicy(c)),await runCheckoutCommand({command:`mkdir -p ${shellQuote(i)}`,label:`create checkout directory`,sandbox:t}),await runCheckoutCommand({command:`cd ${shellQuote(i)} && git init`,label:`initialize git repository`,sandbox:t}),await runCheckoutCommand({command:`cd ${shellQuote(i)} && git remote remove origin >/dev/null 2>&1 || true`,label:`reset git remote`,sandbox:t}),await runCheckoutCommand({command:`cd ${shellQuote(i)} && git remote add origin ${shellQuote(l)}`,label:`configure git remote`,sandbox:t}),await runCheckoutCommand({command:`cd ${shellQuote(i)} && GIT_TERMINAL_PROMPT=0 git fetch${s} origin ${shellQuote(a)}`,label:`fetch GitHub ref`,sandbox:t}),await runCheckoutCommand({command:`cd ${shellQuote(i)} && git checkout --detach ${shellQuote(u)}`,label:`checkout GitHub ref`,sandbox:t}),n.includeBase===!0&&r.baseSha!==null&&await runCheckoutCommand({command:`cd ${shellQuote(i)} && GIT_TERMINAL_PROMPT=0 git fetch${s} origin ${shellQuote(r.baseSha)}`,label:`fetch GitHub base ref`,sandbox:t});let d=(await runCheckoutCommand({command:`cd ${shellQuote(i)} && git rev-parse HEAD`,label:`resolve checked out commit`,sandbox:t})).stdout.trim()||r.headSha||a;return{baseRef:r.baseRef,path:i,ref:a,sha:d}}async function resolveCheckoutDescriptor(e){let n=readNonEmptyString(e.owner),r=readNonEmptyString(e.repo);if(n===void 0||r===void 0)throw Error(`GitHub checkout requires a repository owner and name.`);if(e.installationId===void 0||e.installationId===null)throw Error(`GitHub checkout requires a GitHub App installation id.`);let i=e.pullRequestNumber??null,a=readNonEmptyString(e.ref),o=null;i!==null&&(a===void 0&&((e.headSha===void 0||e.headSha===null)&&(e.headRef===void 0||e.headRef===null)||e.defaultBranch===void 0||e.defaultBranch===null)||e.includeBase===!0&&(e.baseSha===void 0||e.baseSha===null)||e.includeBase===!0&&(e.baseRef===void 0||e.baseRef===null))&&(o=await getGitHubPullRequest({api:e.api,credentials:e.credentials,installationId:e.installationId,owner:n,pullRequestNumber:i,repo:r}));let s=readNonEmptyString(e.defaultBranch)??o?.defaultBranch??await resolveRepositoryDefaultBranch(e,{owner:n,pullRequestNumber:i,repo:r});return{baseRef:e.baseRef??o?.base.ref??null,baseSha:e.baseSha??o?.base.sha??null,defaultBranch:s,headRef:e.headRef??o?.head.ref??null,headSha:e.headSha??o?.head.sha??null,installationId:e.installationId,owner:n,pullRequestNumber:i,repo:r}}async function resolveRepositoryDefaultBranch(e,t){return t.pullRequestNumber!==null||readNonEmptyString(e.ref)!==void 0||readNonEmptyString(e.headSha)!==void 0||readNonEmptyString(e.headRef)!==void 0?null:(await getGitHubRepository({api:e.api,credentials:e.credentials,installationId:e.installationId??void 0,owner:t.owner,repo:t.repo})).defaultBranch??null}function resolveCheckoutRef(e,t){if(e!==void 0&&e.trim().length>0)return e.trim();if(t.headSha!==null)return t.headSha;if(t.pullRequestNumber!==null)return`refs/pull/${t.pullRequestNumber}/head`;if(t.headRef!==null)return t.headRef;if(t.defaultBranch!==null)return t.defaultBranch;throw Error(`GitHub checkout could not resolve a ref to fetch.`)}async function readCheckoutHead(e,t){let n=await e.run({command:`cd ${shellQuote(t)} && git rev-parse HEAD 2>/dev/null`});if(n.exitCode!==0)return null;let r=String(n.stdout??``).trim();return isFullSha(r)?r:null}async function runCheckoutCommand(e){let t=await e.sandbox.run({command:e.command}),n=String(t.stderr??``),r=String(t.stdout??``);if(t.exitCode===0)return{stderr:n,stdout:r};throw Error([`GitHub checkout failed during ${e.label} (exit ${t.exitCode}).`,n?`stderr: ${n}`:void 0,r?`stdout: ${r}`:void 0,`Verify the GitHub App installation has access to this repository.`].filter(e=>e!==void 0).join(` `))}function normalizeCheckoutDepth(e){if(e===void 0)return 1;if(!Number.isFinite(e)||e<1)throw Error(`GitHub checkout depth must be a positive number.`);return Math.floor(e)}function publicRemoteUrl(e){return`https://github.com/${e.owner}/${e.repo}.git`}function buildBrokerNetworkPolicy(e){let t=[{transform:[{headers:{Authorization:`Basic ${Buffer.from(`x-access-token:${e}`).toString(`base64`)}`}}]}];return{allow:{"github.com":t,"codeload.github.com":t,"*":[]}}}function readNonEmptyString(e){return typeof e==`string`&&e.trim().length>0?e.trim():void 0}function isFullSha(e){return/^[a-f0-9]{40}$/iu.test(e)}function shellQuote(e){return`'${e.replace(/'/gu,`'\\''`)}'`}export{checkoutGitHubRepository};

package/dist/src/public/channels/github/constants.d.ts

@@ -0,0 +1,2 @@
+/** Default route mounted by {@link githubChannel}. */
+export declare const GITHUB_CHANNEL_DEFAULT_ROUTE = "/ash/v1/github";

package/dist/src/public/channels/github/constants.js

@@ -0,0 +1 @@
+const GITHUB_CHANNEL_DEFAULT_ROUTE=`/ash/v1/github`;export{GITHUB_CHANNEL_DEFAULT_ROUTE};

package/dist/src/public/channels/github/defaults.d.ts

@@ -0,0 +1,21 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { GitHubApiOptions } from "#public/channels/github/api.js";
+import type { GitHubChannelCredentials } from "#public/channels/github/auth.js";
+import { type GitHubComment } from "#public/channels/github/inbound.js";
+import type { GitHubChannelEvents, GitHubInboundContext, GitHubInboundResult, GitHubProgressConfig } from "#public/channels/github/githubChannel.js";
+/** Projects a GitHub webhook actor into Ash session auth. */
+export declare function defaultGitHubAuth(ctx: GitHubInboundContext): SessionAuthContext;
+/** Options used by the built-in GitHub comment dispatch hook. */
+export interface GitHubDefaultDispatchOptions {
+    readonly botName?: string;
+}
+/** Default comment hook: dispatch only when the comment `@mention`s the bot. */
+export declare function defaultOnComment(ctx: GitHubInboundContext, comment: GitHubComment, options: GitHubDefaultDispatchOptions): GitHubInboundResult;
+/** Options used by built-in GitHub event handlers. */
+export interface GitHubDefaultEventOptions {
+    readonly api?: GitHubApiOptions;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly progress?: GitHubProgressConfig;
+}
+/** Builds GitHub's built-in event handlers for acknowledgement and terminal output. */
+export declare function createDefaultEvents(options?: GitHubDefaultEventOptions): GitHubChannelEvents;

package/dist/src/public/channels/github/defaults.js

@@ -0,0 +1,3 @@
+import{createLogger,extractErrorId,formatErrorHint,logError}from"#internal/logging.js";import{checkoutGitHubRepository}from"#public/channels/github/checkout.js";import{shouldDispatchGitHubComment}from"#public/channels/github/inbound.js";import{splitGitHubCommentBody}from"#public/channels/github/limits.js";const log=createLogger(`github.defaults`);function defaultGitHubAuth(e){let{sender:t}=e;return{attributes:{conversation_kind:e.conversation.kind,delivery_id:e.delivery.id,installation_id:String(e.github.installationId??``),issue_number:String(e.conversation.issueNumber??``),pull_request_number:String(e.conversation.pullRequestNumber??``),repository:e.repository.fullName,repository_id:String(e.repository.id),user_login:t.login,user_type:t.type},authenticator:`github-webhook`,issuer:`github:${e.repository.owner}`,principalId:`github:${t.id}`,principalType:t.type===`Bot`?`service`:`user`,subject:t.login}}function defaultOnComment(e,t,n){return shouldDispatchGitHubComment({author:t.author,body:t.body,botName:n.botName})?{auth:defaultGitHubAuth(e)}:null}function createDefaultEvents(e={}){return{async"turn.started"(t,n,i){if(e.progress?.reactions!==!1)try{await n.thread.react(`eyes`)}catch(e){logError(log,`GitHub reaction failed — swallowed`,e)}await checkoutRepositoryForTurn(n,i,e)},async"message.completed"(e,t,n){e.finishReason===`tool-calls`||!e.message||await postCommentChunks(t,e.message)},async"session.failed"(e,r){let i=formatErrorHint(e),a=extractErrorId(e.details);await postFailure(r,[`This session could not recover from an error${i}.`,``,`Start a new comment to continue.`,...a?[``,`Error id: ${a}`]:[]].join(`
+`))},async"turn.failed"(e,r,i){let a=formatErrorHint(e),o=extractErrorId(e.details);await postFailure(r,[`I hit an error while handling your request${a}.`,``,`Please try again, rephrase, or reach out if it keeps failing.`,...o?[``,`Error id: ${o}`]:[]].join(`
+`))}}}async function checkoutRepositoryForTurn(e,t,n){let{state:a}=e;try{let e=await checkoutGitHubRepository(await t.getSandbox(),{api:n.api,baseRef:a.baseRef,baseSha:a.baseSha,credentials:n.credentials,defaultBranch:a.defaultBranch,headRef:a.headRef,headSha:a.headSha,includeBase:a.pullRequestNumber!==null,installationId:a.installationId,owner:a.owner,pullRequestNumber:a.pullRequestNumber,repo:a.repo});a.checkoutPath=e.path,a.headSha=e.sha,a.baseRef=e.baseRef}catch(e){logError(log,`GitHub checkout failed — swallowed`,e)}}async function postCommentChunks(e,t){for(let n of splitGitHubCommentBody(t))await e.thread.post(n)}async function postFailure(e,t){await postCommentChunks(e,t)}export{createDefaultEvents,defaultGitHubAuth,defaultOnComment};

package/dist/src/public/channels/github/dispatch.d.ts

@@ -0,0 +1,34 @@
+import { type GitHubIssueCommentEvent, type GitHubIssueWebhookEvent, type GitHubPullRequestReviewCommentEvent, type GitHubPullRequestWebhookEvent } from "#public/channels/github/inbound.js";
+import { type GitHubChannelState } from "#public/channels/github/state.js";
+import type { GitHubChannelConfig } from "#public/channels/github/githubChannel.js";
+import type { SendFn } from "#public/definitions/defineChannel.js";
+/** Dispatches a bot-directed issue or PR timeline comment into the runtime. */
+export declare function dispatchIssueComment(input: {
+    readonly botName: string | undefined;
+    readonly config: GitHubChannelConfig;
+    readonly event: GitHubIssueCommentEvent;
+    readonly handler: NonNullable<GitHubChannelConfig["onComment"]>;
+    readonly send: SendFn<GitHubChannelState>;
+}): Promise<void>;
+/** Dispatches a bot-directed inline pull-request review comment. */
+export declare function dispatchPullRequestReviewComment(input: {
+    readonly botName: string | undefined;
+    readonly config: GitHubChannelConfig;
+    readonly event: GitHubPullRequestReviewCommentEvent;
+    readonly handler: NonNullable<GitHubChannelConfig["onComment"]>;
+    readonly send: SendFn<GitHubChannelState>;
+}): Promise<void>;
+/** Dispatches an opt-in issue webhook event into the runtime. */
+export declare function dispatchIssue(input: {
+    readonly config: GitHubChannelConfig;
+    readonly event: GitHubIssueWebhookEvent;
+    readonly handler: NonNullable<GitHubChannelConfig["onIssue"]>;
+    readonly send: SendFn<GitHubChannelState>;
+}): Promise<void>;
+/** Dispatches an opt-in pull-request webhook event into the runtime. */
+export declare function dispatchPullRequest(input: {
+    readonly config: GitHubChannelConfig;
+    readonly event: GitHubPullRequestWebhookEvent;
+    readonly handler: NonNullable<GitHubChannelConfig["onPullRequest"]>;
+    readonly send: SendFn<GitHubChannelState>;
+}): Promise<void>;

package/dist/src/public/channels/github/dispatch.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{extractGitHubCommentTrigger,formatGitHubContextBlock,prependGitHubContext}from"#public/channels/github/inbound.js";import{buildGitHubBinding}from"#public/channels/github/binding.js";import{buildGitHubPullRequestContext,mergeGitHubContext}from"#public/channels/github/pr-context.js";import{continuationTokenFromState,stateFromIssueCommentEvent,stateFromIssueEvent,stateFromPullRequestEvent,stateFromPullRequestReviewCommentEvent}from"#public/channels/github/state.js";const log=createLogger(`github.dispatch`);async function dispatchIssueComment(e){if(isIgnoredInboundComment(e.event.comment.body,e.event.comment.author,e.botName))return;let t=buildInboundContext(e.config,e.event);await dispatchCommentTurn({body:e.event.comment.body,botName:e.botName,commentUrl:e.event.comment.htmlUrl,event:e.event,handlerResult:()=>e.handler(t,toGitHubComment(e.event.comment)),config:e.config,send:e.send,state:stateFromIssueCommentEvent(e.event)})}async function dispatchPullRequestReviewComment(e){if(isIgnoredInboundComment(e.event.comment.body,e.event.comment.author,e.botName))return;let t=buildInboundContext(e.config,e.event);await dispatchCommentTurn({body:e.event.comment.body,botName:e.botName,commentUrl:e.event.comment.htmlUrl,event:e.event,handlerResult:()=>e.handler(t,toGitHubComment(e.event.comment)),config:e.config,send:e.send,state:stateFromPullRequestReviewCommentEvent(e.event)})}async function dispatchIssue(e){let t=buildInboundContext(e.config,e.event);await dispatchWebhookEventTurn({config:e.config,event:e.event,handlerResult:()=>e.handler(t,e.event.issue),message:formatIssueEventMessage(e.event),send:e.send,state:stateFromIssueEvent(e.event)})}async function dispatchPullRequest(e){let t=buildInboundContext(e.config,e.event);await dispatchWebhookEventTurn({config:e.config,event:e.event,handlerResult:()=>e.handler(t,e.event.pullRequest),message:formatPullRequestEventMessage(e.event),send:e.send,state:stateFromPullRequestEvent(e.event)})}async function dispatchWebhookEventTurn(e){let t=await runInboundHandler({event:e.event,handlerResult:e.handlerResult});t!=null&&await sendGitHubTurn({auth:t.auth,event:e.event,message:e.message,context:mergeGitHubContext({github:await buildPullRequestContext(e.config,e.state,e.event.delivery.id),hook:t.context}),send:e.send,state:e.state})}async function dispatchCommentTurn(e){let t=await runInboundHandler({event:e.event,handlerResult:e.handlerResult});if(t==null)return;let r=extractGitHubCommentTrigger({body:e.body,botName:e.botName})?.message??e.body.trim();await sendGitHubTurn({auth:t.auth,commentUrl:e.commentUrl,event:e.event,message:r,context:mergeGitHubContext({github:await buildPullRequestContext(e.config,e.state,e.event.delivery.id),hook:t.context}),send:e.send,state:e.state})}async function runInboundHandler(e){try{return await e.handlerResult()}catch(n){logError(log,`GitHub inbound handler failed`,n,{deliveryId:e.event.delivery.id});return}}async function sendGitHubTurn(e){let n=formatGitHubContextBlock({deliveryId:e.event.delivery.id,commentUrl:e.commentUrl,headSha:e.state.headSha,issueNumber:e.state.issueNumber,pullRequestNumber:e.state.pullRequestNumber,repository:e.event.repository,sender:e.event.sender}),i=prependGitHubContext(e.message,n);try{await e.send({message:i,context:e.context},{auth:e.auth,continuationToken:continuationTokenFromState(e.state),state:e.state})}catch(n){logError(log,e.logMessage??`GitHub delivery failed`,n,{deliveryId:e.event.delivery.id})}}async function buildPullRequestContext(e,n,r){try{return await buildGitHubPullRequestContext({api:e.api,config:e.pullRequestContext,credentials:e.credentials,installationId:n.installationId??void 0,owner:n.owner,pullRequestNumber:n.pullRequestNumber,repo:n.repo})}catch(e){logError(log,`GitHub pull-request context failed — swallowed`,e,{deliveryId:r});return}}function buildInboundContext(e,t){let n=buildGitHubBinding({config:e,state:t.kind===`issue_comment`?stateFromIssueCommentEvent(t):t.kind===`issues`?stateFromIssueEvent(t):t.kind===`pull_request`?stateFromPullRequestEvent(t):stateFromPullRequestReviewCommentEvent(t)});return{conversation:t.conversation,delivery:t.delivery,github:n.github,repository:t.repository,sender:t.sender,thread:n.thread}}function toGitHubComment(e){return{author:e.author,body:e.body,htmlUrl:e.htmlUrl,id:e.id,raw:e.raw,url:e.url}}function formatIssueEventMessage(e){let t=readString(e.issue.raw.title);return`Issue ${e.issue.action}: #${e.issue.issueNumber}${t?` ${t}`:``}`}function formatPullRequestEventMessage(e){let t=readString(e.pullRequest.raw.title);return`Pull request ${e.pullRequest.action}: #${e.pullRequest.pullRequestNumber}${t?` ${t}`:``}`}function isIgnoredInboundComment(e,t,n){if(e.includes(`<!-- ash:github:`)||t?.type===`Bot`)return!0;let r=n?`${n}[bot]`.toLowerCase():``;return r.length>0&&t?.login.toLowerCase()===r}function readString(e){return typeof e==`string`&&e.trim().length>0?e.trim():void 0}export{dispatchIssue,dispatchIssueComment,dispatchPullRequest,dispatchPullRequestReviewComment};

package/dist/src/public/channels/github/githubChannel.d.ts

@@ -0,0 +1,109 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { ChannelSessionOps } from "#public/definitions/defineChannel.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { type GitHubHandle, type GitHubThread } from "#public/channels/github/binding.js";
+import { type GitHubApiOptions } from "#public/channels/github/api.js";
+import type { GitHubChannelCredentials } from "#public/channels/github/auth.js";
+import { type GitHubComment, type GitHubConversationRef, type GitHubDelivery, type GitHubIssueEvent, type GitHubPullRequestEvent, type GitHubRepositoryRef, type GitHubUser } from "#public/channels/github/inbound.js";
+import { type GitHubChannelState } from "#public/channels/github/state.js";
+import type { GitHubPullRequestContextConfig } from "#public/channels/github/pr-context.js";
+import { type Channel } from "#public/definitions/defineChannel.js";
+type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
+    type: T;
+}> extends {
+    data: infer D;
+} ? D : undefined;
+/** Target accepted by `receive(github, { target })` for proactive sessions. */
+export interface GitHubReceiveTarget {
+    readonly initialMessage?: string;
+    readonly installationId?: number;
+    readonly issueNumber?: number;
+    readonly owner: string;
+    readonly pullRequestNumber?: number;
+    /** Optional shortcut that avoids a repository metadata API call. */
+    readonly repositoryId?: number;
+    readonly repo: string;
+}
+/** Optional acknowledgement progress surfaces for GitHub conversations. */
+export interface GitHubProgressConfig {
+    readonly reactions?: boolean;
+}
+/** Pre-dispatch GitHub context passed to inbound hooks. */
+export interface GitHubInboundContext {
+    readonly conversation: GitHubConversationRef;
+    readonly delivery: GitHubDelivery;
+    readonly github: GitHubHandle;
+    readonly repository: GitHubRepositoryRef;
+    readonly sender: GitHubUser;
+    readonly thread: GitHubThread;
+}
+/** Channel-owned GitHub context rebuilt from persisted channel state. */
+export interface GitHubChannelContext {
+    readonly conversation: GitHubConversationRef;
+    readonly github: GitHubHandle;
+    readonly repository: GitHubRepositoryRef;
+    readonly thread: GitHubThread;
+    state: GitHubChannelState;
+}
+/** Event-handler GitHub context, including session operations. */
+export interface GitHubEventContext extends GitHubChannelContext, ChannelSessionOps {
+}
+/** Result of a GitHub inbound hook. Return `null` to acknowledge without dispatching. */
+export type GitHubInboundResult = {
+    readonly auth: SessionAuthContext | null;
+    readonly context?: readonly string[];
+} | null;
+/** Sync or async {@link GitHubInboundResult}. */
+export type GitHubInboundResultOrPromise = GitHubInboundResult | Promise<GitHubInboundResult>;
+type GitHubEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, channel: GitHubEventContext, ctx: SessionContext) => void | Promise<void>;
+type GitHubSessionFailedHandler = (data: EventData<"session.failed">, channel: GitHubEventContext) => void | Promise<void>;
+/** Event handlers supported by `githubChannel({ events })`. */
+export interface GitHubChannelEvents {
+    readonly "action.result"?: GitHubEventHandler<"action.result">;
+    readonly "actions.requested"?: GitHubEventHandler<"actions.requested">;
+    readonly "authorization.completed"?: GitHubEventHandler<"authorization.completed">;
+    readonly "authorization.required"?: GitHubEventHandler<"authorization.required">;
+    readonly "input.requested"?: GitHubEventHandler<"input.requested">;
+    readonly "message.appended"?: GitHubEventHandler<"message.appended">;
+    readonly "message.completed"?: GitHubEventHandler<"message.completed">;
+    readonly "session.completed"?: GitHubEventHandler<"session.completed">;
+    readonly "session.failed"?: GitHubSessionFailedHandler;
+    readonly "session.waiting"?: GitHubEventHandler<"session.waiting">;
+    readonly "turn.completed"?: GitHubEventHandler<"turn.completed">;
+    readonly "turn.failed"?: GitHubEventHandler<"turn.failed">;
+    readonly "turn.started"?: GitHubEventHandler<"turn.started">;
+}
+/** Configuration for {@link githubChannel}. */
+export interface GitHubChannelConfig {
+    readonly api?: GitHubApiOptions;
+    readonly botName?: string;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly events?: GitHubChannelEvents;
+    readonly progress?: GitHubProgressConfig;
+    readonly pullRequestContext?: GitHubPullRequestContextConfig;
+    readonly route?: string;
+    /**
+     * Invoked for every `@mention` of the bot in an issue/PR timeline comment or
+     * an inline review comment. `ctx.conversation.kind` distinguishes the surface.
+     * Return `{ auth }` to dispatch or `null` to ignore. Replacing this fully
+     * replaces the default mention gate.
+     */
+    onComment?(ctx: GitHubInboundContext, comment: GitHubComment): GitHubInboundResultOrPromise;
+    /**
+     * Opt-in handler for `issues` webhook events. There is no default dispatch —
+     * define this to act on issues (e.g. `issue.action === "opened"`).
+     */
+    onIssue?(ctx: GitHubInboundContext, issue: GitHubIssueEvent): GitHubInboundResultOrPromise;
+    /**
+     * Opt-in handler for `pull_request` webhook events. There is no default
+     * dispatch — define this to act on PRs (e.g. `pullRequest.action === "opened"`).
+     */
+    onPullRequest?(ctx: GitHubInboundContext, pullRequest: GitHubPullRequestEvent): GitHubInboundResultOrPromise;
+}
+/** Concrete return type of {@link githubChannel}. */
+export interface GitHubChannel extends Channel<GitHubChannelState, GitHubReceiveTarget> {
+}
+/** GitHub channel factory for GitHub App webhooks and proactive comments. */
+export declare function githubChannel(config?: GitHubChannelConfig): GitHubChannel;
+export {};

package/dist/src/public/channels/github/githubChannel.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{getGitHubRepository}from"#public/channels/github/api.js";import{parseGitHubWebhookEvent}from"#public/channels/github/inbound.js";import{buildGitHubBinding}from"#public/channels/github/binding.js";import{continuationTokenFromState,conversationFromState,initialGitHubState,stateFromReceiveTarget}from"#public/channels/github/state.js";import{GITHUB_CHANNEL_DEFAULT_ROUTE}from"#public/channels/github/constants.js";import{createDefaultEvents,defaultOnComment}from"#public/channels/github/defaults.js";import{dispatchIssue,dispatchIssueComment,dispatchPullRequest,dispatchPullRequestReviewComment}from"#public/channels/github/dispatch.js";import{verifyGitHubRequest}from"#public/channels/github/verify.js";const log=createLogger(`github.channel`);function githubChannel(e={}){let s=e.botName??process.env.GITHUB_APP_SLUG,u={botName:s},d={...createDefaultEvents({api:e.api,credentials:e.credentials,progress:e.progress}),...e.events};return defineChannel({kindHint:`github`,state:initialGitHubState(),context(t,n){return rebuildGitHubContext(t,n,e)},routes:[POST(e.route??GITHUB_CHANNEL_DEFAULT_ROUTE,async(t,{send:n,waitUntil:r})=>{let a=await verifyInbound(t,e.credentials);if(a===null)return new Response(`unauthorized`,{status:401});let o;try{o=parseGitHubWebhookEvent({body:a,contentType:t.headers.get(`content-type`)??void 0,headers:t.headers})}catch(e){return log.warn(`inbound GitHub body is not valid JSON`,{error:e}),jsonOk({ignored:!0,ok:!0})}return o===null?jsonOk({ignored:!0,ok:!0}):o.kind===`ping`?jsonOk({ok:!0}):o.kind===`issue_comment`&&o.action===`created`?(r(dispatchIssueComment({botName:s,config:e,event:o,handler:e.onComment??((e,t)=>defaultOnComment(e,t,u)),send:n})),jsonOk({ok:!0})):o.kind===`pull_request_review_comment`&&o.action===`created`?(r(dispatchPullRequestReviewComment({botName:s,config:e,event:o,handler:e.onComment??((e,t)=>defaultOnComment(e,t,u)),send:n})),jsonOk({ok:!0})):o.kind===`issues`&&e.onIssue!==void 0?(r(dispatchIssue({config:e,event:o,handler:e.onIssue,send:n})),jsonOk({ok:!0})):o.kind===`pull_request`&&e.onPullRequest!==void 0?(r(dispatchPullRequest({config:e,event:o,handler:e.onPullRequest,send:n})),jsonOk({ok:!0})):jsonOk({ignored:!0,ok:!0})})],async receive(t,{send:n}){let i=t.target,s=readNonEmptyString(i.owner),c=readNonEmptyString(i.repo);if(s===void 0||c===void 0)throw Error(`githubChannel().receive requires target.owner and target.repo.`);if([i.issueNumber!==void 0,i.pullRequestNumber!==void 0].filter(Boolean).length!==1)throw Error(`githubChannel().receive requires exactly one of issueNumber or pullRequestNumber.`);let l=stateFromReceiveTarget({target:i,owner:s,repo:c,repositoryId:i.repositoryId??(await getGitHubRepository({api:e.api,credentials:e.credentials,installationId:i.installationId,owner:s,repo:c})).id});if(i.initialMessage!==void 0){let{thread:t}=buildGitHubBinding({config:e,state:l});await t.post(i.initialMessage)}return n(t.message,{auth:t.auth,continuationToken:continuationTokenFromState(l),state:l})},events:d})}function rebuildGitHubContext(e,t,n){let r=buildGitHubBinding({config:n,state:e});return{conversation:conversationFromState(e),github:r.github,repository:r.github.repository,state:e,thread:r.thread}}async function verifyInbound(e,t){try{return await verifyGitHubRequest(e,{webhookSecret:t?.webhookSecret,webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`github inbound verification failed`,{error:e}),null}}function readNonEmptyString(e){return typeof e==`string`&&e.length>0?e:void 0}function jsonOk(e){return new Response(JSON.stringify(e),{headers:{"content-type":`application/json; charset=utf-8`},status:200})}export{githubChannel};