experimental-ash 0.55.3 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # experimental-ash
 
+## 0.57.0
+
+### Minor Changes
+
+- b4d3ff0: Sandbox definitions with `bootstrap()` may now provide an optional build-time `revalidationKey()` function. Resolved revalidation keys and authored sandbox source hashes are stored in compiled artifacts so bootstrap templates can reuse stable snapshots across deploys when the revalidation key, sandbox source, and seed content match.
+- ad9c3c5: Add the native GitHub channel (`experimental-ash/channels/github`). Verifies GitHub App webhooks, derives session auth from the GitHub actor, and dispatches `@mention` turns from issue comments, PR timeline comments, and inline review threads. Replies land on the native surface (timeline comment or inline review-thread reply) and acknowledge with an `eyes` reaction. Pull-request turns always inject the PR diff (with noisy files like lock files excluded from the prompt) and always check out the triggering ref into the sandbox so the built-in filesystem tools operate on the real tree. Checkout is incremental — because the sandbox persists for the session, a turn whose target commit the workspace is already on skips the fetch entirely — and brokers the installation token at the sandbox firewall (so it never enters the sandbox process) rather than embedding it in the git remote URL. Supports opt-in `onIssue`/`onPullRequest` automation hooks, an `onComment` override, a generic `ctx.github.request()` escape hatch, and proactive `receive()` sessions.
+- ad9c3c5: Add `credentials.webhookVerifier` to the GitHub channel, matching the other native channels. When supplied, it replaces the built-in `X-Hub-Signature-256` HMAC check (the `GITHUB_WEBHOOK_SECRET` fallback is skipped), letting integrations like Vercel Connect authenticate forwarded webhooks out-of-band (e.g. with Vercel OIDC). Combined with the existing function-form `appId`/`privateKey`/`webhookSecret` credentials, the GitHub channel now has the same Connect integration surface as Slack, Teams, Telegram, and Discord.
+- 4de5be3: Add optional `outputSchema` to subagent tool input schema for structured output. When a parent agent passes `outputSchema` to a subagent tool call, the child runs in task mode and must produce structured output matching the schema via the `final_output` tool.
+
+## 0.56.0
+
+### Minor Changes
+
+- e5f2d97: Ship the root Ash skill packages inside the npm package under `dist/skills`. The docs site now renders those canonical `SKILL.md` files directly as skill reference pages, avoiding duplicated skill documentation.
+- 80ca852: Add optional `outputSchema` support to `defineTool` and propagate tool output schemas into code mode host tools. Framework tools with fixed result shapes now declare output schemas, provider-managed `web_search` injects the selected provider's output schema at runtime, and code mode logs a warning when an exposed host tool has no output schema.
+
+  Use deterministic per-turn completion hook tokens in the workflow driver so fast subagent resumes cannot collide with a prior turn's completion hook while the Workflow SDK is still persisting disposal.
+
+### Patch Changes
+
+- bdf208a: Connections now recover when the remote server rejects an already-issued
+  token. An MCP `401` (the bearer was revoked or expired out of band) is
+  classified as authorization-required: Ash evicts the stale cached token,
+  tears down the connection, and re-enters the sign-in flow instead of
+  narrating an opaque transport error. A loop guard fails the connection
+  terminally if a freshly authorized token is still rejected, so a broken
+  grant cannot trigger an endless re-authorization loop.
+- f158cb2: Drop verified Slack `http_timeout` retry deliveries so delayed acknowledgements do not start duplicate sessions.
+- 4d59025: Add Apache-2.0 license metadata, a root license file, and publish-time package license copies along with clearer package descriptions and discovery keywords.
+
 ## 0.55.3
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/docs/internals/compiler-and-artifacts.md

@@ -33,7 +33,7 @@ Discovery avoids executing authored code. The module map is the handoff — it s
 
 **`compiled-agent-manifest.json`** — the normalized runtime-facing manifest. Preserves config, prompt, skill, sandbox, schedule, and tool metadata; flattened subagent nodes with explicit `subagentEdges`; manifest kind and version. `sandbox` is `null` or one entry, and `sandboxWorkspaces` is an array of size 0 or 1 (single-sandbox model).
 
