experimental-ash 0.55.3 → 0.57.0

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};

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

@@ -0,0 +1,183 @@
+import type { UserContent } from "ai";
+import { type JsonObject } from "#shared/json.js";
+/** GitHub conversation kinds represented by the channel state. */
+export type GitHubConversationKind = "issue" | "pull_request" | "review_thread";
+/** Stable repository identity normalized from webhook payloads. */
+export interface GitHubRepositoryRef {
+    readonly fullName: string;
+    readonly id: number;
+    readonly name: string;
+    readonly owner: string;
+    readonly private: boolean;
+}
+/** GitHub actor metadata normalized from webhook payloads. */
+export interface GitHubUser {
+    readonly htmlUrl: string | undefined;
+    readonly id: number;
+    readonly login: string;
+    readonly type: string;
+    readonly url: string | undefined;
+}
+/** Verified GitHub webhook delivery headers. */
+export interface GitHubDelivery {
+    readonly event: string;
+    readonly hookId: string | undefined;
+    readonly id: string;
+}
+/** Channel-local conversation reference. */
+export interface GitHubConversationRef {
+    readonly issueNumber: number | null;
+    readonly kind: GitHubConversationKind;
+    readonly pullRequestNumber: number | null;
+}
+/**
+ * Normalized GitHub comment handed to the `onComment` hook. Covers issue and PR
+ * timeline comments and inline review comments alike; `ctx.conversation.kind`
+ * distinguishes them.
+ */
+export interface GitHubComment {
+    readonly author: GitHubUser | undefined;
+    readonly body: string;
+    readonly htmlUrl: string | undefined;
+    readonly id: number;
+    readonly raw: JsonObject;
+    readonly url: string | undefined;
+}
+/** Normalized issue/PR timeline comment. */
+export interface GitHubIssueComment {
+    readonly author: GitHubUser | undefined;
+    readonly body: string;
+    readonly htmlUrl: string | undefined;
+    readonly id: number;
+    readonly issueNumber: number;
+    readonly pullRequestNumber: number | null;
+    readonly raw: JsonObject;
+    readonly url: string | undefined;
+}
+/** Normalized inline pull-request review comment. */
+export interface GitHubPullRequestReviewComment {
+    readonly author: GitHubUser | undefined;
+    readonly body: string;
+    readonly htmlUrl: string | undefined;
+    readonly id: number;
+    readonly inReplyToId: number | null;
+    readonly pullRequestNumber: number;
+    readonly raw: JsonObject;
+    readonly reviewThreadRootCommentId: number;
+    readonly url: string | undefined;
+}
+/**
+ * Common `issues` webhook actions, kept open to any action GitHub sends so
+ * authors get autocomplete without losing forward compatibility.
+ */
+export type GitHubIssueAction = "assigned" | "closed" | "edited" | "labeled" | "opened" | "reopened" | "unassigned" | "unlabeled" | (string & {});
+/** Common `pull_request` webhook actions, kept open to any action GitHub sends. */
+export type GitHubPullRequestAction = "closed" | "edited" | "labeled" | "opened" | "ready_for_review" | "reopened" | "synchronize" | "unlabeled" | (string & {});
+/** Normalized issue event payload. */
+export interface GitHubIssueEvent {
+    readonly action: GitHubIssueAction;
+    readonly issueNumber: number;
+    readonly raw: JsonObject;
+}
+/** Normalized pull-request event payload. */
+export interface GitHubPullRequestEvent {
+    readonly action: GitHubPullRequestAction;
+    readonly headSha: string | null;
+    readonly pullRequestNumber: number;
+    readonly raw: JsonObject;
+}
+export interface GitHubPingEvent extends GitHubInboundEventBase {
+    readonly kind: "ping";
+}
+export interface GitHubIssueCommentEvent extends GitHubInboundEventBase {
+    readonly action: string;
+    readonly baseRef: string | null;
+    readonly baseSha: string | null;
+    readonly comment: GitHubIssueComment;
+    readonly conversation: GitHubConversationRef;
+    readonly defaultBranch: string | null;
+    readonly headRef: string | null;
+    readonly headSha: string | null;
+    readonly kind: "issue_comment";
+}
+export interface GitHubPullRequestReviewCommentEvent extends GitHubInboundEventBase {
+    readonly action: string;
+    readonly baseRef: string | null;
+    readonly baseSha: string | null;
+    readonly comment: GitHubPullRequestReviewComment;
+    readonly conversation: GitHubConversationRef;
+    readonly defaultBranch: string | null;
+    readonly headRef: string | null;
+    readonly headSha: string | null;
+    readonly kind: "pull_request_review_comment";
+}
+export interface GitHubIssueWebhookEvent extends GitHubInboundEventBase {
+    readonly action: string;
+    readonly conversation: GitHubConversationRef;
+    readonly issue: GitHubIssueEvent;
+    readonly kind: "issues";
+}
+export interface GitHubPullRequestWebhookEvent extends GitHubInboundEventBase {
+    readonly action: string;
+    readonly baseRef: string | null;
+    readonly baseSha: string | null;
+    readonly conversation: GitHubConversationRef;
+    readonly defaultBranch: string | null;
+    readonly headRef: string | null;
+    readonly headSha: string | null;
+    readonly kind: "pull_request";
+    readonly pullRequest: GitHubPullRequestEvent;
+}
+interface GitHubInboundEventBase {
+    readonly delivery: GitHubDelivery;
+    readonly installationId: number | undefined;
+    readonly raw: JsonObject;
+    readonly repository: GitHubRepositoryRef;
+    readonly sender: GitHubUser;
+}
+/** Parsed GitHub webhook event shape consumed by the channel. */
+export type GitHubInboundEvent = GitHubIssueCommentEvent | GitHubIssueWebhookEvent | GitHubPingEvent | GitHubPullRequestReviewCommentEvent | GitHubPullRequestWebhookEvent;
+/** Parsed mention trigger for a bot-directed GitHub comment. */
+export interface GitHubCommentTrigger {
+    readonly kind: "mention";
+    readonly message: string;
+    readonly token: string;
+}
+/** Builds the channel-local continuation token for a GitHub conversation. */
+export declare function githubContinuationToken(input: {
+    readonly conversationKind: GitHubConversationKind;
+    readonly issueNumber?: number | null;
+    readonly pullRequestNumber?: number | null;
+    readonly repositoryId: number;
+    readonly reviewThreadRootCommentId?: number | null;
+}): string;
+/** Returns true when a comment @mentions the bot and should wake the channel. */
+export declare function shouldDispatchGitHubComment(input: {
+    readonly author?: GitHubUser;
+    readonly body: string;
+    readonly botName?: string;
+}): boolean;
+/** Extracts and strips the bot `@mention` from a comment body. */
+export declare function extractGitHubCommentTrigger(input: {
+    readonly body: string;
+    readonly botName?: string;
+}): GitHubCommentTrigger | null;
+/** Parses GitHub webhook headers and body into an Ash-owned event shape. */
+export declare function parseGitHubWebhookEvent(input: {
+    readonly body: string;
+    readonly contentType?: string;
+    readonly headers: Headers;
+}): GitHubInboundEvent | null;
+/** Renders deterministic GitHub metadata for the model-visible turn. */
+export declare function formatGitHubContextBlock(input: {
+    readonly commentUrl?: string;
+    readonly deliveryId: string;
+    readonly headSha?: string | null;
+    readonly issueNumber?: number | null;
+    readonly pullRequestNumber?: number | null;
+    readonly repository: GitHubRepositoryRef;
+    readonly sender: GitHubUser;
+}): string;
+/** Prepends a `<github_context>` block to the inbound turn message. */
+export declare function prependGitHubContext(message: string | UserContent, block: string): string | UserContent;
+export {};

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

