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

Filesystem-first framework for durable backend AI agents that run anywhere.

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