experimental-ash 0.56.0 → 0.57.0

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

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,45 @@
+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 rarely helps the model
+ * and burns 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,48 @@
+import { type GitHubConversationKind, type GitHubConversationRef, type GitHubIssueCommentEvent, type GitHubIssueWebhookEvent, type GitHubPullRequestReviewCommentEvent, type GitHubPullRequestWebhookEvent } from "#public/channels/github/inbound.js";
+/** JSON-serializable GitHub channel state. */
+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. Used as an alternative to
+ * HMAC verification — e.g. 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 — e.g. 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/definitions/sandbox.d.ts

@@ -1,8 +1,8 @@
 import type { Optional } from "#shared/optional.js";
-import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
+import type { SandboxDefinitionWithBootstrap as SharedSandboxDefinitionWithBootstrap, SandboxDefinitionWithoutBootstrap as SharedSandboxDefinitionWithoutBootstrap } from "#shared/sandbox-definition.js";
 export type { SandboxCommandResult, SandboxProcess, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxRemovePathOptions, SandboxReadTextFileOptions, SandboxRunOptions, SandboxSession, SandboxSpawnOptions, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
-export type { SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
-export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinition<BO, SO>, "backend">;
+export type { SandboxBootstrapUseFn, SandboxRevalidationKeyFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
+export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinitionWithBootstrap<BO, SO>, "backend"> | Optional<SharedSandboxDefinitionWithoutBootstrap<BO, SO>, "backend">;
 /**
  * Defines a sandbox configuration.
  */

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

@@ -2,7 +2,7 @@
  * Sandbox authoring helpers for `agent/sandbox.ts` (or
  * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
  */
-export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRunOptions, type SandboxSession, type SandboxSpawnOptions, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
+export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRevalidationKeyFn, type SandboxRunOptions, type SandboxSession, type SandboxSpawnOptions, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
 export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
 export type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
 export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";

package/dist/src/runtime/resolve-sandbox.js

@@ -1 +1 @@
-import{expectObjectRecord}from"#internal/authored-module.js";import{toErrorMessage}from"#shared/errors.js";import{lazyBackend}from"#execution/sandbox/lazy-backend.js";import{ResolveAgentError,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{defaultBackend}from"#public/sandbox/backends/default.js";async function resolveSandboxDefinition(n,i,a){try{let t=expectObjectRecord(await loadResolvedModuleExport({definition:n,kindLabel:`sandbox`,moduleMap:i,nodeId:a}),`Expected the sandbox export "${n.exportName??`default`}" from "${n.logicalPath}" to return an object.`);return{backend:resolveBackend(t.backend,n.logicalPath),bootstrap:t.bootstrap,description:n.description,exportName:n.exportName,logicalPath:n.logicalPath,onSession:t.onSession,sourceId:n.sourceId,sourceKind:`module`}}catch(e){throw e instanceof ResolveAgentError?e:new ResolveAgentError(`Failed to attach the sandbox lifecycle handlers from "${n.logicalPath}": ${toErrorMessage(e)}`,{logicalPath:n.logicalPath,sourceId:n.sourceId})}}function resolveBackend(e,t){if(e===void 0)return defaultBackend();if(typeof e==`function`)return lazyBackend(e);if(typeof e!=`object`||!e)throw new ResolveAgentError(`Sandbox "${t}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), another factory that returns a SandboxBackend value, or a zero-arg callback returning one.`,{logicalPath:t});let r=e;if(typeof r.name!=`string`||r.name.length===0)throw new ResolveAgentError(`Sandbox "${t}" backend is missing a non-empty string "name" identifier.`,{logicalPath:t});if(typeof r.create!=`function`)throw new ResolveAgentError(`Sandbox "${t}" backend is missing a "create" function.`,{logicalPath:t});return r}export{resolveSandboxDefinition};
+import{expectObjectRecord}from"#internal/authored-module.js";import{toErrorMessage}from"#shared/errors.js";import{lazyBackend}from"#execution/sandbox/lazy-backend.js";import{ResolveAgentError,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{defaultBackend}from"#public/sandbox/backends/default.js";async function resolveSandboxDefinition(n,i,a){try{let t=expectObjectRecord(await loadResolvedModuleExport({definition:n,kindLabel:`sandbox`,moduleMap:i,nodeId:a}),`Expected the sandbox export "${n.exportName??`default`}" from "${n.logicalPath}" to return an object.`);return{backend:resolveBackend(t.backend,n.logicalPath),bootstrap:t.bootstrap,description:n.description,exportName:n.exportName,logicalPath:n.logicalPath,onSession:t.onSession,revalidationKey:n.revalidationKey,sourceHash:n.sourceHash,sourceId:n.sourceId,sourceKind:`module`}}catch(e){throw e instanceof ResolveAgentError?e:new ResolveAgentError(`Failed to attach the sandbox lifecycle handlers from "${n.logicalPath}": ${toErrorMessage(e)}`,{logicalPath:n.logicalPath,sourceId:n.sourceId})}}function resolveBackend(e,t){if(e===void 0)return defaultBackend();if(typeof e==`function`)return lazyBackend(e);if(typeof e!=`object`||!e)throw new ResolveAgentError(`Sandbox "${t}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), another factory that returns a SandboxBackend value, or a zero-arg callback returning one.`,{logicalPath:t});let r=e;if(typeof r.name!=`string`||r.name.length===0)throw new ResolveAgentError(`Sandbox "${t}" backend is missing a non-empty string "name" identifier.`,{logicalPath:t});if(typeof r.create!=`function`)throw new ResolveAgentError(`Sandbox "${t}" backend is missing a "create" function.`,{logicalPath:t});return r}export{resolveSandboxDefinition};

package/dist/src/runtime/sandbox/keys.js

@@ -1 +1 @@
-import{realpath}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{getRuntimeCompiledArtifactsAppRoot,getRuntimeCompiledArtifactsCacheKey}from"#runtime/compiled-artifacts-source.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";async function createRuntimeSandboxKeys(e){return{sessionKey:await createRuntimeSandboxSessionKey(e),templateKey:await createRuntimeSandboxTemplateKey(e)}}async function createRuntimeSandboxTemplateKey(e){if(e.templatePlan.kind===`none`)return null;let n=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:e.templatePlan.kind===`source-graph`?`deployment`:`stable`}),r=await resolveRuntimeSandboxVersionHash({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId,sourceId:e.sourceId,templatePlan:e.templatePlan}),i=createStableHash(`${resolveInstalledPackageInfo().version}:3:${r}`).slice(0,20);return sanitizeRuntimeSandboxKey(`ash-sbx-tpl-${e.backendName}-${n}-${i}`)}async function createRuntimeSandboxSessionKey(e){let t=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:`deployment`}),n=sanitizeRuntimeSandboxKey(e.nodeId);return sanitizeRuntimeSandboxKey(`ash-sbx-ses-${e.backendName}-${t}-${e.sessionId}-${n}`)}async function resolveRuntimeSandboxScope(t){if(t.backendName===`vercel`){if(t.scopeKind===`stable`){let e=resolveVercelProjectScope();if(e!==void 0)return createStableHash(e).slice(0,16)}let e=process.env.VERCEL_DEPLOYMENT_ID?.trim();if(e!==void 0&&e.length>0)return createStableHash(e).slice(0,16)}let n=getRuntimeCompiledArtifactsAppRoot(t.compiledArtifactsSource);return n===void 0?createStableHash(getRuntimeCompiledArtifactsCacheKey(t.compiledArtifactsSource)).slice(0,16):createStableHash(await realpath(n)).slice(0,16)}async function resolveRuntimeSandboxVersionHash(e){return e.templatePlan.kind===`workspace-content`?createStableHash(`workspace-content:${e.templatePlan.contentHash??await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`):createStableHash(`source-graph:${await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`)}async function resolveSourceGraphHash(e){return(await loadCompileMetadata({compiledArtifactsSource:e}))?.discovery.sourceGraphHash??getRuntimeCompiledArtifactsCacheKey(e)}function resolveVercelProjectScope(){let e=process.env.VERCEL_PROJECT_ID?.trim();if(e===void 0||e.length===0)return;let t=process.env.VERCEL_TEAM_ID?.trim();return t===void 0||t.length===0?`vercel-project:${e}`:`vercel-project:${t}:${e}`}function createStableHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function sanitizeRuntimeSandboxKey(e){return e.replaceAll(/[^a-zA-Z0-9._-]+/g,`-`).slice(0,120)}export{createRuntimeSandboxKeys,createRuntimeSandboxTemplateKey};
+import{realpath}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{getRuntimeCompiledArtifactsAppRoot,getRuntimeCompiledArtifactsCacheKey}from"#runtime/compiled-artifacts-source.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";async function createRuntimeSandboxKeys(e){return{sessionKey:await createRuntimeSandboxSessionKey(e),templateKey:await createRuntimeSandboxTemplateKey(e)}}async function createRuntimeSandboxTemplateKey(e){if(e.templatePlan.kind===`none`)return null;let n=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:e.templatePlan.kind===`source-graph`?`deployment`:`stable`}),r=await resolveRuntimeSandboxVersionHash({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId,sourceId:e.sourceId,templatePlan:e.templatePlan}),i=createStableHash(`${resolveInstalledPackageInfo().version}:5:${r}`).slice(0,20);return sanitizeRuntimeSandboxKey(`ash-sbx-tpl-${e.backendName}-${n}-${i}`)}async function createRuntimeSandboxSessionKey(e){let t=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:`deployment`}),n=sanitizeRuntimeSandboxKey(e.nodeId);return sanitizeRuntimeSandboxKey(`ash-sbx-ses-${e.backendName}-${t}-${e.sessionId}-${n}`)}async function resolveRuntimeSandboxScope(t){if(t.backendName===`vercel`){if(t.scopeKind===`stable`){let e=resolveVercelProjectScope();if(e!==void 0)return createStableHash(e).slice(0,16)}let e=process.env.VERCEL_DEPLOYMENT_ID?.trim();if(e!==void 0&&e.length>0)return createStableHash(e).slice(0,16)}let n=getRuntimeCompiledArtifactsAppRoot(t.compiledArtifactsSource);return n===void 0?createStableHash(getRuntimeCompiledArtifactsCacheKey(t.compiledArtifactsSource)).slice(0,16):createStableHash(await realpath(n)).slice(0,16)}async function resolveRuntimeSandboxVersionHash(e){if(e.templatePlan.kind===`bootstrap`){let t=e.templatePlan.contentHash??await resolveSourceGraphHash(e.compiledArtifactsSource);return createStableHash(`bootstrap:${e.templatePlan.revalidationKey??``}:${e.templatePlan.sourceHash}:${t}:${e.nodeId}:${e.sourceId}`)}return e.templatePlan.kind===`workspace-content`?createStableHash(`workspace-content:${e.templatePlan.contentHash??await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`):createStableHash(`source-graph:${await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`)}async function resolveSourceGraphHash(e){return(await loadCompileMetadata({compiledArtifactsSource:e}))?.discovery.sourceGraphHash??getRuntimeCompiledArtifactsCacheKey(e)}function resolveVercelProjectScope(){let e=process.env.VERCEL_PROJECT_ID?.trim();if(e===void 0||e.length===0)return;let t=process.env.VERCEL_TEAM_ID?.trim();return t===void 0||t.length===0?`vercel-project:${e}`:`vercel-project:${t}:${e}`}function createStableHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function sanitizeRuntimeSandboxKey(e){return e.replaceAll(/[^a-zA-Z0-9._-]+/g,`-`).slice(0,120)}export{createRuntimeSandboxKeys,createRuntimeSandboxTemplateKey};