@@ -0,0 +1,2 @@
+import{isObject}from"#shared/guards.js";import{parseJsonObject}from"#shared/json.js";function githubContinuationToken(e){return e.conversationKind===`issue`?`repo:${e.repositoryId}:issue:${requiredNumber(e.issueNumber,`issueNumber`)}`:e.conversationKind===`pull_request`?`repo:${e.repositoryId}:pull:${requiredNumber(e.pullRequestNumber,`pullRequestNumber`)}`:`repo:${e.repositoryId}:pull:${requiredNumber(e.pullRequestNumber,`pullRequestNumber`)}:review-comment:${requiredNumber(e.reviewThreadRootCommentId,`reviewThreadRootCommentId`)}`}function shouldDispatchGitHubComment(e){return isIgnoredGitHubComment(e.body,e.author,e.botName)?!1:extractGitHubCommentTrigger(e)!==null}function extractGitHubCommentTrigger(e){let t=e.botName?.trim();if(!t)return null;let n=RegExp(`@${escapeRegExp(t)}(?=$|[^A-Za-z0-9_-])`,`iu`).exec(e.body);if(n===null)return null;let r=n.index,i=r+n[0].length;return{kind:`mention`,message:`${e.body.slice(0,r)}${e.body.slice(i)}`.trim(),token:n[0]}}function parseGitHubWebhookEvent(e){let t=e.headers.get(`x-github-event`)??``,n=e.headers.get(`x-github-delivery`)??``;if(!t||!n)return null;let r=decodePayload(e.body,e.contentType),i=normalizeRepository(r.repository),a=normalizeUser(r.sender);if(i===null||a===void 0)return null;let o={delivery:{event:t,hookId:e.headers.get(`x-github-hook-id`)??void 0,id:n},installationId:readInstallationId(r.installation),raw:r,repository:i,sender:a};return t===`ping`?{...o,kind:`ping`}:t===`issue_comment`?parseIssueCommentEvent(o):t===`pull_request_review_comment`?parsePullRequestReviewCommentEvent(o):t===`issues`?parseIssueEvent(o):t===`pull_request`?parsePullRequestEvent(o):null}function formatGitHubContextBlock(e){return[`<github_context>`,`repository: ${e.repository.fullName}`,`repository_id: ${e.repository.id}`,...e.issueNumber!==void 0&&e.issueNumber!==null?[`issue_number: ${e.issueNumber}`]:[],...e.pullRequestNumber!==void 0&&e.pullRequestNumber!==null?[`pull_request_number: ${e.pullRequestNumber}`]:[],`sender: ${e.sender.login}`,`sender_type: ${e.sender.type}`,...e.commentUrl?[`comment_url: ${e.commentUrl}`]:[],...e.headSha?[`head_sha: ${e.headSha}`]:[],`delivery_id: ${e.deliveryId}`,`</github_context>`].join(`
+`)}function prependGitHubContext(e,t){return typeof e==`string`?e.length>0?`${t}\n\n${e}`:t:[{text:t,type:`text`},...e]}function parseIssueCommentEvent(n){let r=isObject(n.raw.issue)?n.raw.issue:null,i=isObject(n.raw.comment)?parseJsonObject(n.raw.comment):null,a=typeof r?.number==`number`?r.number:void 0;if(i===null||r===null||a===void 0)return null;let o=isObject(r.pull_request)?a:null,s=readAction(n.raw),c={author:normalizeUser(i.user),body:typeof i.body==`string`?i.body:``,htmlUrl:typeof i.html_url==`string`?i.html_url:void 0,id:typeof i.id==`number`?i.id:0,issueNumber:a,pullRequestNumber:o,raw:i,url:typeof i.url==`string`?i.url:void 0};return{...n,action:s,baseRef:null,baseSha:null,comment:c,conversation:{issueNumber:a,kind:o===null?`issue`:`pull_request`,pullRequestNumber:o},defaultBranch:null,headRef:null,headSha:null,kind:`issue_comment`}}function parsePullRequestReviewCommentEvent(n){let r=isObject(n.raw.comment)?parseJsonObject(n.raw.comment):null,i=isObject(n.raw.pull_request)?n.raw.pull_request:null,a=typeof i?.number==`number`?i.number:void 0;if(r===null||a===void 0)return null;let o=typeof r.id==`number`?r.id:0,s=typeof r.in_reply_to_id==`number`?r.in_reply_to_id:null,c={author:normalizeUser(r.user),body:typeof r.body==`string`?r.body:``,htmlUrl:typeof r.html_url==`string`?r.html_url:void 0,id:o,inReplyToId:s,pullRequestNumber:a,raw:r,reviewThreadRootCommentId:s??o,url:typeof r.url==`string`?r.url:void 0};return{...n,action:readAction(n.raw),baseRef:readPullRequestBaseRef(i),baseSha:readPullRequestBaseSha(i),comment:c,conversation:{issueNumber:null,kind:`review_thread`,pullRequestNumber:a},defaultBranch:readPullRequestDefaultBranch(i),headRef:readPullRequestHeadRef(i),headSha:readPullRequestHeadSha(i),kind:`pull_request_review_comment`}}function parseIssueEvent(n){let r=isObject(n.raw.issue)?n.raw.issue:null,i=typeof r?.number==`number`?r.number:void 0;return i===void 0?null:{...n,action:readAction(n.raw),conversation:{issueNumber:i,kind:`issue`,pullRequestNumber:null},issue:{action:readAction(n.raw),issueNumber:i,raw:parseJsonObject(r)},kind:`issues`}}function parsePullRequestEvent(n){let r=isObject(n.raw.pull_request)?n.raw.pull_request:null,i=typeof r?.number==`number`?r.number:void 0;return i===void 0?null:{...n,action:readAction(n.raw),baseRef:readPullRequestBaseRef(r),baseSha:readPullRequestBaseSha(r),conversation:{issueNumber:null,kind:`pull_request`,pullRequestNumber:i},defaultBranch:readPullRequestDefaultBranch(r),headRef:readPullRequestHeadRef(r),headSha:readPullRequestHeadSha(r),kind:`pull_request`,pullRequest:{action:readAction(n.raw),headSha:readPullRequestHeadSha(r),pullRequestNumber:i,raw:parseJsonObject(r)}}}function decodePayload(e,n){if(n?.includes(`application/x-www-form-urlencoded`)===!0){let n=new URLSearchParams(e).get(`payload`)??``;return parseJsonObject(JSON.parse(n))}return parseJsonObject(JSON.parse(e))}function normalizeRepository(t){if(!isObject(t))return null;let n=typeof t.full_name==`string`?t.full_name:``,[r=``,i=``]=n.split(`/`),a=isObject(t.owner)?t.owner:{},o=typeof a.login==`string`?a.login:r,s=typeof t.name==`string`?t.name:i,c=typeof t.id==`number`?t.id:0;return!o||!s?null:{fullName:n||`${o}/${s}`,id:c,name:s,owner:o,private:t.private===!0}}function normalizeUser(t){if(!isObject(t))return;let n=typeof t.login==`string`?t.login:``;if(n)return{htmlUrl:typeof t.html_url==`string`?t.html_url:void 0,id:typeof t.id==`number`?t.id:0,login:n,type:typeof t.type==`string`?t.type:`User`,url:typeof t.url==`string`?t.url:void 0}}function readInstallationId(t){if(isObject(t))return typeof t.id==`number`?t.id:void 0}function readAction(e){return typeof e.action==`string`?e.action:``}function readPullRequestHeadSha(t){let n=isObject(t?.head)?t.head:null;return typeof n?.sha==`string`?n.sha:null}function readPullRequestHeadRef(t){let n=isObject(t?.head)?t.head:null;return typeof n?.ref==`string`?n.ref:null}function readPullRequestBaseRef(t){let n=isObject(t?.base)?t.base:null;return typeof n?.ref==`string`?n.ref:null}function readPullRequestBaseSha(t){let n=isObject(t?.base)?t.base:null;return typeof n?.sha==`string`?n.sha:null}function readPullRequestDefaultBranch(t){let n=isObject(t?.base)?t.base:null,r=isObject(n?.repo)?n.repo:null;return typeof r?.default_branch==`string`?r.default_branch:null}function isIgnoredGitHubComment(e,t,n){if(e.includes(`<!-- ash:github:`))return!0;if(t===void 0)return!1;if(t.type===`Bot`)return!0;let r=n?`${n}[bot]`.toLowerCase():``;return r.length>0&&t.login.toLowerCase()===r}function requiredNumber(e,t){if(typeof e==`number`&&Number.isFinite(e))return e;throw Error(`githubContinuationToken requires ${t}.`)}function escapeRegExp(e){return e.replace(/[.*+?^${}()|[\]\\]/gu,`\\$&`)}export{extractGitHubCommentTrigger,formatGitHubContextBlock,githubContinuationToken,parseGitHubWebhookEvent,prependGitHubContext,shouldDispatchGitHubComment};

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

