@cursor/july 0.1.1

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

@@ -0,0 +1,73 @@
+/**
+ * Rebuild GitHub API + thread handles for inbound hooks and stream events.
+ */
+import type { Octokit } from "@octokit/rest";
+import { type GitHubApiMethod, type GitHubApiOptions, type GitHubApiResponse, type GitHubJsonObject, type GitHubPostedComment, type GitHubReactionContent } from "./api.js";
+import type { GitHubChannelCredentials, GitHubConversationKind, GitHubRepositoryRef } from "./types.js";
+/** Hidden marker on outbound GitHub comments so inbound dispatch ignores them. */
+export declare const GITHUB_OUTBOUND_MARKER = "<!-- agent-serve-github -->";
+export declare function formatGitHubOutboundComment(body: string): string;
+export interface GitHubBindingConfig {
+    api?: GitHubApiOptions;
+    credentials?: GitHubChannelCredentials;
+}
+/** Serializable fields needed to rebuild handles. */
+export interface GitHubBindingState {
+    conversationKind: GitHubConversationKind;
+    installationId: number | null;
+    issueNumber: number | null;
+    owner: string;
+    pullRequestNumber: number | null;
+    repo: string;
+    repositoryId: number | null;
+    reviewCommentId: number | null;
+    reviewThreadRootCommentId: number | null;
+    triggeringCommentId: number | null;
+}
+/** GitHub operations exposed to hooks (`ctx.github`). */
+export interface GitHubHandle {
+    installationId: number | undefined;
+    repository: GitHubRepositoryRef;
+    /**
+     * Authenticated `@octokit/rest` client. Prefer typed `octokit.rest.*`
+     * methods for new code; keep {@link request} / {@link createStatus} for
+     * thin wrappers and host-side tasks.
+     */
+    getOctokit(): Promise<Octokit>;
+    /**
+     * Call an arbitrary GitHub REST path with channel auth (PAT / App /
+     * `gh auth token`). Prefer {@link getOctokit} for typed calls.
+     */
+    request<T = unknown>(input: {
+        body?: GitHubJsonObject;
+        method: GitHubApiMethod;
+        path: string;
+    }): Promise<GitHubApiResponse<T>>;
+    /** Create a commit status on `sha`. */
+    createStatus(input: {
+        sha: string;
+        state: "error" | "failure" | "pending" | "success";
+        context?: string;
+        description?: string;
+        targetUrl?: string;
+    }): Promise<GitHubApiResponse>;
+}
+/** Thread-scoped operations for the current conversation (`ctx.thread`). */
+export interface GitHubThread {
+    kind: GitHubConversationKind;
+    /** Post a reply on the issue/PR timeline or review thread. */
+    post(message: string): Promise<GitHubPostedComment>;
+    /**
+     * React to the triggering comment. No-ops when there is no comment to
+     * react to (e.g. a PR-opened delivery).
+     */
+    react(content: GitHubReactionContent): Promise<void>;
+}
+export declare function buildGitHubBinding(input: {
+    config: GitHubBindingConfig;
+    state: GitHubBindingState;
+}): {
+    github: GitHubHandle;
+    thread: GitHubThread;
+};
+//# sourceMappingURL=binding.d.ts.map

package/dist/channels/github/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../../src/channels/github/binding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACxC;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE;QAC1B,IAAI,CAAC,EAAE,gBAAgB,CAAC;QACxB,MAAM,EAAE,eAAe,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,uCAAuC;IACvC,YAAY,CAAC,KAAK,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,8DAA8D;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACpD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,kBAAkB,CAAC;CAC3B,GAAG;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAkHjD"}

package/dist/channels/github/binding.js

