eve 0.5.4 → 0.6.0-beta.3

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

@@ -0,0 +1,126 @@
+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.
+ * Requires `owner`, `repo`, and exactly one of `issueNumber` or
+ * `pullRequestNumber`; supplying both numbers or neither throws.
+ */
+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; return `{ auth }` to dispatch. Optional `context` strings are
+ * added as `role: "user"` messages before the dispatched turn.
+ */
+export type GitHubInboundResult = {
+    readonly auth: SessionAuthContext | null;
+    readonly context?: readonly string[];
+} | null;
+/**
+ * Return type of the `onComment`/`onIssue`/`onPullRequest` hooks: a
+ * {@link GitHubInboundResult} or a promise for one.
+ */
+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 for `githubChannel({ events })`. The channel installs built-in
+ * handlers for `turn.started` (eyes reaction plus repo checkout),
+ * `message.completed` (posts the reply), and `session.failed`/`turn.failed`
+ * (posts an error comment). A handler supplied here replaces the built-in for
+ * that key rather than running alongside it.
+ */
+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. 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 Eve-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(`<!-- eve: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};

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

@@ -0,0 +1,4 @@
+/** Maximum body length accepted by GitHub issue and pull-request comments. */
+export declare const GITHUB_COMMENT_BODY_MAX_LENGTH = 65536;
+/** Splits a long comment body into GitHub-sized comment bodies. */
+export declare function splitGitHubCommentBody(body: string, maxLength?: number): readonly string[];

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

@@ -0,0 +1,2 @@
+const GITHUB_COMMENT_BODY_MAX_LENGTH=65536;function splitGitHubCommentBody(t,n=GITHUB_COMMENT_BODY_MAX_LENGTH){if(t.length<=n)return[t];let r=[],i=t;for(;i.length>n;){let e=findCommentSplitIndex(i,n);r.push(i.slice(0,e).trimEnd()),i=i.slice(e).trimStart()}return i.length>0&&r.push(i),r}function findCommentSplitIndex(e,t){let n=e.lastIndexOf(`
+`,t);if(n>t*.5)return n;let r=e.lastIndexOf(` `,t);return r>t*.5?r:t}export{GITHUB_COMMENT_BODY_MAX_LENGTH,splitGitHubCommentBody};

package/dist/src/public/channels/github/pr-context.d.ts

@@ -0,0 +1,46 @@
+import { type GitHubApiOptions } from "#public/channels/github/api.js";
+import type { GitHubChannelCredentials } from "#public/channels/github/auth.js";
+/**
+ * Built-in glob patterns excluded from the diff loaded into model context.
+ *
+ * These files are large and generated; their patch text seldom helps the model
+ * and consumes context budget. They are still listed with their stats so the
+ * agent knows they changed, and the full file is always available from the
+ * checkout.
+ */
+export declare const GITHUB_DEFAULT_EXCLUDED_DIFF_FILES: readonly string[];
+/** Controls the pull-request diff injected into GitHub-triggered turns. */
+export interface GitHubPullRequestContextConfig {
+    /**
+     * Additional glob patterns excluded from the diff loaded into model context.
+     * Extends the built-in {@link GITHUB_DEFAULT_EXCLUDED_DIFF_FILES} list; it
+     * does not replace it. Excluded files are still listed with their stats; only
+     * the patch body is omitted.
+     */
+    readonly excludedFiles?: readonly string[];
+}
+/** Input for building one-shot model context for a pull request. */
+export interface GitHubPullRequestContextInput {
+    readonly api?: GitHubApiOptions;
+    readonly config?: GitHubPullRequestContextConfig;
+    readonly credentials?: GitHubChannelCredentials;
+    readonly installationId?: number;
+    readonly owner: string;
+    readonly pullRequestNumber: number | null;
+    readonly repo: string;
+}
+/**
+ * Builds bounded, one-shot pull-request background for a GitHub turn: PR
+ * metadata plus the changed-file diff (noisy files excluded from the patch).
+ *
+ * The returned strings are intended for `SendPayload.context`; each is appended
+ * as a `role: "user"` message to session history before the delivery message.
+ */
+export declare function buildGitHubPullRequestContext(input: GitHubPullRequestContextInput): Promise<readonly string[] | undefined>;
+/** Merges channel-generated PR context before hook-provided context. */
+export declare function mergeGitHubContext(input: {
+    readonly github?: readonly string[];
+    readonly hook?: readonly string[];
+}): readonly string[] | undefined;
+/** Returns true when a file path matches any of the provided glob patterns. */
+export declare function fileMatchesAnyGlob(filename: string, patterns: readonly string[]): boolean;

package/dist/src/public/channels/github/pr-context.js

@@ -0,0 +1,5 @@
+import{getGitHubPullRequest,listGitHubPullRequestFiles}from"#public/channels/github/api.js";const MAX_PATCH_BYTES=2e4,GITHUB_DEFAULT_EXCLUDED_DIFF_FILES=[`**/pnpm-lock.yaml`,`**/package-lock.json`,`**/npm-shrinkwrap.json`,`**/yarn.lock`,`**/bun.lockb`,`**/Cargo.lock`,`**/go.sum`,`**/poetry.lock`,`**/Pipfile.lock`,`**/uv.lock`,`**/composer.lock`,`**/Gemfile.lock`,`**/*.min.js`,`**/*.min.css`,`**/*.map`,`**/*.snap`];async function buildGitHubPullRequestContext(n){if(n.pullRequestNumber===null)return;let i=renderPullRequestMetadata(await getGitHubPullRequest({api:n.api,credentials:n.credentials,installationId:n.installationId,owner:n.owner,pullRequestNumber:n.pullRequestNumber,repo:n.repo})),a=await listGitHubPullRequestFiles({api:n.api,credentials:n.credentials,installationId:n.installationId,owner:n.owner,perPage:50,pullRequestNumber:n.pullRequestNumber,repo:n.repo}),o=[...GITHUB_DEFAULT_EXCLUDED_DIFF_FILES,...n.config?.excludedFiles??[]];return i.push(``,...renderPullRequestFiles(a,o)),[[`GitHub pull request context for the current turn. `,`Use this as background for the user's GitHub comment.`,``,i.join(`
+`)].join(`
+`)]}function mergeGitHubContext(e){let t=e.github??[],n=e.hook??[];if(!(t.length===0&&n.length===0))return[...t,...n]}function renderPullRequestMetadata(e){return[`<github_pull_request>`,`number: ${e.number}`,`title: ${e.title}`,`state: ${e.state??`unknown`}`,`draft: ${e.draft?`true`:`false`}`,...e.author?.login?[`author: ${e.author.login}`]:[],...e.htmlUrl?[`url: ${e.htmlUrl}`]:[],...e.base.ref?[`base_ref: ${e.base.ref}`]:[],...e.base.sha?[`base_sha: ${e.base.sha}`]:[],...e.head.ref?[`head_ref: ${e.head.ref}`]:[],...e.head.sha?[`head_sha: ${e.head.sha}`]:[],...e.mergeable===null||e.mergeable===void 0?[]:[`mergeable: ${e.mergeable?`true`:`false`}`],...e.changedFiles===void 0?[]:[`changed_files: ${e.changedFiles}`],...e.additions===void 0?[]:[`additions: ${e.additions}`],...e.deletions===void 0?[]:[`deletions: ${e.deletions}`],...e.body?[``,`body:`,indent(truncateText(e.body,4e3))]:[],`</github_pull_request>`]}function renderPullRequestFiles(e,t){if(e.length===0)return[`<github_pull_request_files>`,`none`,`</github_pull_request_files>`];let r=[`<github_pull_request_files>`],i=MAX_PATCH_BYTES,a=!1;for(let n of e){if(r.push(renderFileSummary(n)),fileMatchesAnyGlob(n.filename,t)){r.push(`  patch omitted (excluded)`);continue}if(n.patch===void 0)continue;if(i<=0){a=!0;continue}let e=truncateByBytes(n.patch,i);r.push(`patch:`,indent(e.text)),i-=e.bytes,e.truncated&&(a=!0,i=0)}return a&&r.push(``,`patches_truncated: true`,`max_patch_bytes: ${MAX_PATCH_BYTES}`),r.push(`</github_pull_request_files>`),r}function renderFileSummary(e){let t=[e.status??`modified`,e.additions===void 0?void 0:`+${e.additions}`,e.deletions===void 0?void 0:`-${e.deletions}`].filter(e=>e!==void 0);return`- ${e.filename}${t.length>0?` (${t.join(`, `)})`:``}`}function fileMatchesAnyGlob(e,t){return t.some(t=>globToRegExp(t).test(e))}function globToRegExp(e){let t=``;for(let n=0;n<e.length;n+=1){let r=e.charAt(n);r===`*`?e[n+1]===`*`?(t+=`.*`,n+=1,e[n+1]===`/`&&(n+=1)):t+=`[^/]*`:`\\^$.|?+()[]{}`.includes(r)?t+=`\\${r}`:t+=r}return RegExp(`^${t}$`,`u`)}function truncateByBytes(e,t){let n=new TextEncoder().encode(e);return n.byteLength<=t?{bytes:n.byteLength,text:e,truncated:!1}:{bytes:t,text:`${new TextDecoder().decode(n.slice(0,t))}\n[truncated]`,truncated:!0}}function truncateText(e,t){return e.length<=t?e:`${e.slice(0,t)}\n[truncated]`}function indent(e){return e.split(`
+`).map(e=>`  ${e}`).join(`
+`)}export{GITHUB_DEFAULT_EXCLUDED_DIFF_FILES,buildGitHubPullRequestContext,fileMatchesAnyGlob,mergeGitHubContext};

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

@@ -0,0 +1,60 @@
+import { type GitHubConversationKind, type GitHubConversationRef, type GitHubIssueCommentEvent, type GitHubIssueWebhookEvent, type GitHubPullRequestReviewCommentEvent, type GitHubPullRequestWebhookEvent } from "#public/channels/github/inbound.js";
+/**
+ * Durable, mutable per-conversation GitHub channel state, persisted as JSON.
+ *
+ * Which fields are populated depends on `conversationKind`: `review_thread`
+ * state sets `reviewCommentId`/`reviewThreadRootCommentId`, issue and PR
+ * timeline comments set `triggeringCommentId`, and issue/PR conversations set
+ * `issueNumber`/`pullRequestNumber`. See the `stateFrom*` builders for the
+ * exact mapping per kind.
+ *
+ * The checkout-derived fields (`checkoutPath`, `headSha`, `baseRef`) start
+ * null. The default `turn.started` handler fills them in once it checks out
+ * the repository, which is why the fields are mutable.
+ */
+export interface GitHubChannelState {
+    baseRef: string | null;
+    baseSha: string | null;
+    checkoutPath: string | null;
+    conversationKind: GitHubConversationKind;
+    defaultBranch: string | null;
+    headRef: string | null;
+    headSha: string | null;
+    installationId: number | null;
+    issueNumber: number | null;
+    owner: string;
+    pullRequestNumber: number | null;
+    repo: string;
+    repositoryId: number;
+    reviewCommentId: number | null;
+    reviewThreadRootCommentId: number | null;
+    triggeringCommentId: number | null;
+    triggeringUserLogin: string | null;
+}
+/** Minimal receive target needed to seed GitHub channel state. */
+export interface GitHubReceiveStateTarget {
+    readonly installationId?: number;
+    readonly issueNumber?: number;
+    readonly pullRequestNumber?: number;
+}
+/** Initial empty GitHub channel state. */
+export declare function initialGitHubState(): GitHubChannelState;
+/** Builds state for an issue or PR timeline comment. */
+export declare function stateFromIssueCommentEvent(event: GitHubIssueCommentEvent): GitHubChannelState;
+/** Builds state for an inline pull-request review comment. */
+export declare function stateFromPullRequestReviewCommentEvent(event: GitHubPullRequestReviewCommentEvent): GitHubChannelState;
+/** Builds state for an issue event hook dispatch. */
+export declare function stateFromIssueEvent(event: GitHubIssueWebhookEvent): GitHubChannelState;
+/** Builds state for a pull-request event hook dispatch. */
+export declare function stateFromPullRequestEvent(event: GitHubPullRequestWebhookEvent): GitHubChannelState;
+/** Builds state for proactive `receive()` calls. */
+export declare function stateFromReceiveTarget(input: {
+    readonly target: GitHubReceiveStateTarget;
+    readonly owner: string;
+    readonly repo: string;
+    readonly repositoryId: number;
+}): GitHubChannelState;
+/** Reconstructs the channel-local GitHub conversation reference from state. */
+export declare function conversationFromState(state: GitHubChannelState): GitHubConversationRef;
+/** Builds the channel-local continuation token from durable state. */
+export declare function continuationTokenFromState(state: GitHubChannelState): string;

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

@@ -0,0 +1 @@
+import{githubContinuationToken}from"#public/channels/github/inbound.js";function initialGitHubState(){return{baseRef:null,baseSha:null,checkoutPath:null,conversationKind:`issue`,defaultBranch:null,headRef:null,headSha:null,installationId:null,issueNumber:null,owner:``,pullRequestNumber:null,repo:``,repositoryId:0,reviewCommentId:null,reviewThreadRootCommentId:null,triggeringCommentId:null,triggeringUserLogin:null}}function stateFromIssueCommentEvent(e){return{...initialGitHubState(),baseRef:e.baseRef,baseSha:e.baseSha,conversationKind:e.conversation.kind,defaultBranch:e.defaultBranch,headRef:e.headRef,headSha:e.headSha,installationId:e.installationId??null,issueNumber:e.comment.issueNumber,owner:e.repository.owner,pullRequestNumber:e.comment.pullRequestNumber,repo:e.repository.name,repositoryId:e.repository.id,triggeringCommentId:e.comment.id,triggeringUserLogin:e.sender.login}}function stateFromPullRequestReviewCommentEvent(e){return{...initialGitHubState(),baseRef:e.baseRef,baseSha:e.baseSha,conversationKind:`review_thread`,defaultBranch:e.defaultBranch,headRef:e.headRef,headSha:e.headSha,installationId:e.installationId??null,owner:e.repository.owner,pullRequestNumber:e.comment.pullRequestNumber,repo:e.repository.name,repositoryId:e.repository.id,reviewCommentId:e.comment.id,reviewThreadRootCommentId:e.comment.reviewThreadRootCommentId,triggeringCommentId:e.comment.id,triggeringUserLogin:e.sender.login}}function stateFromIssueEvent(e){return{...initialGitHubState(),conversationKind:`issue`,installationId:e.installationId??null,issueNumber:e.issue.issueNumber,owner:e.repository.owner,repo:e.repository.name,repositoryId:e.repository.id,triggeringUserLogin:e.sender.login}}function stateFromPullRequestEvent(e){return{...initialGitHubState(),baseRef:e.baseRef,baseSha:e.baseSha,conversationKind:`pull_request`,defaultBranch:e.defaultBranch,headRef:e.headRef,headSha:e.headSha,installationId:e.installationId??null,issueNumber:e.pullRequest.pullRequestNumber,owner:e.repository.owner,pullRequestNumber:e.pullRequest.pullRequestNumber,repo:e.repository.name,repositoryId:e.repository.id,triggeringUserLogin:e.sender.login}}function stateFromReceiveTarget(e){let{target:t}=e,n=t.pullRequestNumber===void 0?`issue`:`pull_request`;return{...initialGitHubState(),conversationKind:n,installationId:t.installationId??null,issueNumber:n===`issue`?t.issueNumber??null:t.pullRequestNumber??null,owner:e.owner,pullRequestNumber:t.pullRequestNumber??null,repo:e.repo,repositoryId:e.repositoryId}}function conversationFromState(e){return{issueNumber:e.issueNumber,kind:e.conversationKind,pullRequestNumber:e.pullRequestNumber}}function continuationTokenFromState(t){return githubContinuationToken({conversationKind:t.conversationKind,issueNumber:t.issueNumber,pullRequestNumber:t.pullRequestNumber,repositoryId:t.repositoryId,reviewThreadRootCommentId:t.reviewThreadRootCommentId})}export{continuationTokenFromState,conversationFromState,initialGitHubState,stateFromIssueCommentEvent,stateFromIssueEvent,stateFromPullRequestEvent,stateFromPullRequestReviewCommentEvent,stateFromReceiveTarget};

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

@@ -0,0 +1,35 @@
+import { type GitHubWebhookSecret } from "#public/channels/github/auth.js";
+/**
+ * Caller-supplied inbound webhook verifier. Use it as an alternative to HMAC
+ * verification. For example, Connect supplies a verifier that authenticates
+ * Connect-forwarded webhooks with Vercel OIDC instead of GitHub's webhook
+ * secret.
+ *
+ * Contract (matches the other channels' `webhookVerifier`):
+ *
+ * - **Throw / reject** → the channel responds 401 to GitHub.
+ * - **Return a falsy value** (`null` / `undefined` / `false` / `""` / `0`)
+ *   → the channel responds 401 to GitHub. This lets verifiers signal
+ *   rejection without throwing. For example, Connect's `vercelOidc()` returns
+ *   `null` on a failed OIDC check.
+ * - **Return a truthy non-string value** → verification accepted.
+ * - **Return a string** → verification accepted, and the string replaces
+ *   the raw body for downstream parsing.
+ */
+export type GitHubWebhookVerifier = (request: Request, body: string) => unknown | Promise<unknown>;
+/** Options for {@link verifyGitHubRequest}. */
+export interface GitHubVerifyOptions {
+    readonly webhookSecret?: GitHubWebhookSecret;
+    readonly webhookVerifier?: GitHubWebhookVerifier;
+}
+/**
+ * Verifies a GitHub webhook request and returns its raw body. The raw body is
+ * required because GitHub signs the exact bytes it delivered.
+ *
+ * When a {@link GitHubWebhookVerifier} is supplied, it replaces the built-in
+ * HMAC check: GitHub's webhook secret is never read and the verifier owns the
+ * accept/reject decision.
+ */
+export declare function verifyGitHubRequest(request: Request, options: GitHubVerifyOptions): Promise<string>;
+/** Signs a raw GitHub webhook body for tests and local fixtures. */
+export declare function signGitHubWebhookBody(body: string, secret: string): string;

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

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{createHmac,timingSafeEqual}from"node:crypto";import{resolveGitHubWebhookSecret}from"#public/channels/github/auth.js";const log=createLogger(`github.verify`);async function verifyGitHubRequest(e,t){let n=await e.text();if(t.webhookVerifier!==void 0){let r=await t.webhookVerifier(e,n);if(!r)throw Error(`githubChannel: inbound webhook verifier rejected the request.`);return typeof r==`string`?r:n}let i=await resolveGitHubWebhookSecret(t.webhookSecret),a=e.headers.get(`x-hub-signature-256`)??``;if(!a)throw Error(`githubChannel: inbound request missing X-Hub-Signature-256.`);if(!constantTimeCompare(signGitHubWebhookBody(n,i),a))throw Error(`githubChannel: inbound request signature mismatch.`);return n}function signGitHubWebhookBody(e,n){return`sha256=${createHmac(`sha256`,n).update(e).digest(`hex`)}`}function constantTimeCompare(e,t){if(e.length!==t.length)return!1;try{return timingSafeEqual(Buffer.from(e),Buffer.from(t))}catch(e){return log.debug(`timingSafeEqual threw`,{error:e}),!1}}export{signGitHubWebhookBody,verifyGitHubRequest};

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

@@ -0,0 +1,89 @@
+export { defineChannel, GET, POST, PUT, PATCH, DELETE, WS, type Channel, type ChannelDefinition, type ChannelSessionOps, type ChannelEvents, type InferChannelMetadata, type Session, type SessionHandle, type RouteDefinition, type RouteHandlerArgs, type SendFn, type SendOptions, type SendPayload, type GetSessionFn, type HttpRouteDefinition, type WebSocketMessage, type WebSocketPeer, type WebSocketRouteDefinition, type WebSocketRouteHandler, type WebSocketRouteHooks, type WebSocketUpgradeRequest, type WebSocketUpgradeResult, } from "#public/definitions/defineChannel.js";
+export { createWebSocketUpgradeServer, type WebSocketUpgradeServerBridge, } from "#channel/websocket-upgrade-server.js";
+import type { Channel } from "#public/definitions/defineChannel.js";
+/**
+ * Base channel metadata shape used by framework channel kinds.
+ */
+export type InstrumentationChannelMetadata = Readonly<Record<string, unknown>>;
+/**
+ * Channel metadata projections keyed by channel kind.
+ *
+ * Built-in channel packages ship declaration-merged entries (e.g. Slack
+ * ships `"channel:slack"`). The Eve compiler generates entries for
+ * authored channels at build time.
+ */
+export interface ChannelMetadataMap {
+    readonly http: InstrumentationChannelMetadata;
+    readonly schedule: InstrumentationChannelMetadata;
+    readonly subagent: InstrumentationChannelMetadata;
+    readonly unknown: InstrumentationChannelMetadata;
+    readonly "channel:slack": import("#public/channels/slack/slackChannel.js").SlackInstrumentationMetadata;
+    readonly "channel:discord": import("#public/channels/discord/index.js").DiscordInstrumentationMetadata;
+    readonly "channel:twilio": import("#public/channels/twilio/twilioChannel.js").TwilioInstrumentationMetadata;
+    readonly "channel:teams": import("#public/channels/teams/index.js").TeamsInstrumentationMetadata;
+    readonly "channel:telegram": import("#public/channels/telegram/index.js").TelegramInstrumentationMetadata;
+    readonly "channel:linear": import("#public/channels/linear/index.js").LinearInstrumentationMetadata;
+}
+/**
+ * Union of all known channel kind discriminators (the keys of
+ * {@link ChannelMetadataMap}): the framework kinds `"http"`, `"schedule"`,
+ * `"subagent"`, and `"unknown"`, plus a `"channel:<slug>"` entry for each
+ * built-in and compiler-generated authored channel.
+ */
+export type InstrumentationChannelKind = keyof ChannelMetadataMap;
+/**
+ * Channel values keyed by path-derived channel kind.
+ *
+ * Entries are generated by the Eve compiler for authored channels.
+ * Built-in channel entries are declared inline above.
+ * Used by {@link isChannel} to resolve a channel value to its kind string.
+ */
+export interface ChannelReferenceMap {
+    readonly "channel:slack": import("#public/channels/slack/slackChannel.js").SlackChannel;
+    readonly "channel:discord": import("#public/channels/discord/discordChannel.js").DiscordChannel;
+    readonly "channel:twilio": import("#public/channels/twilio/twilioChannel.js").TwilioChannel;
+    readonly "channel:teams": import("#public/channels/teams/teamsChannel.js").TeamsChannel;
+    readonly "channel:telegram": import("#public/channels/telegram/telegramChannel.js").TelegramChannel;
+    readonly "channel:linear": import("#public/channels/linear/linearChannel.js").LinearChannel;
+}
+/**
+ * One arm of {@link InstrumentationChannel}: a channel of kind `K` paired with
+ * its matching {@link ChannelMetadataMap} metadata projection.
+ */
+export interface InstrumentationChannelForKind<K extends InstrumentationChannelKind> {
+    readonly kind: K;
+    readonly metadata: ChannelMetadataMap[K];
+}
+/**
+ * Discriminated union over every {@link InstrumentationChannelKind}, each arm
+ * carrying its `kind` string and matching `metadata`. This is the channel shape
+ * instrumentation callbacks receive as `input.channel`; narrow it with
+ * {@link isChannel}.
+ */
+export type InstrumentationChannel = {
+    readonly [K in InstrumentationChannelKind]: InstrumentationChannelForKind<K>;
+}[InstrumentationChannelKind];
+type ChannelReferenceKind<TChannel> = {
+    readonly [K in keyof ChannelReferenceMap]: [TChannel] extends [ChannelReferenceMap[K]] ? [ChannelReferenceMap[K]] extends [TChannel] ? K : never : never;
+}[keyof ChannelReferenceMap];
+/**
+ * The {@link InstrumentationChannel} arm matching the app-owned channel value
+ * `TChannel`, resolved through its compiler-derived `channel:<slug>` identity in
+ * {@link ChannelReferenceMap}. Used as the narrowed type produced by
+ * {@link isChannel}.
+ */
+export type InstrumentationChannelForChannel<TChannel> = Extract<InstrumentationChannel, {
+    readonly kind: Extract<ChannelReferenceKind<TChannel>, InstrumentationChannelKind>;
+}>;
+/**
+ * Narrows a channel by comparing it to an app-owned channel value imported
+ * from `agent/channels/*`.
+ *
+ * Works with both instrumentation resolver inputs (`input.channel`) and
+ * dynamic resolver inputs (`ctx.channel`). The comparison uses the
+ * compiler's path-derived `channel:<slug>` identity. Metadata narrows to
+ * the channel's declared `ChannelMetadataMap` entry on success.
+ */
+export declare function isChannel<TChannel extends Channel<any, any, any>>(channel: InstrumentationChannel | {
+    readonly kind?: string;
+}, target: TChannel): channel is InstrumentationChannelForChannel<TChannel>;

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

@@ -0,0 +1 @@
+import{getChannelInstrumentationKind}from"#channel/compiled-channel.js";import{DELETE,GET,PATCH,POST,PUT,WS,defineChannel}from"#public/definitions/defineChannel.js";import{createWebSocketUpgradeServer}from"#channel/websocket-upgrade-server.js";function isChannel(e,t){return e.kind===getChannelInstrumentationKind(t)}export{DELETE,GET,PATCH,POST,PUT,WS,createWebSocketUpgradeServer,defineChannel,isChannel};