@@ -0,0 +1,9 @@
+export { GitHubApiError, type GitHubApiMethod, type GitHubApiOptions, type GitHubApiResponse, type GitHubJsonObject, type GitHubPostedComment, type GitHubReactionContent, } from "#public/channels/github/api.js";
+export { type GitHubHandle, type GitHubThread } from "#public/channels/github/binding.js";
+export { type GitHubAppId, type GitHubChannelCredentials, type GitHubInstallationToken, type GitHubPrivateKey, type GitHubWebhookSecret, } from "#public/channels/github/auth.js";
+export { defaultGitHubAuth } from "#public/channels/github/defaults.js";
+export { type GitHubComment, type GitHubConversationKind, type GitHubConversationRef, type GitHubDelivery, type GitHubIssueAction, type GitHubIssueEvent, type GitHubPullRequestAction, type GitHubPullRequestEvent, type GitHubRepositoryRef, type GitHubUser, } from "#public/channels/github/inbound.js";
+export { githubChannel, type GitHubChannel, type GitHubChannelConfig, type GitHubChannelEvents, type GitHubEventContext, type GitHubInboundContext, type GitHubInboundResult, type GitHubInboundResultOrPromise, type GitHubProgressConfig, type GitHubReceiveTarget, } from "#public/channels/github/githubChannel.js";
+export { GITHUB_DEFAULT_EXCLUDED_DIFF_FILES, type GitHubPullRequestContextConfig, } from "#public/channels/github/pr-context.js";
+export { type GitHubChannelState } from "#public/channels/github/state.js";
+export { type GitHubWebhookVerifier } from "#public/channels/github/verify.js";

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

@@ -0,0 +1 @@
+import{GitHubApiError}from"#public/channels/github/api.js";import{GITHUB_DEFAULT_EXCLUDED_DIFF_FILES}from"#public/channels/github/pr-context.js";import{defaultGitHubAuth}from"#public/channels/github/defaults.js";import{githubChannel}from"#public/channels/github/githubChannel.js";export{GITHUB_DEFAULT_EXCLUDED_DIFF_FILES,GitHubApiError,defaultGitHubAuth,githubChannel};