experimental-ash 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # experimental-ash
 
+## 0.58.0
+
+### Minor Changes
+
+- 6544348: Add built-in `agent` tool that runs the current agent as a subagent with a focused task. Self-delegated children share the parent's Vercel Sandbox so file writes are visible to the parent. The tool accepts `message` and optional `outputSchema` for structured output.
+
+### Patch Changes
+
+- 0fd74c8: Refresh the composed system prompt between turns in `ash dev` so edits to authored markdown, including `instructions.md`, apply to existing development sessions after HMR rebuilds.
+- 4a84d65: Refactored onboarding/channel setup state so Vercel project resolution and AI Gateway readiness are tracked separately while preserving existing create and `ash channels add` behavior.
+
+## 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

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/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

@@ -3,9 +3,15 @@ title: "Subagents"
 description: "Delegate specialized work to child agents with their own prompts, tools, and sandbox."
 ---
 
-Subagents let the root agent delegate specialized work to local child agents.
+Subagents let an agent delegate specialized work to child agents.
 
-Use them when the task deserves its own prompt, tools, sandbox, and local runtime context.
+There are two kinds of delegation:
+
+- **Built-in `agent` tool** — every agent gets this automatically. It runs a copy of the current
+  agent as a subagent with a focused task. The child shares the parent's sandbox filesystem but
+  gets fresh session state. Use this when the task doesn't need a different prompt or tool surface.
+- **Declared subagents** — authored under `agent/subagents/<id>/` with their own prompt, tools,
+  skills, and sandbox. Use these when the child needs a clearly different identity.
 
 A subagent is just an agent that lives under `agent/subagents/<id>/`. It is authored with the same
 `defineAgent` helper as the root agent — the location under `subagents/` is what makes it a
@@ -21,6 +27,37 @@ subagent.
   stream, and do not commit unless the user asks.
 </CopyPrompt>
 