@@ -0,0 +1,114 @@
+/**
+ * Rebuild GitHub API + thread handles for inbound hooks and stream events.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { callGitHubApi, createGitHubCommitStatus, createGitHubIssueComment, createGitHubOctokit, createGitHubReaction, createGitHubReviewCommentReply, } from "./api.js";
+/** Hidden marker on outbound GitHub comments so inbound dispatch ignores them. */
+export const GITHUB_OUTBOUND_MARKER = "<!-- agent-serve-github -->";
+export function formatGitHubOutboundComment(body) {
+    if (body.includes(GITHUB_OUTBOUND_MARKER)) {
+        return body;
+    }
+    return `${body.trimEnd()}\n\n${GITHUB_OUTBOUND_MARKER}`;
+}
+export function buildGitHubBinding(input) {
+    var _a;
+    const { config, state } = input;
+    const repository = Object.assign({ fullName: `${state.owner}/${state.repo}`, url: `https://github.com/${state.owner}/${state.repo}`, owner: state.owner, name: state.repo }, (state.repositoryId === null ? {} : { id: state.repositoryId }));
+    const installationId = (_a = state.installationId) !== null && _a !== void 0 ? _a : undefined;
+    let octokitPromise;
+    const getOctokit = () => {
+        octokitPromise !== null && octokitPromise !== void 0 ? octokitPromise : (octokitPromise = createGitHubOctokit({
+            api: config.api,
+            credentials: config.credentials,
+            installationId,
+        }));
+        return octokitPromise;
+    };
+    const github = {
+        installationId,
+        repository,
+        getOctokit,
+        request(req) {
+            return callGitHubApi({
+                api: config.api,
+                body: req.body,
+                credentials: config.credentials,
+                installationId,
+                method: req.method,
+                path: req.path,
+            });
+        },
+        createStatus(status) {
+            return createGitHubCommitStatus(Object.assign(Object.assign(Object.assign({ api: config.api, credentials: config.credentials, installationId, owner: state.owner, repo: state.repo, sha: status.sha, state: status.state }, (status.context === undefined ? {} : { context: status.context })), (status.description === undefined
+                ? {}
+                : { description: status.description })), (status.targetUrl === undefined
+                ? {}
+                : { targetUrl: status.targetUrl })));
+        },
+    };
+    const thread = {
+        kind: state.conversationKind,
+        post(message) {
+            var _a, _b;
+            if (state.conversationKind === "review_thread") {
+                return createGitHubReviewCommentReply({
+                    api: config.api,
+                    body: message,
+                    commentId: requiredNumber((_a = state.reviewThreadRootCommentId) !== null && _a !== void 0 ? _a : state.reviewCommentId, "reviewThreadRootCommentId"),
+                    credentials: config.credentials,
+                    installationId,
+                    owner: state.owner,
+                    pullRequestNumber: requiredNumber(state.pullRequestNumber, "pullRequestNumber"),
+                    repo: state.repo,
+                });
+            }
+            return createGitHubIssueComment({
+                api: config.api,
+                body: message,
+                credentials: config.credentials,
+                installationId,
+                issueNumber: requiredNumber((_b = state.issueNumber) !== null && _b !== void 0 ? _b : state.pullRequestNumber, "issueNumber"),
+                owner: state.owner,
+                repo: state.repo,
+            });
+        },
+        react(content) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const commentId = state.conversationKind === "review_thread"
+                    ? state.reviewCommentId
+                    : state.triggeringCommentId;
+                if (commentId === null) {
+                    return;
+                }
+                yield createGitHubReaction({
+                    api: config.api,
+                    commentId,
+                    content,
+                    credentials: config.credentials,
+                    installationId,
+                    owner: state.owner,
+                    repo: state.repo,
+                    subject: state.conversationKind === "review_thread"
+                        ? "pull_request_review_comment"
+                        : "issue_comment",
+                });
+            });
+        },
+    };
+    return { github, thread };
+}
+function requiredNumber(value, name) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    throw new Error(`githubChannel: missing ${name}.`);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Default stream-event handlers for the GitHub channel.
+ */
+import type { ChannelEventHandlers } from "../../types.js";
+import type { GitHubBindingConfig } from "./binding.js";
+import type { GitHubChannelState } from "./state.js";
+export interface GitHubProgressConfig {
+    /** When false, skip the eyes reaction on turn.started. Defaults to true. */
+    reactions?: boolean;
+}
+export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
+    progress?: GitHubProgressConfig;
+    /**
+     * When false, skip posting completed assistant messages back to GitHub.
+     * Defaults to true.
+     */
+    deliverReplies?: boolean;
+}
+/**
+ * Built-in delivery: eyes reaction on turn start, post assistant text on
+ * `message.completed`, and a short error comment on turn/session failure.
+ */
+export declare function buildDefaultGitHubEvents(options?: BuildDefaultGitHubEventsOptions): ChannelEventHandlers<GitHubChannelState>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/channels/github/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/channels/github/defaults.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,+BAAgC,SAAQ,mBAAmB;IAC1E,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,+BAAoC,GAC5C,oBAAoB,CAAC,kBAAkB,CAAC,CAmD1C"}