package/dist/src/runtime/sandbox/template-plan.d.ts

@@ -9,6 +9,11 @@ export type RuntimeSandboxTemplatePlan = {
 } | {
     readonly contentHash?: string;
     readonly kind: "workspace-content";
+} | {
+    readonly contentHash?: string;
+    readonly kind: "bootstrap";
+    readonly revalidationKey?: string;
+    readonly sourceHash: string;
 } | {
     readonly kind: "source-graph";
 };

package/dist/src/runtime/sandbox/template-plan.js

@@ -1 +1 @@
-function createRuntimeSandboxTemplatePlan(e){return e.definition.bootstrap===void 0?e.workspaceResourceRoot.rootEntries.length===0?{kind:`none`}:{contentHash:e.workspaceResourceRoot.contentHash,kind:`workspace-content`}:{kind:`source-graph`}}export{createRuntimeSandboxTemplatePlan};
+function createRuntimeSandboxTemplatePlan(e){if(e.definition.bootstrap!==void 0){if(e.definition.sourceHash===void 0)throw Error(`Sandbox "${e.definition.logicalPath}" defines bootstrap() but has no compiled sourceHash.`);return{contentHash:e.workspaceResourceRoot.contentHash,kind:`bootstrap`,revalidationKey:e.definition.revalidationKey,sourceHash:e.definition.sourceHash}}return e.workspaceResourceRoot.rootEntries.length===0?{kind:`none`}:{contentHash:e.workspaceResourceRoot.contentHash,kind:`workspace-content`}}export{createRuntimeSandboxTemplatePlan};