+## The Built-in `agent` Tool
+
+Every agent gets a built-in `agent` tool. The model calls it to delegate a subtask to a copy of
+itself — same tools, connections, and instructions, fresh conversation history.
+
+```ts
+{
+  message: string;
+  outputSchema?: object;
+}
+```
+
+The child shares the parent's sandbox filesystem. File writes from the child are immediately
+visible to the parent. This makes it natural for the model to split work across multiple parallel
+calls — for example, fixing different files concurrently.
+
+Session state (`defineState`) is **not** shared. Each child gets its own fresh state. Auth,
+connections, and the full tool surface are inherited, but conversation history and durable state
+start empty.
+
+If a declared subagent calls `agent`, the child is a copy of that subagent (not the root agent).
+Every node self-delegates to itself.
+
+An authored tool at `agent/tools/agent.ts` takes priority over the built-in.
+
+## Declared Subagents
+
+A declared subagent is an agent that lives under `agent/subagents/<id>/`. It is authored with the same
+`defineAgent` helper as the root agent — the location under `subagents/` is what makes it a
+subagent.
+
 ## What A Local Subagent Looks Like
 
 ```text
@@ -74,7 +111,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 +135,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,9 +148,13 @@ 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.
 
-## What The Subagent Gets
+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.
 
-Subagent execution gets:
+## What A Declared Subagent Gets
+
+Declared subagent execution gets:
 
 - its own instructions prompt
 - its own tools
@@ -120,10 +162,11 @@ Subagent execution gets:
 - its own `skills/` set (independent of the parent's skills)
 - immediate parent lineage in `ctx.session.parent`, including the parent subagent tool `callId`
 
-Skills and sandboxes do not cross the parent/child boundary. The subagent only sees skills
-authored under `agent/subagents/<id>/skills/`; skills under the root `agent/skills/` are not
-available inside the subagent's turns. If two subagents need the same procedure, duplicate the
-markdown under each subagent's `skills/` (or, for typed code reuse, share helpers via `lib/`).
+Skills and sandboxes do not cross the parent/child boundary for declared subagents. The subagent
+only sees skills authored under `agent/subagents/<id>/skills/`; skills under the root
+`agent/skills/` are not available inside the subagent's turns. If two subagents need the same
+procedure, duplicate the markdown under each subagent's `skills/` (or, for typed code reuse, share
+helpers via `lib/`).
 
 The subagent's sandbox follows the same rule: it does not inherit from the parent, since different
 agents generally have different skills and sharing a filesystem would be confusing. Each subagent
@@ -132,6 +175,9 @@ gets the framework default sandbox unless it authors its own override at
 `workspace/` folder). A subagent can also author only `subagents/<name>/sandbox/workspace/` to seed
 files without overriding the definition.
 
+The built-in `agent` tool is different: its children share the parent's sandbox because they are
+copies of the same agent working on the same codebase.
+
 ## Stream Behavior
 
 Delegated local subagents now create their own public child session and stream.

package/dist/docs/public/tools.mdx

@@ -119,8 +119,14 @@ That means tools are:
 ## Customizing Framework Tools
 
 Every Ash agent gets a small set of framework-provided tools by default:
-`bash`, `read_file`, `write_file`, `todo`, `web_fetch`, `web_search`, and, when the agent has skills,
-`load_skill`.
+`bash`, `read_file`, `write_file`, `todo`, `web_fetch`, `web_search`, `agent`, and, when the agent
+has skills, `load_skill`.
+
+`agent` runs a copy of the current agent as a subagent with a focused task. The child gets the same
+tools, connections, and instructions but a fresh conversation history. The child shares the parent's
+sandbox filesystem — file writes from the child are visible to the parent. Session state
+(`defineState`) is isolated: the child gets fresh state, not the parent's values. See
+[Subagents](./subagents.mdx) for more on delegation.
 
 `load_skill` loads on-demand skill instructions into the current turn. It does not add a new
 execution surface by itself; executable behavior still comes from the tools the agent already has.

package/dist/src/cli/commands/channels.d.ts

@@ -1,4 +1,4 @@
-import { type DeployProjectOptions, type RunAddToAgentOptions } from "@vercel/ash-scaffold/steps";
+import { type AddToAgentState, type DeployProjectOptions, type RunAddToAgentOptions } from "@vercel/ash-scaffold/steps";
 import { type ChannelAddPrompter } from "@vercel/ash-scaffold/cli";
 import { type DeploymentInfo } from "@vercel/ash-scaffold/primitives";
 export interface CliLogger {
@@ -13,8 +13,8 @@ export interface AddChannelCommandOptions {
 export interface ChannelsAddDependencies {
     createPrompter?: () => ChannelAddPrompter;
     detectDeployment(projectPath: string): Promise<DeploymentInfo>;
-    deployProject(options: DeployProjectOptions): Promise<void>;
-    runAddToAgent(options: RunAddToAgentOptions): Promise<void>;
+    deployProject(options: DeployProjectOptions): Promise<AddToAgentState>;
+    runAddToAgent(options: RunAddToAgentOptions): Promise<AddToAgentState>;
 }
 export declare function runChannelsAddCommand(logger: CliLogger, appRoot: string, args: {
     kind?: string;

package/dist/src/cli/commands/channels.js

@@ -1 +1 @@
-import{assertCanAddSelectedChannels,inspectExistingChannelRegistrations}from"./channel-add-conflicts.js";import{isAshProject}from"../../packages/ash-scaffold/src/project.js";import{listAuthoredChannels}from"../../packages/ash-scaffold/src/channels.js";import"../../packages/ash-scaffold/src/index.js";import{detectDeployment}from"../../packages/ash-scaffold/src/primitives/detect-deployment.js";import{createAddToAgentState,deployProject,runAddToAgent}from"../../packages/ash-scaffold/src/steps/run-add-to-agent.js";import"../../packages/ash-scaffold/src/steps/index.js";import{ChannelAddCancelledError,createChannelAddPrompter}from"../../packages/ash-scaffold/src/cli/channel-add-prompter.js";import"../../packages/ash-scaffold/src/cli/index.js";import"../../packages/ash-scaffold/src/primitives/index.js";const NOT_AN_AGENT_MESSAGE="No Ash agent in this directory. Run `pnpm create experimental-ash-agent`, then run this command from inside the new project.",KNOWN_CHANNEL_KINDS=[`slack`,`web`];function isChannelKind(e){return KNOWN_CHANNEL_KINDS.includes(e)}function parseChannelKind(e){if(!isChannelKind(e))throw Error(`Unknown channel kind "${e}". Known: ${KNOWN_CHANNEL_KINDS.join(`, `)}.`);return e}const defaultChannelsAddDependencies={detectDeployment,deployProject,runAddToAgent};async function runAddChannelsFlow(n,r,i,o){if(r===void 0&&(i.yes||!process.stdin.isTTY||!process.stdout.isTTY))throw Error(`Pass a channel kind: \`ash channels add <${KNOWN_CHANNEL_KINDS.join(`|`)}>\`.`);let s=o.createPrompter?.()??createChannelAddPrompter();s.intro(`Add channels to your Ash agent`),s.log.message(`Checking the current Vercel project...`);let c=createAddToAgentState(await o.detectDeployment(n)),l;function inspectRegistrations(){return l===void 0&&(s.log.message(`Inspecting existing channel registrations...`),l=inspectExistingChannelRegistrations(n)),l}let u=r===void 0?(await inspectRegistrations()).disabledChannelReasons:void 0;await o.runAddToAgent({prompter:s,projectPath:n,state:c,presetChannels:r===void 0?void 0:[r],presetCreateSlackbot:i.yes?!0:void 0,disabledChannelReasons:u,force:i.force,validateSelectedChannels:async t=>{!t.includes(`web`)&&!t.includes(`slack`)||assertCanAddSelectedChannels(t,await inspectRegistrations())}}),await o.deployProject({prompter:s,projectPath:n,vercelProjectId:c.vercelProjectId,state:c}),s.outro(c.channels.length===0?`No channels added.`:`Channels added.`)}async function runChannelsAddCommand(e,t,r,i=defaultChannelsAddDependencies){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}try{await runAddChannelsFlow(t,r.kind===void 0?void 0:parseChannelKind(r.kind),r.options,i)}catch(t){if(t instanceof ChannelAddCancelledError)return;e.error(t instanceof Error?t.message:String(t)),process.exitCode=1}}async function runChannelsListCommand(e,t,i){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}let a=await listAuthoredChannels(t);if(i.json){e.log(JSON.stringify({channels:a},null,2));return}if(a.length===0){e.log("No channels defined. Run `ash channels add` to add one.");return}for(let t of a)e.log(t)}export{runChannelsAddCommand,runChannelsListCommand};
+import{assertCanAddSelectedChannels,inspectExistingChannelRegistrations}from"./channel-add-conflicts.js";import{isAshProject}from"../../packages/ash-scaffold/src/project.js";import{listAuthoredChannels}from"../../packages/ash-scaffold/src/channels.js";import"../../packages/ash-scaffold/src/index.js";import{detectDeployment}from"../../packages/ash-scaffold/src/primitives/detect-deployment.js";import{createAddToAgentState,deployProject,runAddToAgent}from"../../packages/ash-scaffold/src/steps/run-add-to-agent.js";import"../../packages/ash-scaffold/src/steps/index.js";import{ChannelAddCancelledError,createChannelAddPrompter}from"../../packages/ash-scaffold/src/cli/channel-add-prompter.js";import"../../packages/ash-scaffold/src/cli/index.js";import"../../packages/ash-scaffold/src/primitives/index.js";const NOT_AN_AGENT_MESSAGE="No Ash agent in this directory. Run `pnpm create experimental-ash-agent`, then run this command from inside the new project.",KNOWN_CHANNEL_KINDS=[`slack`,`web`];function isChannelKind(e){return KNOWN_CHANNEL_KINDS.includes(e)}function parseChannelKind(e){if(!isChannelKind(e))throw Error(`Unknown channel kind "${e}". Known: ${KNOWN_CHANNEL_KINDS.join(`, `)}.`);return e}const defaultChannelsAddDependencies={detectDeployment,deployProject,runAddToAgent};async function runAddChannelsFlow(n,r,i,o){if(r===void 0&&(i.yes||!process.stdin.isTTY||!process.stdout.isTTY))throw Error(`Pass a channel kind: \`ash channels add <${KNOWN_CHANNEL_KINDS.join(`|`)}>\`.`);let s=o.createPrompter?.()??createChannelAddPrompter();s.intro(`Add channels to your Ash agent`),s.log.message(`Checking the current Vercel project...`);let c=createAddToAgentState(await o.detectDeployment(n)),l;function inspectRegistrations(){return l===void 0&&(s.log.message(`Inspecting existing channel registrations...`),l=inspectExistingChannelRegistrations(n)),l}let u=r===void 0?(await inspectRegistrations()).disabledChannelReasons:void 0;c=await o.runAddToAgent({prompter:s,projectPath:n,state:c,presetChannels:r===void 0?void 0:[r],presetCreateSlackbot:i.yes?!0:void 0,disabledChannelReasons:u,force:i.force,validateSelectedChannels:async t=>{!t.includes(`web`)&&!t.includes(`slack`)||assertCanAddSelectedChannels(t,await inspectRegistrations())}}),c=await o.deployProject({prompter:s,projectPath:n,state:c}),s.outro(c.channels.length===0?`No channels added.`:`Channels added.`)}async function runChannelsAddCommand(e,t,r,i=defaultChannelsAddDependencies){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}try{await runAddChannelsFlow(t,r.kind===void 0?void 0:parseChannelKind(r.kind),r.options,i)}catch(t){if(t instanceof ChannelAddCancelledError)return;e.error(t instanceof Error?t.message:String(t)),process.exitCode=1}}async function runChannelsListCommand(e,t,i){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}let a=await listAuthoredChannels(t);if(i.json){e.log(JSON.stringify({channels:a},null,2));return}if(a.length===0){e.log("No channels defined. Run `ash channels add` to add one.");return}for(let t of a)e.log(t)}export{runChannelsAddCommand,runChannelsListCommand};