package/dist/channels/github/defaults.js

@@ -0,0 +1,100 @@
+/**
+ * Default stream-event handlers for the GitHub channel.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { buildGitHubBinding, formatGitHubOutboundComment } from "./binding.js";
+/**
+ * Built-in delivery: eyes reaction on turn start, post assistant text on
+ * `message.completed`, and a short error comment on turn/session failure.
+ */
+export function buildDefaultGitHubEvents(options = {}) {
+    const deliverReplies = options.deliverReplies !== false;
+    return {
+        "turn.started"(_event, channel) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                if (((_a = options.progress) === null || _a === void 0 ? void 0 : _a.reactions) === false) {
+                    return;
+                }
+                if (channel.state.owner === "" || channel.state.repo === "") {
+                    return;
+                }
+                try {
+                    const { thread } = buildGitHubBinding({
+                        config: options,
+                        state: channel.state,
+                    });
+                    yield thread.react("eyes");
+                }
+                catch (_b) {
+                    // Soft-fail: missing token / no triggering comment is fine.
+                }
+            });
+        },
+        "message.completed"(event, channel) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (!deliverReplies) {
+                    return;
+                }
+                if (event.data.finishReason === "tool_call" || event.data.text === "") {
+                    return;
+                }
+                if (channel.state.owner === "" || channel.state.repo === "") {
+                    return;
+                }
+                try {
+                    const { thread } = buildGitHubBinding({
+                        config: options,
+                        state: channel.state,
+                    });
+                    yield thread.post(formatGitHubOutboundComment(event.data.text));
+                }
+                catch (_a) {
+                    // Soft-fail delivery so a missing token does not crash the session.
+                }
+            });
+        },
+        "turn.failed"(event, channel) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield postFailure(channel, options, event.data.message);
+            });
+        },
+        "session.failed"(event, channel) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield postFailure(channel, options, event.data.message);
+            });
+        },
+    };
+}
+function postFailure(channel, options, _error) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (options.deliverReplies === false) {
+            return;
+        }
+        if (channel.state.owner === "" || channel.state.repo === "") {
+            return;
+        }
+        try {
+            const { thread } = buildGitHubBinding({
+                config: options,
+                state: channel.state,
+            });
+            yield thread.post(formatGitHubOutboundComment([
+                "I hit an error while handling your request.",
+                "",
+                "Please try again, or reach out if it keeps failing.",
+            ].join("\n")));
+        }
+        catch (_a) {
+            // Soft-fail.
+        }
+    });
+}

package/dist/channels/github/events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Webhook event derivation for the GitHub channel.
+ *
+ * `agent-serve github forward` reads the set of webhook events a channel is
+ * wired to dispatch (published as `meta.githubWebhookEvents`) so it can build
+ * `gh webhook forward --events=…` without the operator hand-listing them.
+ */
+import type { GitHubChannelOptions } from "./types.js";
+/** {@link ChannelMeta.kind} value used by {@link githubChannel}. */
+export declare const GITHUB_CHANNEL_KIND = "github";
+/**
+ * Derive the webhook events a {@link githubChannel} dispatches on from its
+ * declared hooks. When {@link GitHubChannelOptions.webhookEvents} is set it is
+ * authoritative and returned verbatim (deduped, order preserved) — use it to
+ * pin an exact list (e.g. to add events only handled via `onEvent`).
+ */
+export declare function deriveGitHubWebhookEvents(options: GitHubChannelOptions): string[];
+//# sourceMappingURL=events.d.ts.map

package/dist/channels/github/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/channels/github/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAkC5C;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,oBAAoB,GAC5B,MAAM,EAAE,CAcV"}

package/dist/channels/github/events.js

@@ -0,0 +1,59 @@
+/**
+ * Webhook event derivation for the GitHub channel.
+ *
+ * `agent-serve github forward` reads the set of webhook events a channel is
+ * wired to dispatch (published as `meta.githubWebhookEvents`) so it can build
+ * `gh webhook forward --events=…` without the operator hand-listing them.
+ */
+/** {@link ChannelMeta.kind} value used by {@link githubChannel}. */
+export const GITHUB_CHANNEL_KIND = "github";
+/**
+ * Events the channel always parses through its built-in defaults: the
+ * `pull_request` gate and the `@mention` comment gates exist even when no
+ * hook is declared.
+ */
+const BASE_WEBHOOK_EVENTS = [
+    "pull_request",
+    "issue_comment",
+    "pull_request_review_comment",
+];
+/** Typed opt-in hooks and the webhook event each subscribes to. */
+const OPT_IN_HOOK_EVENTS = [
+    { option: "onIssue", event: "issues" },
+    { option: "onCheckSuite", event: "check_suite" },
+    { option: "onCheckRun", event: "check_run" },
+    { option: "onWorkflowRun", event: "workflow_run" },
+    { option: "onStatus", event: "status" },
+];
+/**
+ * Common events that only reach the `onEvent` catch-all (no typed hook). When
+ * `onEvent` is declared we forward these too so review activity is delivered.
+ */
+const CATCH_ALL_EVENTS = [
+    "pull_request_review",
+    "pull_request_review_thread",
+];
+/**
+ * Derive the webhook events a {@link githubChannel} dispatches on from its
+ * declared hooks. When {@link GitHubChannelOptions.webhookEvents} is set it is
+ * authoritative and returned verbatim (deduped, order preserved) — use it to
+ * pin an exact list (e.g. to add events only handled via `onEvent`).
+ */
+export function deriveGitHubWebhookEvents(options) {
+    if (options.webhookEvents !== undefined) {
+        return dedupe(options.webhookEvents);
+    }
+    const events = [...BASE_WEBHOOK_EVENTS];
+    for (const { option, event } of OPT_IN_HOOK_EVENTS) {
+        if (options[option] !== undefined) {
+            events.push(event);
+        }
+    }
+    if (options.onEvent !== undefined) {
+        events.push(...CATCH_ALL_EVENTS);
+    }
+    return dedupe(events);
+}
+function dedupe(events) {
+    return [...new Set(events.map((event) => event.trim()).filter(Boolean))];
+}

package/dist/channels/github/forward.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Planning helpers for `agent-serve github forward` — turning discovered
+ * GitHub channels into a `gh webhook forward` invocation.
+ *
+ * These are pure functions (no process spawning) so they are unit-testable;
+ * the CLI in `internal/cli-github.ts` runs `gh` around them.
+ *
+ * @see https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing
+ */
+import type { AgentProject } from "../../types.js";
+/** GitHub CLI extension that provides `gh webhook forward`. */
+export declare const GITHUB_WEBHOOK_EXTENSION = "cli/gh-webhook";
+/**
+ * Pinned release for {@link GITHUB_WEBHOOK_EXTENSION}. Passed to
+ * `gh extension install --pin` so auto-install does not float to arbitrary tags.
+ *
+ * @see https://github.com/cli/gh-webhook/releases
+ */
+export declare const GITHUB_WEBHOOK_EXTENSION_PIN = "v0.2.0";
+/** `gh` argv to install the webhook extension at the pinned release. */
+export declare function ghWebhookExtensionInstallArgs(options?: {
+    force?: boolean;
+}): string[];
+/** One discovered GitHub webhook channel on a served agent. */
+export interface GitHubChannelTarget {
+    /** Agent mount slug (`""` for a single-agent server). */
+    slug: string;
+    /** Channel id (filename under `agent/channels/`). */
+    channelId: string;
+    /** Route path under the channel (default `/`). */
+    routePath: string;
+    /** Webhook events this channel is wired to dispatch on. */
+    events: string[];
+}
+/** Minimal mount shape shared by `serve` / `resolveAgentMounts`. */
+export interface AgentMountLike {
+    slug: string;
+    project: AgentProject;
+}
+/**
+ * Collect the GitHub webhook channels across every mounted agent, reading the
+ * `meta` a {@link githubChannel} publishes.
+ */
+export declare function findGitHubChannelTargets(mounts: ReadonlyArray<AgentMountLike>): GitHubChannelTarget[];
+/** Absolute forward URL for a channel target on a local server. */
+export declare function channelForwardUrl(input: {
+    host: string;
+    port: number;
+    slug: string;
+    channelId: string;
+    routePath: string;
+}): string;
+/** A resolved channel to forward deliveries to. */
+export interface GitHubForwardTarget {
+    slug: string;
+    channelId: string;
+    url: string;
+    events: string[];
+}
+export interface ResolveGitHubForwardTargetsInput {
+    targets: ReadonlyArray<GitHubChannelTarget>;
+    /** Restrict to one agent mount. */
+    slug?: string;
+    /** Restrict to one channel id. */
+    channel?: string;
+    host: string;
+    port: number;
+    /**
+     * Explicit forward URL. Only valid when the selection resolves to a single
+     * channel; skips URL derivation.
+     */
+    url?: string;
+    /** Explicit event list; overrides every selected channel's declared events. */
+    events?: readonly string[];
+}
+export type ResolveGitHubForwardTargetsResult = {
+    ok: true;
+    targets: GitHubForwardTarget[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve every channel a forward should feed, honoring `--slug` / `--channel`
+ * selection and `--url` / `--events` overrides. Returns one target for a single
+ * match (or an explicit `--url`) and many when several channels match — the CLI
+ * fans a single `gh webhook forward` out to all of them.
+ */
+export declare function resolveGitHubForwardTargets(input: ResolveGitHubForwardTargetsInput): ResolveGitHubForwardTargetsResult;
+/** Union of the webhook events across every forward target (deduped). */
+export declare function unionForwardEvents(targets: ReadonlyArray<GitHubForwardTarget>): string[];
+export interface GitHubForwardArgsInput {
+    url: string;
+    events: readonly string[];
+    /** `owner/repo`; mutually exclusive with {@link org}. */
+    repo?: string;
+    /** Organization login for org-level hooks. */
+    org?: string;
+    /** Webhook signing secret so `X-Hub-Signature-256` verifies. */
+    secret?: string;
+    /** Extra args appended verbatim (advanced passthrough). */
+    extraArgs?: readonly string[];
+}
+/**
+ * Build the argv for `gh <argv>` that runs `gh webhook forward` with the
+ * planned URL, events, repo/org, and (optional) signing secret.
+ */
+export declare function buildGitHubForwardArgs(input: GitHubForwardArgsInput): string[];
+/** True when `gh extension list` output includes the webhook extension. */
+export declare function parseGhWebhookExtensionInstalled(listOutput: string): boolean;
+/** Version column from `gh extension list` for the webhook extension, if present. */
+export declare function parseGhWebhookExtensionVersion(listOutput: string): string | undefined;
+/** Whether the installed webhook extension matches {@link GITHUB_WEBHOOK_EXTENSION_PIN}. */
+export declare function ghWebhookExtensionPinSatisfied(listOutput: string): boolean;
+/**
+ * `gh webhook forward` authenticates its relay session
+ * (`webhook-forwarder.github.com`) with the GitHub CLI's *own* OAuth login. A
+ * `GITHUB_TOKEN` / `GH_TOKEN` env override is used for REST calls (so hook
+ * creation succeeds) but is rejected by the relay — every delivery then fails
+ * with HTTP 401. Detect such an override so the CLI can warn.
+ *
+ * Returns the offending env var name, or undefined when none is set.
+ */
+export declare function detectGitHubEnvTokenOverride(env?: Record<string, string | undefined>): string | undefined;
+/** Guidance shown when {@link detectGitHubEnvTokenOverride} finds an override. */
+export declare function githubEnvTokenHint(varName: string): string;
+/**
+ * Extract `owner/repo` from a git remote URL (https, `git@`, or `ssh://`).
+ * Returns undefined for unrecognized shapes.
+ */
+export declare function parseRepoFromRemoteUrl(remote: string): string | undefined;
+/** `slug/channelId`, or just `channelId` for a single-agent (unslugged) mount. */
+export declare function targetLabel(target: {
+    slug: string;
+    channelId: string;
+}): string;
+//# sourceMappingURL=forward.d.ts.map

package/dist/channels/github/forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward.d.ts","sourceRoot":"","sources":["../../../src/channels/github/forward.ts"],"names":[],"mappings":"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"}