package/dist/src/runtime/subagents/registry.js

@@ -1 +1 @@
-import{RuntimeRegistry,RuntimeRegistryError}from"#internal/runtime-registry.js";const SUBAGENT_TOOL_INPUT_SCHEMA=Object.freeze({type:`object`,properties:Object.freeze({message:Object.freeze({type:`string`,description:`The message to send to the subagent. Provide all context the subagent needs to complete the task; the subagent does not see the parent's history.`})}),required:Object.freeze([`message`]),additionalProperties:!1});function createRuntimeSubagentRegistry(t){let n=[],r=new RuntimeRegistry(`subagent`,t.reservedToolNames??[]),i=new Map;for(let e of t.subagents){let t={logicalPath:e.logicalPath,sourceId:e.sourceId};if(i.has(e.nodeId))throw new RuntimeRegistryError(`subagent`,`Found multiple runtime subagents mapped to node id "${e.nodeId}".`,{...t,entryName:e.name});let a=createPreparedRuntimeSubagentTool(e),o={definition:e,prepared:a};r.register(e.name,o,{location:t,duplicateMessage:`Found multiple subagents named "${e.name}". Subagent names must be unique at runtime.`,reservedMessage:`Subagent "${e.name}" collides with another runtime-visible tool name.`}),n.push(a),i.set(e.nodeId,o)}return{preparedTools:n,subagentsByName:r.asMap(),subagentsByNodeId:i}}function createPreparedRuntimeSubagentTool(e){return{description:e.description,inputSchema:SUBAGENT_TOOL_INPUT_SCHEMA,kind:e.kind,logicalPath:e.logicalPath,name:e.name,nodeId:e.nodeId,outputSchema:e.kind===`remote`?e.outputSchema:void 0,sourceId:e.sourceId}}export{createRuntimeSubagentRegistry};
+import{RuntimeRegistry,RuntimeRegistryError}from"#internal/runtime-registry.js";const SUBAGENT_TOOL_INPUT_SCHEMA=Object.freeze({type:`object`,properties:Object.freeze({message:Object.freeze({type:`string`,description:`The message to send to the subagent. Provide all context the subagent needs to complete the task; the subagent does not see the parent's history.`}),outputSchema:Object.freeze({type:`object`,description:`When provided, the subagent runs in task mode and must produce structured output matching this JSON Schema. The structured output becomes the tool result.`})}),required:Object.freeze([`message`]),additionalProperties:!1});function createRuntimeSubagentRegistry(t){let n=[],r=new RuntimeRegistry(`subagent`,t.reservedToolNames??[]),i=new Map;for(let e of t.subagents){let t={logicalPath:e.logicalPath,sourceId:e.sourceId};if(i.has(e.nodeId))throw new RuntimeRegistryError(`subagent`,`Found multiple runtime subagents mapped to node id "${e.nodeId}".`,{...t,entryName:e.name});let a=createPreparedRuntimeSubagentTool(e),o={definition:e,prepared:a};r.register(e.name,o,{location:t,duplicateMessage:`Found multiple subagents named "${e.name}". Subagent names must be unique at runtime.`,reservedMessage:`Subagent "${e.name}" collides with another runtime-visible tool name.`}),n.push(a),i.set(e.nodeId,o)}return{preparedTools:n,subagentsByName:r.asMap(),subagentsByNodeId:i}}function createPreparedRuntimeSubagentTool(e){return{description:e.description,inputSchema:SUBAGENT_TOOL_INPUT_SCHEMA,kind:e.kind,logicalPath:e.logicalPath,name:e.name,nodeId:e.nodeId,outputSchema:e.kind===`remote`?e.outputSchema:void 0,sourceId:e.sourceId}}export{createRuntimeSubagentRegistry};

package/dist/src/runtime/types.d.ts

@@ -19,7 +19,7 @@ import type { NamedSkillDefinition } from "#shared/skill-definition.js";
 import type { InternalAgentDefinition } from "#shared/agent-definition.js";
 import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
 import type { SandboxBackend } from "#shared/sandbox-backend.js";
-import type { SandboxDefinition } from "#shared/sandbox-definition.js";
+import type { SandboxBootstrapContext, SandboxSessionContext } from "#shared/sandbox-definition.js";
 /**
  * Runtime-owned source ref describing one additive config module import.
  */
@@ -86,7 +86,10 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
  * `vercelBackend()` and `localBackend()` based on the current
  * environment).
  */
-export type ResolvedSandboxDefinition = Readonly<Omit<SandboxDefinition, "backend">> & ResolvedModuleSourceRef & {
+export type ResolvedSandboxDefinition = ResolvedModuleSourceRef & {
+    readonly bootstrap?: (input: SandboxBootstrapContext) => Promise<void> | void;
+    readonly revalidationKey?: string;
+    readonly sourceHash?: string;
     /**
      * Resolved backend value. The authored `SandboxDefinition.backend`
      * accepts either a `SandboxBackend` or a `() => SandboxBackend`; by
@@ -96,6 +99,7 @@ export type ResolvedSandboxDefinition = Readonly<Omit<SandboxDefinition, "backen
      */
     readonly backend: SandboxBackend;
     readonly description?: string;
+    readonly onSession?: (input: SandboxSessionContext) => Promise<void> | void;
 };
 /**
  * Runtime-owned authored tool definition resolved from a compiled module map.

package/dist/src/shared/sandbox-definition.d.ts

@@ -10,6 +10,7 @@ export interface SandboxSessionContext<O = Record<string, never>> {
     readonly ctx: SessionContext;
     readonly use: SandboxSessionUseFn<O>;
 }
+export type SandboxRevalidationKeyFn = () => Promise<string> | string;
 /**
  * Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
  * or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
@@ -23,7 +24,7 @@ export interface SandboxSessionContext<O = Record<string, never>> {
  * `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
  * their parent's sandbox (skill seeds differ per agent).
  */
-export interface SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> {
+interface SandboxDefinitionBase<BO = Record<string, never>, SO = Record<string, never>> {
     /**
      * Backend that runs this sandbox.
      *
@@ -49,6 +50,25 @@ export interface SandboxDefinition<BO = Record<string, never>, SO = Record<strin
      * specific backend regardless of environment.
      */
     readonly backend: SandboxBackend<BO, SO> | (() => SandboxBackend<BO, SO>);
-    bootstrap?(input: SandboxBootstrapContext<BO>): Promise<void> | void;
+    readonly description?: string;
     onSession?(input: SandboxSessionContext<SO>): Promise<void> | void;
 }
+export interface SandboxDefinitionWithBootstrap<BO = Record<string, never>, SO = Record<string, never>> extends SandboxDefinitionBase<BO, SO> {
+    bootstrap(input: SandboxBootstrapContext<BO>): Promise<void> | void;
+    /**
+     * Optional build-time revalidation key for the reusable sandbox
+     * snapshot produced by {@link bootstrap}. Ash evaluates this
+     * function during compile/build, stores the resolved string in
+     * compiled artifacts, and uses that frozen value for both prewarm and
+     * runtime session create. Authored sandbox source and
+     * framework-managed seed contents are included automatically; provide
+     * this key only for external inputs that affect bootstrap output.
+     */
+    readonly revalidationKey?: SandboxRevalidationKeyFn;
+}
+export interface SandboxDefinitionWithoutBootstrap<BO = Record<string, never>, SO = Record<string, never>> extends SandboxDefinitionBase<BO, SO> {
+    bootstrap?: undefined;
+    readonly revalidationKey?: never;
+}
+export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = SandboxDefinitionWithBootstrap<BO, SO> | SandboxDefinitionWithoutBootstrap<BO, SO>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
     "agent-framework",
@@ -165,6 +165,11 @@
       "import": "./dist/src/public/channels/slack/index.js",
       "default": "./dist/src/public/channels/slack/index.js"
     },
+    "./channels/github": {
+      "types": "./dist/src/public/channels/github/index.d.ts",
+      "import": "./dist/src/public/channels/github/index.js",
+      "default": "./dist/src/public/channels/github/index.js"
+    },
     "./channels/discord": {
       "types": "./dist/src/public/channels/discord/index.d.ts",
       "import": "./dist/src/public/channels/discord/index.js",