package/dist/src/compiler/manifest.d.ts

@@ -18,7 +18,7 @@ export declare const ROOT_COMPILED_AGENT_NODE_ID = "__root__";
 /**
  * Current compiled manifest schema version.
  */
-export declare const COMPILED_AGENT_MANIFEST_VERSION = 26;
+export declare const COMPILED_AGENT_MANIFEST_VERSION = 27;
 /**
  * Compiled channel entry preserved in the compiled manifest.
  */
@@ -189,6 +189,8 @@ declare const compiledSandboxDefinitionSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     exportName: z.ZodOptional<z.ZodString>;
     logicalPath: z.ZodString;
+    revalidationKey: z.ZodOptional<z.ZodString>;
+    sourceHash: z.ZodString;
     sourceId: z.ZodString;
     sourceKind: z.ZodLiteral<"module">;
 }, z.core.$strict>;
@@ -248,6 +250,8 @@ declare const compiledAgentNodeManifestSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         exportName: z.ZodOptional<z.ZodString>;
         logicalPath: z.ZodString;
+        revalidationKey: z.ZodOptional<z.ZodString>;
+        sourceHash: z.ZodString;
         sourceId: z.ZodString;
         sourceKind: z.ZodLiteral<"module">;
     }, z.core.$strict>>;
@@ -358,6 +362,8 @@ export declare const compiledAgentManifestSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         exportName: z.ZodOptional<z.ZodString>;
         logicalPath: z.ZodString;