-**`compile-metadata.json`** — artifact paths, SHA-256 digests, diagnostics summary, compile status, generator version, and `sourceGraphHash`. The `sourceGraphHash` drives sandbox template cache invalidation — runtime and Vercel build-time prewarm both derive template keys from it.
+**`compile-metadata.json`** — artifact paths, SHA-256 digests, diagnostics summary, compile status, generator version, and `sourceGraphHash`. Runtime and Vercel build-time prewarm derive sandbox template keys from compiled artifacts: seed-only templates use workspace content hashes, bootstrap templates use the optional resolved authored `revalidationKey()` plus authored sandbox source and workspace content, and source-graph fallback paths use `sourceGraphHash`.
 
 **`module-map.mjs`** — frozen object keyed by `(nodeId, sourceId)`. Authored sandbox modules are indexed directly (runtime needs their lifecycle hooks); `lib/` modules come in transitively.
 

package/dist/docs/internals/context.md

@@ -80,9 +80,9 @@ Authored hook stream-event dispatch runs inside step (4)'s ALS scope.
 Event hooks receive `(event, ctx)`. See [Hooks](./hooks.md) for the
 full pipeline.
 
-`StepInput.modelContext` is provided by channels through
-`SendPayload.modelContext`. The messages are visible to the next model
-call only and are never persisted to durable session history.
+`StepInput.context` is provided by channels through `SendPayload.context`.
+Each entry is appended as a `role: "user"` message to durable session
+history before the delivery message.
 
 ## Channel Context
 

package/dist/docs/public/advanced/typescript-api.md

@@ -118,6 +118,24 @@ Channel and Slack types exported from `experimental-ash/channels/slack`:
 - `Card`, `Button`, `Actions`, `Section`, `Modal`, `Table`, etc. - card builders re-exported for
   rendering Slack messages
 
+Channel and GitHub types exported from `experimental-ash/channels/github`:
+
+- `githubChannel` - GitHub App webhook channel factory for issue/PR comments, review comments,
+  and opt-in issue/pull-request hooks
+- `GitHubChannelConfig` - config type for credentials, route, bot mention trigger, PR diff
+  exclusions, reaction acknowledgement, and the `onComment`/`onIssue`/`onPullRequest` handlers
+- `GitHubInboundContext` - pre-dispatch context for inbound hooks (`thread`, `github`,
+  `repository`, `sender`, `delivery`)
+- `GitHubEventContext` - event-handler context (`thread`, `github`, mutable `state`,
+  repository/conversation metadata, and channel session operations)
+- `GitHubHandle` - GitHub helper handle: `request()` plus `installationId` and `repository`
+- `GitHubThread` - conversation-scoped operations: `post` and `react`
+- `GitHubComment`, `GitHubIssueEvent`, and `GitHubPullRequestEvent` - parsed inbound payload types
+- `GitHubIssueAction` / `GitHubPullRequestAction` - typed webhook action unions
+- `GitHubPullRequestContextConfig` - PR diff exclusion config (`excludedFiles`)
+- `GitHubReceiveTarget` - target accepted by proactive `receive(github, ...)`
+- `defaultGitHubAuth` - default GitHub actor-to-session-auth projection
+
 Channel and Twilio types exported from `experimental-ash/channels/twilio`:
 
 - `twilioChannel` - Twilio channel factory for SMS and speech-transcribed voice webhooks
@@ -203,6 +221,7 @@ import { defineAgent } from "experimental-ash";
 import { defineChannel, POST, GET } from "experimental-ash/channels";
 import { ashChannel } from "experimental-ash/channels/ash";
 import { vercelOidc } from "experimental-ash/channels/auth";
+import { githubChannel } from "experimental-ash/channels/github";
 import { slackChannel } from "experimental-ash/channels/slack";
 import { telegramChannel } from "experimental-ash/channels/telegram";
 ```

package/dist/docs/public/advanced/vercel-deployment.md

@@ -63,7 +63,8 @@ Important behavior:
 - Ash skips prewarm for sandboxes with no `bootstrap()` and no workspace seed files
 - seed-only templates are keyed by skills and workspace file contents, so unchanged seeds can reuse
   a template across deploys
-- sandboxes with `bootstrap()` remain deployment-scoped
+- sandboxes with `bootstrap()` are keyed by the optional resolved `revalidationKey()` value plus
+  authored sandbox source and seed contents, so matching inputs can reuse a template across deploys
 - the build log labels each template `reused cached` or `built`, so a reuse across deploys is visible
 - `onSession()` still runs later at runtime
 - if build-time prewarm fails, the build fails

package/dist/docs/public/channels/github.md

@@ -0,0 +1,145 @@
+---
+title: "GitHub channel setup"
+description: "Create a GitHub App-backed Ash channel with automatic PR context and sandbox checkout."
+type: integration
+related:
+  - /channels
+  - /sandbox
+---
+
+Ash GitHub channels receive GitHub App webhooks at `/ash/v1/github`, verify the webhook signature,
+derive auth from the GitHub actor, and deliver responses back to the native GitHub surface.
+
+## Add The Channel File
+
+Create `agent/channels/github.ts`:
+
+```ts
+import { githubChannel } from "experimental-ash/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+  credentials: {
+    appId: process.env.GITHUB_APP_ID,
+    privateKey: process.env.GITHUB_APP_PRIVATE_KEY,
+    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
+  },
+});
+```
+
+Configure the GitHub App webhook URL to `https://<deployment>/ash/v1/github`. Subscribe to
+`issue_comment` and `pull_request_review_comment` for mention-driven turns. Subscribe to `issues`
+and `pull_request` when you configure their opt-in hooks.
+
+The agent starts a turn whenever a comment or inline review comment `@mention`s `botName`.
+
+Each field has an environment-variable fallback, so the `credentials` block above is optional when
+those variables are set: `appId` reads `GITHUB_APP_ID`, `privateKey` reads `GITHUB_APP_PRIVATE_KEY`,
+`webhookSecret` reads `GITHUB_WEBHOOK_SECRET`, and `botName` reads `GITHUB_APP_SLUG`. `appId`,
+`privateKey`, and `webhookSecret` also accept a function that resolves the value lazily (e.g. from a
+secret manager).
+
+## Acknowledgement & Replies
+
+The channel manages the GitHub-native side of a turn for you:
+
+- When a turn starts it adds an `eyes` reaction to the triggering comment so the user knows the agent
+  picked it up. Disable the reaction with `progress: { reactions: false }`.
+- The agent's reply is posted back to the conversation as a comment (issue/PR timeline comments reply
+  on the issue or PR; inline review comments reply in the review thread). Long replies are split
+  across multiple comments to stay within GitHub's size limit.
+- If a turn or session fails, the channel posts a short error comment with an error id instead of
+  going silent.
+
+## Pull Request Context
+
+When the agent is summoned on a pull request, it always sees the PR. The channel injects PR metadata
+and the changed-file diff as `context` strings appended to the turn before the comment. There is no
+flag to disable it — seeing the diff is the point.
+
+Large, generated files (lock files, minified bundles, source maps, snapshots) are excluded from the
+diff loaded into the prompt: they are still listed with their stats, but their patch body is omitted.
+Add your own globs with `excludedFiles` (they extend the built-in list):
+
+```ts
+export default githubChannel({
+  botName: "my-agent",
+  pullRequestContext: {
+    excludedFiles: ["**/*.generated.ts", "docs/**/*.svg"],
+  },
+});
+```
+
+Excluded files are still on disk via the checkout, so the agent can `read_file` one if it needs the
+contents. Custom inbound hooks can also return their own `context`; Ash prepends the
+channel-generated PR diff first, then your hook context.
+
+## Sandbox Checkout
+
+Every triggered turn checks out the relevant ref into the sandbox before the first model call, so the
+built-in `read_file`, `glob`, `grep`, and `bash` tools operate on the real tree:
+
+- issue comments and `onIssue` turns check out the repository default branch.
+- PR comments, inline review comments, and `onPullRequest` turns check out the PR head, and also
+  fetch the base ref so `git diff <base>...HEAD` works.
+
+Checkout brokers a fresh installation token at the sandbox firewall: `git` fetches a clean,
+token-free URL and the platform injects an `Authorization` header on egress to `github.com`, so the
+token never enters the sandbox process. This requires a firewall-capable backend (the Vercel
+backend); the local backend cannot broker, so checkout is skipped there (the failure is logged and
+the turn proceeds with the PR diff still in context).
+
+The sandbox persists for the life of the session, so checkout is incremental: when a later turn in
+the same session targets a commit the workspace is already on, the turn skips the fetch entirely
+(no installation token is minted and nothing is downloaded).
+
+## Inbound Hooks
+
+Three optional hooks let you customize dispatch. Each returns `{ auth }` to dispatch or `null` to
+ignore.
+
+Derive session auth from the GitHub actor with `defaultGitHubAuth(ctx)`.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "experimental-ash/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+
+  // Replaces the default `@mention` gate for issue/PR/review comments.
+  // ctx.conversation.kind is "issue" | "pull_request" | "review_thread".
+  async onComment(ctx, comment) {
+    const context: string[] | undefined = comment.body.includes("/grammar")
+      ? ["Review only prose, comments, and documentation."]
+      : undefined;
+    return { auth: defaultGitHubAuth(ctx), context };
+  },
+
+  // Opt in to act on issues. There is no default dispatch on this event.
+  onIssue(ctx, issue) {
+    if (issue.action !== "opened") return null;
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+
+  // Opt in to act on pull requests. There is no default dispatch on this event.
+  onPullRequest(ctx, pullRequest) {
+    if (pullRequest.action !== "opened") return null;
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+});
+```
+
+`issue.action` and `pullRequest.action` are typed unions of the common GitHub webhook actions
+(`opened`, `closed`, `edited`, `synchronize`, …) and stay open to any action GitHub sends.
+
+## Arbitrary GitHub API Calls
+
+For anything the channel does not wrap, use `ctx.github.request()` with installation-token auth:
+
+```ts
+await ctx.github.request({
+  method: "POST",
+  path: `/repos/${ctx.repository.fullName}/issues/${issueNumber}/labels`,
+  body: { labels: ["triaged"] },
+});
+```

package/dist/docs/public/channels/index.md

@@ -1,6 +1,6 @@
 ---
 title: "Channels"
-description: "Deliver your agent over HTTP, Slack, Discord, Twilio, Telegram, Microsoft Teams, and custom transports."
+description: "Deliver your agent over HTTP, Slack, GitHub, Discord, Twilio, Telegram, Microsoft Teams, and custom transports."
 url: /channels
 ---
 
@@ -23,7 +23,7 @@ Ash ships the public HTTP protocol as channels:
 - `ashChannel({ auth })` for the built-in Ash protocol channel
 
 Ash also supports authored channels under `agent/channels/` for platform-specific integrations such
-as Slack, Discord, Twilio, Telegram, Microsoft Teams, or custom webhooks.
+as Slack, GitHub, Discord, Twilio, Telegram, Microsoft Teams, or custom webhooks.
 
 ## Filesystem Shape
 
@@ -283,6 +283,26 @@ dispatch for app mentions, direct messages, and interactions.
 For a Slack app backed by Vercel Connect, see [Slack channel setup](./slack.mdx) to create the Connect client
 and channel file.
 
+## GitHub Channels
+
+GitHub channels are authored with `githubChannel()`:
+
+```ts
+import { githubChannel } from "experimental-ash/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+});
+```
+
+The channel verifies GitHub App webhooks at `/ash/v1/github`, dispatches bot-directed issue/PR
+comments and pull-request review comments, can opt into issue and pull-request hooks, exposes
+GitHub-native issue, PR, reaction, and checkout helpers, and injects bounded PR metadata,
+file lists, and patch text as turn `context`.
+
+See [GitHub channel setup](./github.md) for GitHub App permissions, PR context, checkout, and
+custom inbound hooks.
+
 ## Discord Channels
 
 Discord channels are authored with `discordChannel()`:
@@ -632,6 +652,7 @@ See [Channel file uploads](./attachments.md) for the full guide.
 ## What To Read Next
 
 - [Slack channel setup](./slack.mdx)
+- [GitHub channel setup](./github.md)
 - [Telegram channel setup](./telegram.mdx)
 - [Channel file uploads](./attachments.md)
 - [Project Layout](../project-layout.md)

package/dist/docs/public/meta.json

@@ -15,6 +15,7 @@
     "connections",
     "---",
     "advanced",
+    "guides",
     "---",
     "research"
   ]

package/dist/docs/public/onboarding.md

@@ -28,8 +28,8 @@ Collect these up front. A capable agent should use a structured question UI (suc
 4. **Model provider** — how the agent reaches a model:
    - Vercel project (default) — create a project, or pass `--project <slug>` to link an existing one, and use AI Gateway via OIDC.
    - API key override — pass `--gateway-api-key <key>` to write `AI_GATEWAY_API_KEY` to `.env.local`.
-   - Local only — pass `--local-only` for web/REPL-only setups that should scaffold without a Vercel project; the agent will not reach a model until you add a provider. Slack still requires a Vercel project.
-5. **Deploy** — whether to deploy to Vercel production now. Required for Slack to receive events; pass `--no-deploy` to skip.
+   - Skip Vercel — pass `--skip-vercel` for web/REPL-only setups that should scaffold without a Vercel project or Vercel Services config; the agent will not reach a model until you add a provider. Slack still requires a Vercel project.
+5. **Deploy** — whether to deploy to Vercel production now. Required for Slack to receive events; pass `--skip-deploy` to skip only the final deployment.
 
 ## Step 1 — Scaffold (non-interactive)
 
@@ -42,13 +42,15 @@ npx create-experimental-ash-agent@latest <name> \
   [--team <slug>] \
   [--project <slug>] \
   [--gateway-api-key <key>] \
-  [--local-only] \
-  [--no-deploy] \
+  [--skip-vercel] \
+  [--skip-deploy] \
   --target-dir <parent-dir> \
   --yes --json
 ```
 