+        revalidationKey: z.ZodOptional<z.ZodString>;
+        sourceHash: z.ZodString;
         sourceId: z.ZodString;
         sourceKind: z.ZodLiteral<"module">;
     }, z.core.$strict>>;
@@ -408,7 +414,7 @@ export declare const compiledAgentManifestSchema: z.ZodObject<{
         sourceId: z.ZodString;
         sourceKind: z.ZodLiteral<"module">;
     }, z.core.$strict>>;
-    version: z.ZodLiteral<26>;
+    version: z.ZodLiteral<27>;
     workspaceResourceRoot: z.ZodObject<{
         contentHash: z.ZodOptional<z.ZodString>;
         logicalPath: z.ZodString;

package/dist/src/compiler/manifest.js

@@ -1 +1 @@
-import{z}from"#compiled/zod/index.js";import{discoverDiagnosticsSummarySchema}from"#discover/diagnostics.js";import{compiledRemoteAgentNodeSchema}from"#compiler/remote-agent-node.js";import{jsonObjectSchema}from"#shared/json-schemas.js";const COMPILED_AGENT_MANIFEST_KIND=`ash-agent-compiled-manifest`,ROOT_COMPILED_AGENT_NODE_ID=`__root__`,COMPILED_AGENT_MANIFEST_VERSION=26,moduleSourceRefSchema=z.object({exportName:z.string().optional(),sourceKind:z.literal(`module`),logicalPath:z.string(),sourceId:z.string()}).strict(),channelMethodSchema=z.union([z.literal(`GET`),z.literal(`POST`),z.literal(`PUT`),z.literal(`PATCH`),z.literal(`DELETE`)]),compiledChannelDefinitionSchema=z.object({kind:z.literal(`channel`),name:z.string(),logicalPath:z.string(),method:channelMethodSchema,urlPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),exportName:z.string().optional(),adapterKind:z.string().optional()}).strict(),disabledCompiledChannelEntrySchema=z.object({kind:z.literal(`disabled`),name:z.string(),logicalPath:z.string()}).strict(),compiledChannelEntrySchema=z.union([compiledChannelDefinitionSchema,disabledCompiledChannelEntrySchema]),compiledRuntimeModelReferenceSchema=z.object({contextWindowTokens:z.number().int().positive().optional(),id:z.string(),source:moduleSourceRefSchema.optional(),providerOptions:z.record(z.string(),jsonObjectSchema).optional()}).strict(),compiledAgentBuildDefinitionSchema=z.object({externalDependencies:z.array(z.string()).optional()}).strict(),compiledAgentCompactionDefinitionSchema=z.object({model:compiledRuntimeModelReferenceSchema.optional(),thresholdPercent:z.number().finite().min(0).max(1).optional()}).strict(),compiledAgentConfigSchema=z.object({build:compiledAgentBuildDefinitionSchema.optional(),compaction:compiledAgentCompactionDefinitionSchema.optional(),description:z.string().optional(),experimental:z.object({codeMode:z.boolean().optional()}).strict().optional(),model:compiledRuntimeModelReferenceSchema,name:z.string(),outputSchema:jsonObjectSchema.optional(),source:moduleSourceRefSchema.optional()}).strict(),compiledInstructionsSchema=z.object({name:z.string(),logicalPath:z.string(),markdown:z.string(),sourceId:z.string(),sourceKind:z.union([z.literal(`markdown`),z.literal(`module`)])}).strict(),compiledSkillBaseFields={name:z.string(),description:z.string(),license:z.string().optional(),markdown:z.string(),metadata:z.record(z.string(),z.string()).optional(),sourceId:z.string(),logicalPath:z.string()},compiledSkillSourceSchema=z.discriminatedUnion(`sourceKind`,[z.object({...compiledSkillBaseFields,sourceKind:z.literal(`markdown`)}).strict(),z.object({...compiledSkillBaseFields,sourceKind:z.literal(`module`),exportName:z.string().optional()}).strict(),z.object({...compiledSkillBaseFields,sourceKind:z.literal(`skill-package`),skillId:z.string(),skillFilePath:z.string(),rootPath:z.string(),assetsPath:z.string().optional(),referencesPath:z.string().optional(),scriptsPath:z.string().optional()}).strict()]),compiledScheduleDefinitionSchema=z.object({cron:z.string(),hasRun:z.boolean(),name:z.string(),logicalPath:z.string(),markdown:z.string().optional(),sourceId:z.string(),sourceKind:z.union([z.literal(`markdown`),z.literal(`module`)])}).strict(),compiledSandboxDefinitionSchema=z.object({description:z.string().optional(),exportName:z.string().optional(),logicalPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledSandboxWorkspaceSchema=z.object({logicalPath:z.string(),rootEntries:z.array(z.string()).readonly(),sourceId:z.string(),sourcePath:z.string()}).strict(),compiledWorkspaceResourceRootSchema=z.object({contentHash:z.string().optional(),logicalPath:z.string(),rootEntries:z.array(z.string()).readonly()}).strict(),compiledConnectionDefinitionSchema=z.object({connectionName:z.string(),description:z.string(),exportName:z.string().optional(),logicalPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),url:z.string(),vercelConnect:z.object({connector:z.string()}).strict().optional()}).strict(),compiledToolDefinitionSchema=z.object({description:z.string(),exportName:z.string().optional(),inputSchema:jsonObjectSchema.nullable(),logicalPath:z.string(),name:z.string(),outputSchema:jsonObjectSchema.optional(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicToolDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicSkillDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicInstructionsDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledHookDefinitionSchema=z.object({exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledAgentNodeManifestSchema=z.object({agentRoot:z.string(),appRoot:z.string(),channels:z.array(compiledChannelEntrySchema),config:compiledAgentConfigSchema,connections:z.array(compiledConnectionDefinitionSchema),diagnosticsSummary:discoverDiagnosticsSummarySchema,disabledFrameworkTools:z.array(z.string()).readonly(),dynamicInstructions:z.array(compiledDynamicInstructionsDefinitionSchema).default([]),dynamicSkills:z.array(compiledDynamicSkillDefinitionSchema).default([]),dynamicTools:z.array(compiledDynamicToolDefinitionSchema).default([]),hooks:z.array(compiledHookDefinitionSchema),sandbox:compiledSandboxDefinitionSchema.nullable(),sandboxWorkspaces:z.array(compiledSandboxWorkspaceSchema),schedules:z.array(compiledScheduleDefinitionSchema),remoteAgents:z.array(compiledRemoteAgentNodeSchema),skills:z.array(compiledSkillSourceSchema).readonly(),instructions:compiledInstructionsSchema.optional(),tools:z.array(compiledToolDefinitionSchema),workspaceResourceRoot:compiledWorkspaceResourceRootSchema}).strict(),compiledSubagentNodeSchema=z.object({agent:compiledAgentNodeManifestSchema,description:z.string(),entryPath:z.string(),logicalPath:z.string(),name:z.string(),nodeId:z.string(),rootPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),exportName:z.string().optional()}).strict(),compiledSubagentEdgeSchema=z.object({childNodeId:z.string(),parentNodeId:z.string()}).strict(),compiledAgentManifestSchema=z.object({agentRoot:z.string(),appRoot:z.string(),channels:z.array(compiledChannelEntrySchema),config:compiledAgentConfigSchema,connections:z.array(compiledConnectionDefinitionSchema),diagnosticsSummary:discoverDiagnosticsSummarySchema,disabledFrameworkTools:z.array(z.string()).readonly(),dynamicInstructions:z.array(compiledDynamicInstructionsDefinitionSchema).default([]),dynamicSkills:z.array(compiledDynamicSkillDefinitionSchema).default([]),dynamicTools:z.array(compiledDynamicToolDefinitionSchema).default([]),hooks:z.array(compiledHookDefinitionSchema),kind:z.literal(COMPILED_AGENT_MANIFEST_KIND),remoteAgents:z.array(compiledRemoteAgentNodeSchema),sandbox:compiledSandboxDefinitionSchema.nullable(),sandboxWorkspaces:z.array(compiledSandboxWorkspaceSchema),schedules:z.array(compiledScheduleDefinitionSchema),skills:z.array(compiledSkillSourceSchema).readonly(),subagentEdges:z.array(compiledSubagentEdgeSchema),subagents:z.array(compiledSubagentNodeSchema),instructions:compiledInstructionsSchema.optional(),tools:z.array(compiledToolDefinitionSchema),version:z.literal(26),workspaceResourceRoot:compiledWorkspaceResourceRootSchema}).strict();function createCompiledAgentNodeManifest(e){let t={agentRoot:e.agentRoot,appRoot:e.appRoot,channels:[...e.channels??[]],connections:[...e.connections??[]],config:{build:e.config.build===void 0?void 0:{externalDependencies:e.config.build.externalDependencies===void 0?void 0:[...e.config.build.externalDependencies]},compaction:{model:e.config.compaction?.model===void 0?void 0:cloneCompiledRuntimeModelReference(e.config.compaction.model),thresholdPercent:e.config.compaction?.thresholdPercent},description:e.config.description,experimental:e.config.experimental===void 0?void 0:{codeMode:e.config.experimental.codeMode},model:cloneCompiledRuntimeModelReference(e.config.model),name:e.config.name,outputSchema:e.config.outputSchema,source:e.config.source===void 0?void 0:{...e.config.source}},diagnosticsSummary:e.diagnosticsSummary??{errors:0,warnings:0},disabledFrameworkTools:[...e.disabledFrameworkTools??[]],dynamicInstructions:[...e.dynamicInstructions??[]],dynamicSkills:[...e.dynamicSkills??[]],dynamicTools:[...e.dynamicTools??[]],hooks:[...e.hooks??[]],remoteAgents:[...e.remoteAgents??[]],sandbox:e.sandbox??null,sandboxWorkspaces:[...e.sandboxWorkspaces??[]],schedules:[...e.schedules??[]],skills:[...e.skills??[]],tools:[...e.tools??[]],workspaceResourceRoot:e.workspaceResourceRoot??{logicalPath:``,rootEntries:deriveResourceRootEntries({sandboxWorkspaces:e.sandboxWorkspaces,skills:e.skills})}};return e.instructions!==void 0&&(t.instructions=e.instructions),t}function deriveResourceRootEntries(e){let t=new Set;(e.skills??[]).length>0&&t.add(`skills/`);for(let n of e.sandboxWorkspaces??[])for(let e of n.rootEntries)t.add(e);return[...t].sort((e,t)=>e.localeCompare(t))}function createCompiledSubagentNodeId(e,t){return e===`__root__`?t:`${e}::${t}`}function createCompiledAgentManifest(e){return{...createCompiledAgentNodeManifest(e),kind:COMPILED_AGENT_MANIFEST_KIND,subagentEdges:[...e.subagentEdges??[]],subagents:[...e.subagents??[]],version:26}}function cloneCompiledRuntimeModelReference(e){return e.contextWindowTokens===void 0&&e.source===void 0&&e.providerOptions===void 0?{id:e.id}:e.source===void 0?e.providerOptions===void 0?{contextWindowTokens:e.contextWindowTokens,id:e.id}:{contextWindowTokens:e.contextWindowTokens,id:e.id,providerOptions:{...e.providerOptions}}:e.contextWindowTokens===void 0&&e.providerOptions===void 0?{id:e.id,source:{...e.source}}:{contextWindowTokens:e.contextWindowTokens,id:e.id,providerOptions:e.providerOptions===void 0?void 0:{...e.providerOptions},source:{...e.source}}}export{COMPILED_AGENT_MANIFEST_KIND,COMPILED_AGENT_MANIFEST_VERSION,ROOT_COMPILED_AGENT_NODE_ID,compiledAgentManifestSchema,createCompiledAgentManifest,createCompiledAgentNodeManifest,createCompiledSubagentNodeId,deriveResourceRootEntries};
+import{z}from"#compiled/zod/index.js";import{discoverDiagnosticsSummarySchema}from"#discover/diagnostics.js";import{compiledRemoteAgentNodeSchema}from"#compiler/remote-agent-node.js";import{jsonObjectSchema}from"#shared/json-schemas.js";const COMPILED_AGENT_MANIFEST_KIND=`ash-agent-compiled-manifest`,ROOT_COMPILED_AGENT_NODE_ID=`__root__`,COMPILED_AGENT_MANIFEST_VERSION=27,moduleSourceRefSchema=z.object({exportName:z.string().optional(),sourceKind:z.literal(`module`),logicalPath:z.string(),sourceId:z.string()}).strict(),channelMethodSchema=z.union([z.literal(`GET`),z.literal(`POST`),z.literal(`PUT`),z.literal(`PATCH`),z.literal(`DELETE`)]),compiledChannelDefinitionSchema=z.object({kind:z.literal(`channel`),name:z.string(),logicalPath:z.string(),method:channelMethodSchema,urlPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),exportName:z.string().optional(),adapterKind:z.string().optional()}).strict(),disabledCompiledChannelEntrySchema=z.object({kind:z.literal(`disabled`),name:z.string(),logicalPath:z.string()}).strict(),compiledChannelEntrySchema=z.union([compiledChannelDefinitionSchema,disabledCompiledChannelEntrySchema]),compiledRuntimeModelReferenceSchema=z.object({contextWindowTokens:z.number().int().positive().optional(),id:z.string(),source:moduleSourceRefSchema.optional(),providerOptions:z.record(z.string(),jsonObjectSchema).optional()}).strict(),compiledAgentBuildDefinitionSchema=z.object({externalDependencies:z.array(z.string()).optional()}).strict(),compiledAgentCompactionDefinitionSchema=z.object({model:compiledRuntimeModelReferenceSchema.optional(),thresholdPercent:z.number().finite().min(0).max(1).optional()}).strict(),compiledAgentConfigSchema=z.object({build:compiledAgentBuildDefinitionSchema.optional(),compaction:compiledAgentCompactionDefinitionSchema.optional(),description:z.string().optional(),experimental:z.object({codeMode:z.boolean().optional()}).strict().optional(),model:compiledRuntimeModelReferenceSchema,name:z.string(),outputSchema:jsonObjectSchema.optional(),source:moduleSourceRefSchema.optional()}).strict(),compiledInstructionsSchema=z.object({name:z.string(),logicalPath:z.string(),markdown:z.string(),sourceId:z.string(),sourceKind:z.union([z.literal(`markdown`),z.literal(`module`)])}).strict(),compiledSkillBaseFields={name:z.string(),description:z.string(),license:z.string().optional(),markdown:z.string(),metadata:z.record(z.string(),z.string()).optional(),sourceId:z.string(),logicalPath:z.string()},compiledSkillSourceSchema=z.discriminatedUnion(`sourceKind`,[z.object({...compiledSkillBaseFields,sourceKind:z.literal(`markdown`)}).strict(),z.object({...compiledSkillBaseFields,sourceKind:z.literal(`module`),exportName:z.string().optional()}).strict(),z.object({...compiledSkillBaseFields,sourceKind:z.literal(`skill-package`),skillId:z.string(),skillFilePath:z.string(),rootPath:z.string(),assetsPath:z.string().optional(),referencesPath:z.string().optional(),scriptsPath:z.string().optional()}).strict()]),compiledScheduleDefinitionSchema=z.object({cron:z.string(),hasRun:z.boolean(),name:z.string(),logicalPath:z.string(),markdown:z.string().optional(),sourceId:z.string(),sourceKind:z.union([z.literal(`markdown`),z.literal(`module`)])}).strict(),compiledSandboxDefinitionSchema=z.object({description:z.string().optional(),exportName:z.string().optional(),logicalPath:z.string(),revalidationKey:z.string().optional(),sourceHash:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledSandboxWorkspaceSchema=z.object({logicalPath:z.string(),rootEntries:z.array(z.string()).readonly(),sourceId:z.string(),sourcePath:z.string()}).strict(),compiledWorkspaceResourceRootSchema=z.object({contentHash:z.string().optional(),logicalPath:z.string(),rootEntries:z.array(z.string()).readonly()}).strict(),compiledConnectionDefinitionSchema=z.object({connectionName:z.string(),description:z.string(),exportName:z.string().optional(),logicalPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),url:z.string(),vercelConnect:z.object({connector:z.string()}).strict().optional()}).strict(),compiledToolDefinitionSchema=z.object({description:z.string(),exportName:z.string().optional(),inputSchema:jsonObjectSchema.nullable(),logicalPath:z.string(),name:z.string(),outputSchema:jsonObjectSchema.optional(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicToolDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicSkillDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledDynamicInstructionsDefinitionSchema=z.object({eventNames:z.array(z.string()).readonly(),exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledHookDefinitionSchema=z.object({exportName:z.string().optional(),logicalPath:z.string(),slug:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`)}).strict(),compiledAgentNodeManifestSchema=z.object({agentRoot:z.string(),appRoot:z.string(),channels:z.array(compiledChannelEntrySchema),config:compiledAgentConfigSchema,connections:z.array(compiledConnectionDefinitionSchema),diagnosticsSummary:discoverDiagnosticsSummarySchema,disabledFrameworkTools:z.array(z.string()).readonly(),dynamicInstructions:z.array(compiledDynamicInstructionsDefinitionSchema).default([]),dynamicSkills:z.array(compiledDynamicSkillDefinitionSchema).default([]),dynamicTools:z.array(compiledDynamicToolDefinitionSchema).default([]),hooks:z.array(compiledHookDefinitionSchema),sandbox:compiledSandboxDefinitionSchema.nullable(),sandboxWorkspaces:z.array(compiledSandboxWorkspaceSchema),schedules:z.array(compiledScheduleDefinitionSchema),remoteAgents:z.array(compiledRemoteAgentNodeSchema),skills:z.array(compiledSkillSourceSchema).readonly(),instructions:compiledInstructionsSchema.optional(),tools:z.array(compiledToolDefinitionSchema),workspaceResourceRoot:compiledWorkspaceResourceRootSchema}).strict(),compiledSubagentNodeSchema=z.object({agent:compiledAgentNodeManifestSchema,description:z.string(),entryPath:z.string(),logicalPath:z.string(),name:z.string(),nodeId:z.string(),rootPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),exportName:z.string().optional()}).strict(),compiledSubagentEdgeSchema=z.object({childNodeId:z.string(),parentNodeId:z.string()}).strict(),compiledAgentManifestSchema=z.object({agentRoot:z.string(),appRoot:z.string(),channels:z.array(compiledChannelEntrySchema),config:compiledAgentConfigSchema,connections:z.array(compiledConnectionDefinitionSchema),diagnosticsSummary:discoverDiagnosticsSummarySchema,disabledFrameworkTools:z.array(z.string()).readonly(),dynamicInstructions:z.array(compiledDynamicInstructionsDefinitionSchema).default([]),dynamicSkills:z.array(compiledDynamicSkillDefinitionSchema).default([]),dynamicTools:z.array(compiledDynamicToolDefinitionSchema).default([]),hooks:z.array(compiledHookDefinitionSchema),kind:z.literal(COMPILED_AGENT_MANIFEST_KIND),remoteAgents:z.array(compiledRemoteAgentNodeSchema),sandbox:compiledSandboxDefinitionSchema.nullable(),sandboxWorkspaces:z.array(compiledSandboxWorkspaceSchema),schedules:z.array(compiledScheduleDefinitionSchema),skills:z.array(compiledSkillSourceSchema).readonly(),subagentEdges:z.array(compiledSubagentEdgeSchema),subagents:z.array(compiledSubagentNodeSchema),instructions:compiledInstructionsSchema.optional(),tools:z.array(compiledToolDefinitionSchema),version:z.literal(27),workspaceResourceRoot:compiledWorkspaceResourceRootSchema}).strict();function createCompiledAgentNodeManifest(e){let t={agentRoot:e.agentRoot,appRoot:e.appRoot,channels:[...e.channels??[]],connections:[...e.connections??[]],config:{build:e.config.build===void 0?void 0:{externalDependencies:e.config.build.externalDependencies===void 0?void 0:[...e.config.build.externalDependencies]},compaction:{model:e.config.compaction?.model===void 0?void 0:cloneCompiledRuntimeModelReference(e.config.compaction.model),thresholdPercent:e.config.compaction?.thresholdPercent},description:e.config.description,experimental:e.config.experimental===void 0?void 0:{codeMode:e.config.experimental.codeMode},model:cloneCompiledRuntimeModelReference(e.config.model),name:e.config.name,outputSchema:e.config.outputSchema,source:e.config.source===void 0?void 0:{...e.config.source}},diagnosticsSummary:e.diagnosticsSummary??{errors:0,warnings:0},disabledFrameworkTools:[...e.disabledFrameworkTools??[]],dynamicInstructions:[...e.dynamicInstructions??[]],dynamicSkills:[...e.dynamicSkills??[]],dynamicTools:[...e.dynamicTools??[]],hooks:[...e.hooks??[]],remoteAgents:[...e.remoteAgents??[]],sandbox:e.sandbox??null,sandboxWorkspaces:[...e.sandboxWorkspaces??[]],schedules:[...e.schedules??[]],skills:[...e.skills??[]],tools:[...e.tools??[]],workspaceResourceRoot:e.workspaceResourceRoot??{logicalPath:``,rootEntries:deriveResourceRootEntries({sandboxWorkspaces:e.sandboxWorkspaces,skills:e.skills})}};return e.instructions!==void 0&&(t.instructions=e.instructions),t}function deriveResourceRootEntries(e){let t=new Set;(e.skills??[]).length>0&&t.add(`skills/`);for(let n of e.sandboxWorkspaces??[])for(let e of n.rootEntries)t.add(e);return[...t].sort((e,t)=>e.localeCompare(t))}function createCompiledSubagentNodeId(e,t){return e===`__root__`?t:`${e}::${t}`}function createCompiledAgentManifest(e){return{...createCompiledAgentNodeManifest(e),kind:COMPILED_AGENT_MANIFEST_KIND,subagentEdges:[...e.subagentEdges??[]],subagents:[...e.subagents??[]],version:27}}function cloneCompiledRuntimeModelReference(e){return e.contextWindowTokens===void 0&&e.source===void 0&&e.providerOptions===void 0?{id:e.id}:e.source===void 0?e.providerOptions===void 0?{contextWindowTokens:e.contextWindowTokens,id:e.id}:{contextWindowTokens:e.contextWindowTokens,id:e.id,providerOptions:{...e.providerOptions}}:e.contextWindowTokens===void 0&&e.providerOptions===void 0?{id:e.id,source:{...e.source}}:{contextWindowTokens:e.contextWindowTokens,id:e.id,providerOptions:e.providerOptions===void 0?void 0:{...e.providerOptions},source:{...e.source}}}export{COMPILED_AGENT_MANIFEST_KIND,COMPILED_AGENT_MANIFEST_VERSION,ROOT_COMPILED_AGENT_NODE_ID,compiledAgentManifestSchema,createCompiledAgentManifest,createCompiledAgentNodeManifest,createCompiledSubagentNodeId,deriveResourceRootEntries};

package/dist/src/compiler/normalize-sandbox.js

@@ -1 +1 @@
-import{loadModuleBackedDefinition}from"#compiler/normalize-helpers.js";import{normalizeSandboxDefinition}from"#internal/authored-definition/sandbox.js";async function compileSandboxDefinition(e,t){return{description:normalizeSandboxDefinition(await loadModuleBackedDefinition({agentRoot:e,kind:`sandbox`,source:t}),`Expected the sandbox export "${t.exportName??`default`}" from "${t.logicalPath}" to match the public Ash shape.`).description,exportName:t.exportName,logicalPath:t.logicalPath,sourceId:t.sourceId,sourceKind:`module`}}export{compileSandboxDefinition};
+import{join}from"node:path";import{readFile}from"node:fs/promises";import{toErrorMessage}from"#shared/errors.js";import{createHash}from"node:crypto";import{loadModuleBackedDefinition}from"#compiler/normalize-helpers.js";import{normalizeSandboxDefinition}from"#internal/authored-definition/sandbox.js";async function compileSandboxDefinition(e,t){let n=`Expected the sandbox export "${t.exportName??`default`}" from "${t.logicalPath}" to match the public Ash shape.`,r=normalizeSandboxDefinition(await loadModuleBackedDefinition({agentRoot:e,kind:`sandbox`,source:t}),n),o=r.revalidationKey===void 0?void 0:await resolveSandboxRevalidationKey({message:n,revalidationKey:r.revalidationKey,source:t});return{description:r.description,exportName:t.exportName,logicalPath:t.logicalPath,revalidationKey:o,sourceHash:await resolveSandboxSourceHash(e,t),sourceId:t.sourceId,sourceKind:`module`}}async function resolveSandboxRevalidationKey(e){let t;try{t=await e.revalidationKey()}catch(t){throw Error(`${e.message} Failed to execute the "revalidationKey" function from "${e.source.logicalPath}": ${toErrorMessage(t)}`)}if(typeof t!=`string`)throw Error(`${e.message} The "revalidationKey" function must return a string.`);if(t.trim().length===0)throw Error(`${e.message} The "revalidationKey" function must return a non-empty string.`);return t}async function resolveSandboxSourceHash(n,i){let a=await readFile(join(n,i.logicalPath));return createHash(`sha256`).update(a).digest(`hex`)}export{compileSandboxDefinition};