-By default the CLI creates a Vercel project named `<name>`, links it non-interactively, and pulls the project's AI Gateway environment. Use `--project <slug>` when the user picked an existing project, `--team <slug>` when they picked a non-current Vercel team, `--gateway-api-key <key>` when they want a pasted key in `.env.local`, and `--local-only` only for web/REPL-only setups where they explicitly do not want Vercel provisioning.
+By default the CLI creates a Vercel project named `<name>`, links it non-interactively, and pulls the project's AI Gateway environment. Use `--project <slug>` when the user picked an existing project, `--team <slug>` when they picked a non-current Vercel team, `--gateway-api-key <key>` when they want a pasted key in `.env.local`, and `--skip-vercel` only for web/REPL-only setups where they explicitly do not want Vercel provisioning or Vercel Services config.
+
+To scaffold into an existing directory instead of creating `<parent-dir>/<name>`, omit `<name>` and pass `--in-place --target-dir <dir>`. Add `-y` / `--yes` only when replacing existing Ash scaffold files is intended; the CLI logs every overwritten file.
 
 The CLI advances as far as it can without human input. When it reaches a login or browser step, it emits an `action-required` record and exits cleanly instead of blocking on a prompt:
 

package/dist/docs/public/sandbox.md

@@ -29,6 +29,7 @@ author a sandbox definition module:
 import { defineSandbox } from "experimental-ash/sandbox";
 
 export default defineSandbox({
+  revalidationKey: () => "jq-bootstrap-v1",
   async bootstrap({ use }) {
     const sandbox = await use();
     await sandbox.run({ command: "apt-get install -y jq" });
@@ -52,6 +53,9 @@ The public lifecycle surface is intentionally small:
 
 - `bootstrap({ use })` — template-scoped setup (runs once when the template is built). Call `use()`
   to get a `SandboxSession` for filesystem setup. Only filesystem state survives snapshotting.
+- `revalidationKey()` — optional build-time function for external inputs that affect
+  `bootstrap()` output. Authored sandbox source and framework-managed seed contents are included
+  automatically.
 - `onSession({ use })` — durable-session-scoped setup (runs once per session). Call `use(opts?)` to
   get a `SandboxSession`; `opts` are forwarded to the backend's update path (the Vercel SDK's
   `sandbox.update(...)`) before the session is returned. `onSession`'s `use()` never creates a
@@ -190,6 +194,13 @@ Inside a subagent's authored code, `ctx.getSandbox()` binds to the subagent's ow
 Call `use()` to get a `SandboxSession`. Only filesystem state survives — configuration changes
 like network policy or resource allocation do not persist into the snapshot.
 
+When external inputs can change `bootstrap()` output, define
+`revalidationKey: () => string | Promise<string>`. Ash evaluates `revalidationKey()` during
+compile/build, stores the resolved string in compiled artifacts, and uses that frozen value for both
+build-time prewarm and runtime session creation. Authored sandbox source and framework-managed seed
+contents are included automatically, so use `revalidationKey()` only for inputs outside that source,
+such as a git commit, lockfile hash, base snapshot version, or daily rotation string.
+
 Framework-managed seed files (compiled skills, authored `workspace/` entries) are written into the
 template before the authored `bootstrap` runs, so your bootstrap can read them.
 
@@ -246,6 +257,7 @@ import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: vercelBackend({ runtime: "node24", resources: { vcpus: 2 } }),
+  revalidationKey: () => "repo-bootstrap-v1",
   async bootstrap({ use }) {
     const sandbox = await use();
     await sandbox.run({ command: "git clone https://example.com/repo.git repo" });
@@ -322,8 +334,8 @@ also work and follow the same rules. When `source.type === "snapshot"`, the Verc
 `runtime`, and TypeScript enforces that at the factory call site.
 
 Ash does not detect changes to an external snapshot. If you rebuild your snapshot and want Ash to
-pick it up, force a template rebuild — for example, by changing the sandbox definition so its
-template key changes.
+pick it up, force a template rebuild by changing the `revalidationKey()` value used by your
+bootstrap template.
 
 ### Deferring Backend Construction
 
@@ -473,7 +485,10 @@ On hosted Vercel builds, Ash can prewarm the authored sandbox template during `a
 
 Ash skips template prewarm for sandboxes that have no `bootstrap()` and no workspace seed files.
 Seed-only sandboxes use a content-addressed template key, so matching skills and workspace files can
-reuse an existing template across deploys. Sandboxes with `bootstrap()` remain deployment-scoped.
+reuse an existing template across deploys. Sandboxes with `bootstrap()` use the optional resolved
+`revalidationKey` plus authored sandbox source and workspace seed content, so matching inputs can
+reuse an existing template across deploys. Changing `revalidationKey()` or sandbox source only takes
+effect after rebuilding compiled artifacts.
 
 Important behavior:
 

package/dist/docs/public/subagents.mdx

@@ -74,7 +74,7 @@ export default defineRemoteAgent({
 });
 ```
 
-Remote agents use the same lowered `{ message: string }` tool shape as local subagents. The
+Remote agents use the same lowered `{ message, outputSchema? }` tool shape as local subagents. The
 difference is dispatch: the parent starts a task-mode session on the remote agent's
 `POST /ash/v1/session`, passes a framework callback URL, parks the parent turn, and resumes when
 the remote agent posts a terminal callback back to the parent. The parent sees the same
@@ -98,11 +98,12 @@ owns redelivery instead of marking the remote task complete.
 
 Ash lowers every subagent into a model-visible tool on the parent agent.
 
-The lowered tool always exposes the same single parameter:
+The lowered tool exposes:
 
 ```ts
 {
   message: string;
+  outputSchema?: object;
 }
 ```
 
@@ -110,6 +111,10 @@ The parent fills `message` with everything the subagent needs to run the task
 not see the parent's history. This mirrors the public message API used to invoke the parent agent
 itself, so prompt-engineering a delegation feels the same as prompt-engineering an initial run.
 
+When `outputSchema` is provided, the subagent runs in task mode and must produce structured output
+matching the given JSON Schema via the `final_output` tool. The structured output becomes the tool
+result returned to the parent.
+
 ## What The Subagent Gets
 
 Subagent execution gets: