experimental-ash 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # experimental-ash
 
+## 0.53.0
+
+### Minor Changes
+
+- 3ea7d16: Expose the parent subagent tool call id on `ctx.session.parent.callId` for local subagent sessions. Subagent workflow runs now use `$ash.parent` for the parent session id and add `$ash.parent_call` / `$ash.parent_turn` for lineage queries.
+
+## 0.52.0
+
+### Minor Changes
+
+- 56fdb14: `ash info --json` now emits a machine-readable view of the compiled agent (status, channels, tools, model, and message routes), and `ash channels add <kind> --yes` skips Ash confirmations for non-interactive use. Slack setup still runs Vercel Connect's interactive OAuth flow before attaching the connector to the Ash route.
+- d486e9e: Rename cross-channel receive options from `args` to `target`. Channel receive hooks now read `input.target`, and native channel receive target types use the `*ReceiveTarget` naming.
+- b91b550: Breaking: replace `defineInstrumentation({ metadata })` with `defineInstrumentation({ events: { "step.started": () => ({ runtimeContext }) } })` for per-step AI SDK telemetry context.
+
 ## 0.51.0
 
 ### Minor Changes

package/dist/docs/public/advanced/instrumentation.md

@@ -1,14 +1,28 @@
 ---
 title: "instrumentation.ts"
-description: "Configure OpenTelemetry exporters and AI SDK span behavior for your agent."
+description: "Configure OpenTelemetry export and per-call AI SDK span context for your agent, and read the workflow run tags Ash emits automatically."
 url: /instrumentation
 ---
 
-`instrumentation.ts` is the single place to configure OpenTelemetry for an Ash agent. It controls
-both _where_ spans are exported and _what_ the AI SDK records in those spans.
+`instrumentation.ts` is where you configure how an Ash agent is observed. The framework
+auto-discovers `agent/instrumentation.ts` and runs it at server startup before any agent code. Its
+presence implicitly enables telemetry -- there is no separate `isEnabled` toggle.
 
-The framework auto-discovers `agent/instrumentation.ts` and runs it at server startup before any
-agent code.
+## Three observability surfaces
+
+Ash observes an agent through three distinct surfaces. They do not all live in this file, and they
+write to different places -- so it helps to keep them apart:
+
+| Surface                          | Configured in `instrumentation.ts`?                           | What it is                                                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Workflow run tags** (`$ash.*`) | No -- automatic                                               | Framework-owned attributes on each Vercel Workflow run. Let dashboards stitch session/turn/subagent runs into a tree and surface model and token usage. |
+| **OpenTelemetry export**         | Yes -- `setup`, `recordInputs`, `recordOutputs`, `functionId` | Where AI SDK spans are exported and what they record.                                                                                                   |
+| **Runtime context events**       | Yes -- `events["step.started"]`                               | Per-model-call values written into the AI SDK's runtime context, which the AI SDK carries onto its spans.                                               |
+
+The two configurable surfaces send AI SDK spans to your OpenTelemetry backend. Workflow run tags are
+a separate system: they live on the Vercel Workflow run and are queryable in the Workflow dashboard,
+not on your OTel spans. The sections below cover what you configure here;
+[Workflow run tags](#workflow-run-tags) documents what Ash emits on its own.
 
 ## The Main API
 
@@ -30,123 +44,67 @@ export default defineInstrumentation({
 });
 ```
 
-Export the result of `defineInstrumentation` as the default export. Its presence implicitly enables
-telemetry -- there is no separate `isEnabled` toggle.
+Export the result of `defineInstrumentation` as the default export.
 
-## `setup`
+## OpenTelemetry
 
 The `setup` callback is invoked by the framework at server startup with the resolved agent name. Use
 it to register your OTel provider (e.g. `registerOTel` from `@vercel/otel`). The
-`context.agentName` is derived from the agent's filesystem path at compile time, so you never need
-to hard-code a service name.
+`context.agentName` is resolved at compile time from your project -- the package's `name`, falling
+back to the app directory name -- so you never need to hard-code a service name.
 
 Any OTel-compatible backend works (Braintrust, Honeycomb, Datadog, Jaeger). Install the exporter
 package you need and configure it in the callback.
 
-## AI SDK Span Settings
-
-These fields control what the AI SDK records inside OTel spans:
+Three more fields control what the AI SDK records inside those spans (see the AI SDK's
+[telemetry reference](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)):
 
 - `recordInputs` -- record full message history on each step span (defaults to `true`). Set to
-  `false` to disable if inputs contain sensitive content or you want to reduce span payload size.
+  `false` if inputs contain sensitive content or you want to reduce span payload size.
 - `recordOutputs` -- record model outputs on spans (defaults to `true`). Set to `false` to disable
   output recording.
-- `functionId` -- override the function name on spans (defaults to the agent name)
-- `metadata["step.started"]` -- a synchronous callback that returns key-value pairs for one
-  model-call attempt
-
-## Metadata
-
-Use `metadata["step.started"]` when the metadata depends on the current session, turn, step,
-channel, or model input:
-
-```ts
-import { defineInstrumentation } from "experimental-ash/instrumentation";
-
-export default defineInstrumentation({
-  metadata: {
-    "step.started"(input) {
-      if (input.channel.kind !== "channel:support") {
-        return {};
-      }
+- `functionId` -- override the function name on spans (defaults to the agent name).
 
-      return {
-        "slack.channel_id": input.channel.metadata.channelId ?? "",
-        "slack.user_id": input.channel.metadata.triggeringUserId ?? "",
-      };
-    },
-  },
-});
-```
-
-For authored channels, TypeScript gets channel metadata types from a compiler-owned declaration
-file. When Ash compiles `agent/channels/support.ts`, it writes
-`.ash/compile/channel-instrumentation-types.d.ts` with a `ChannelMetadataMap` entry for the
-filename-derived kind and a `ChannelReferenceMap` entry for `isChannel`:
+The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call
+values to these spans.
 
-```ts
-import type { InferChannelMetadata } from "experimental-ash/channels";
-
-declare module "experimental-ash/instrumentation" {
-  interface ChannelMetadataMap {
-    readonly "channel:support": InferChannelMetadata<
-      typeof import("../../agent/channels/support.js").default
-    >;
-  }
-  interface ChannelReferenceMap {
-    readonly "channel:support": typeof import("../../agent/channels/support.js").default;
-  }
-}
-```
+## Runtime Context
 
-Keep `.ash/**/*.d.ts` in your app's `tsconfig.json` `include` list so TypeScript sees that file.
-Then either `input.channel.kind === "channel:support"` or `isChannel(input.channel, supportChannel)`
-narrows `input.channel.metadata` to the return type of the channel's `metadata(state)` function:
+_Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text):
+a user-defined object that flows through a generation lifecycle. Ash exposes it through
+`events["step.started"]`, a callback that runs once Ash has assembled the model input for an attempt
+and returns `{ runtimeContext }`. Because Ash registers the AI SDK's OpenTelemetry integration with runtime
+context enabled, those returned values ride onto the model-call span and its children -- that is the
+reason this surface exists. The returned field is named `runtimeContext`, not `metadata`, because AI
+SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
 
-```ts
-// agent/channels/support.ts
-import { defineChannel, POST } from "experimental-ash/channels";
-
-export default defineChannel({
-  state: { ticketId: null as string | null },
-  // Ash uses this function's runtime value for instrumentation metadata and
-  // makes its return type available to instrumentation.ts.
-  metadata(state) {
-    return { ticketId: state.ticketId };
-  },
-  routes: [POST("/support", async () => new Response("ok"))],
-});
-```
+Use it when the values depend on the current session, turn, step, channel, or model input:
 
 ```ts
-// agent/instrumentation.ts
 import { defineInstrumentation, isChannel } from "experimental-ash/instrumentation";
-
 import supportChannel from "./channels/support.js";
 
 export default defineInstrumentation({
-  metadata: {
+  events: {
     "step.started"(input) {
       if (!isChannel(input.channel, supportChannel)) {
-        return {};
+        return undefined;
       }
 
       return {
-        "support.ticket_id": input.channel.metadata.ticketId ?? "",
+        runtimeContext: {
+          "support.channel_id": input.channel.metadata.channelId ?? "",
+          "support.user_id": input.channel.metadata.triggeringUserId ?? "",
+        },
       };
     },
   },
 });
 ```
 
-Built-in wrapper return types expose their concrete metadata too. For example, a file named
-`agent/channels/support.ts` that default-exports `slackChannel()` still narrows under
-`input.channel.kind === "channel:support"` to Slack's projected metadata shape.
-
-The callback runs after Ash has assembled the model input for the attempt and before constructing
-the AI SDK call. That timing lets the returned values attach to the AI SDK model-call span and its
-child spans. It runs for each model-call attempt, including a retry of the same logical step when
-Ash changes provider settings or instructions.
+For authored channels, Ash emits compiler-owned typings keyed by the channel filename. A file at
+`agent/channels/support.ts` narrows as `channel:support`, either by checking
+`input.channel.kind === "channel:support"` or by using `isChannel(input.channel, supportChannel)`.
 
 The callback receives:
 
@@ -160,7 +118,8 @@ The callback receives:
 A channel exposes its identity through `kind`: the discriminant you narrow on. For authored
 channels it is `channel:<name>`, where `<name>` is the channel's filename under
 `agent/channels/` — `agent/channels/support.ts` is `channel:support`. Framework channels use
-`http`, `schedule`, or `subagent`. It is also emitted as the `ash.channel.kind` span attribute.
+`http`, `schedule`, or `subagent`; an unrecognized or absent kind normalizes to `unknown`. The kind
+is also emitted as the `ash.channel.kind` span attribute.
 
 Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make
 observable; for example, Slack projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId`
@@ -168,36 +127,12 @@ from its durable channel state. User-authored channels expose their own projecti
 `metadata(state)` from `defineChannel`. Runtime instrumentation never falls back to raw channel
 state.
 
-`metadata(state)` must return an object composed of JSON primitives, arrays, and plain objects.
-Ash omits `undefined` object properties and drops projections containing values such as `Date` or
-`Map` with a warning.
-
-Manual `ChannelMetadataMap` declaration merging is only the escape hatch for unusual setups where
-the generated `.ash/**/*.d.ts` file is not available to the TypeScript program, or where a channel
-is typed outside the normal `agent/channels/<name>` compile path:
-
-```ts
-import type { SlackInstrumentationMetadata } from "experimental-ash/channels/slack";
-
-declare module "experimental-ash/instrumentation" {
-  interface ChannelMetadataMap {
-    readonly "channel:support": SlackInstrumentationMetadata;
-  }
-}
-```
-
-Metadata failures are non-destructive. If the callback throws, returns a non-record, or returns
-non-string values, Ash logs a warning, drops the invalid metadata, and continues the model call.
-Thenables are rejected; the callback is intentionally synchronous. Keys beginning with `ash.` are
-reserved, so authored metadata cannot override framework metadata. Instrumentation projections
-containing values outside the JSON shape, such as `Date` or `Map`, are dropped with a warning.
-
 ## Trace Hierarchy
 
 When telemetry is enabled, each turn produces a trace like:
 
 ```text
-ash.turn  {ash.session.id, ash.turn.id}
+ai.ash.turn  {ash.session.id}
   +-- ai.streamText                           step 1
   |     +-- ai.streamText.doStream            model call
   |     +-- ai.toolCall  {toolName: search}   tool exec
@@ -207,10 +142,43 @@ ash.turn  {ash.session.id, ash.turn.id}
   +-- ai.streamText                           step 3 (final text)
 ```
 
-Ash creates the `ash.turn` parent span per turn and passes enriched telemetry to the AI SDK so model
-calls and tool executions are traced automatically. Session, turn, step, and channel context
-(`ash.version`, `ash.session.id`, `ash.environment`, `ash.turn.id`, `ash.turn.sequence`,
-`ash.step.index`, `ash.channel.kind`) is injected into span metadata.
+Ash creates the `ai.ash.turn` parent span per turn and passes enriched telemetry to the AI SDK so model
+calls and tool executions are traced automatically. Session, turn, step, and channel context is
+injected as the framework half of the runtime context (`ash.version`, `ash.session.id`,
+`ash.environment`, `ash.turn.id`, `ash.turn.sequence`, `ash.step.index`, `ash.channel.kind`) and
+rides onto the spans alongside any values your `events["step.started"]` callback returns under
+`runtimeContext`.
+
+## Workflow run tags
+
+Separately from OpenTelemetry, Ash tags every workflow run with reserved `$ash.*` attributes. These
+live on the **Vercel Workflow run** -- queryable in the Workflow dashboard -- not on OTel spans, and
+you do not configure them: they are framework-owned and emitted automatically on every session,
+turn, and subagent run, whether or not an `instrumentation.ts` file is present. Authored code cannot
+set or override the `$ash.` namespace.
+
+Their job is to let a dashboard reconstruct the tree of runs behind a single agent invocation and
+surface model and token usage without reading run bodies.
+
+**Structural tags** describe each run's place in the tree:
+
+- `$ash.type` -- `"session"`, `"turn"`, or `"subagent"`
+- `$ash.parent` -- session id of the immediate parent
+- `$ash.root` -- session id of the root session in the chain (group a whole tree with
+  `$ash.root=<id>`)
+- `$ash.subagent` -- compiled graph node id (subagent runs only)
+- `$ash.trigger` -- the channel kind that started the run
+- `$ash.title` -- truncated title derived from the first user message
+
+**Per-turn usage tags** are written on each step of a turn, accumulating cumulative totals
+(last write wins):
+
+- `$ash.model` -- model id for the turn
+- `$ash.input_tokens`, `$ash.output_tokens`, `$ash.cache_read_tokens` -- running token counts
+- `$ash.tool_count` -- number of tools available to the turn
+
+Tag writes are best-effort: a failure is logged once per process and then swallowed, so a broken tag
+emit never breaks the agent.
 
 ## What To Read Next
 

package/dist/docs/public/advanced/session-context.md

@@ -35,7 +35,8 @@ export default defineTool({
       turnSequence: ctx.session.turn.sequence,
       currentCaller: ctx.session.auth.current?.principalId,
       initiator: ctx.session.auth.initiator?.principalId,
-      parentSessionId: ctx.session.parent?.id,
+      parentSessionId: ctx.session.parent?.sessionId,
+      parentCallId: ctx.session.parent?.callId,
     };
   },
 });
@@ -56,7 +57,8 @@ Important behavior:
 - `auth.initiator` is the caller that started the durable session
 - unprotected agents expose both as `null`
 - top-level schedule sessions expose the framework app principal (`principalId: "ash:app"`, `principalType: "runtime"`)
-- `parent` is present for child subagent sessions
+- `parent` is present for child subagent sessions and includes the parent `callId`, `sessionId`,
+  `rootSessionId`, and `turn`
 
 ## `ctx.getSandbox()`
 

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

@@ -113,6 +113,7 @@ Channel and Slack types exported from `experimental-ash/channels/slack`:
 - `SlackInteractionAction` - action type for `onInteraction`
 - `SlackMentionResult` / `SlackInboundResult` - return type of `onAppMention` / `onDirectMessage`
   (`{ auth, context? } | null`)
+- `SlackReceiveTarget` - target accepted by proactive `receive(slack, ...)`
 - `defaultSlackAuth(message, ctx)` - default Slack actor-to-session-auth projection
 - `Card`, `Button`, `Actions`, `Section`, `Modal`, `Table`, etc. - card builders re-exported for
   rendering Slack messages
@@ -134,6 +135,7 @@ Channel and Twilio types exported from `experimental-ash/channels/twilio`:
 - `TwilioVoiceResult` - call-answering options returned by `onVoice`
 - `TwilioVoiceTranscription` - parsed voice transcript payload (`from`, `to`, `callSid`, `text`,
   `confidence`, ...)
+- `TwilioReceiveTarget` - target accepted by proactive `receive(twilio, ...)`
 - `verifyTwilioRequest`, `signTwilioRequest` - Ash-owned Twilio webhook signature helpers
 
 Channel and Telegram types exported from `experimental-ash/channels/telegram`:
@@ -152,7 +154,7 @@ Channel and Telegram types exported from `experimental-ash/channels/telegram`:
   `attachments`, reply context, ...)
 - `TelegramCallbackQuery` - parsed callback query payload passed to `onCallbackQuery`
 - `TelegramAttachment` - parsed inbound photo or document metadata
-- `TelegramReceiveArgs` - arguments accepted by proactive `receive(telegram, ...)`
+- `TelegramReceiveTarget` - target accepted by proactive `receive(telegram, ...)`
 - `verifyTelegramRequest` - Ash-owned webhook secret-token verification helper
 
 Channel and Microsoft Teams types exported from `experimental-ash/channels/teams`:
@@ -166,7 +168,7 @@ Channel and Microsoft Teams types exported from `experimental-ash/channels/teams
   `updateActivity`, `startTyping`, and `request`
 - `TeamsThread` - conversation-scoped `post`, `update`, `startTyping`, and `mentionUser`
 - `TeamsMessageActivity` / `TeamsInvokeActivity` - parsed inbound Activity payloads
-- `TeamsReceiveArgs` - proactive/cross-channel handoff args requiring `serviceUrl` and
+- `TeamsReceiveTarget` - proactive/cross-channel handoff target requiring `serviceUrl` and
   `conversationId`
 - `teamsContinuationToken` - channel-local Teams continuation-token helper
 - `defaultTeamsAuth` - default Teams actor-to-session-auth projection

package/dist/docs/public/channels/discord.mdx

@@ -143,7 +143,7 @@ Component and modal submissions resume the parked Ash session automatically.
 
 ## Proactive Sessions
 
-Use `receive(discord, { message, args, auth })` from a schedule `run` handler, or
+Use `receive(discord, { message, target, auth })` from a schedule `run` handler, or
 `args.receive(discord, ...)` from another channel, to start a Discord session:
 
 ```ts
@@ -156,7 +156,7 @@ export default defineSchedule({
     waitUntil(
       receive(discord, {
         message: "Post the daily summary.",
-        args: {
+        target: {
           channelId: "123456789012345678",
           initialMessage: "Daily summary",
         },

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

@@ -373,7 +373,7 @@ Adaptive Cards, and sends agent replies through the Bot Framework Connector REST
 resume by conversation id; channel and group-chat threads resume by conversation id plus root
 activity id.
 
-Proactive `receive(teams, args)` sessions require an existing conversation reference
+Proactive `receive(teams, { target })` sessions require an existing conversation reference
 (`serviceUrl` and `conversationId`). See [Microsoft Teams channel setup](./teams.mdx) for Azure Bot
 setup, environment variables, proactive handoff, HITL, and file options.
 
@@ -394,7 +394,7 @@ export default defineChannel({
       args.waitUntil(
         args.receive(slack, {
           message: `Investigate ${incident.reference}: ${incident.title}`,
-          args: { channelId: "C0123ABC" },
+          target: { channelId: "C0123ABC" },
           auth: {
             authenticator: "incidentio",
             principalType: "service",
@@ -412,7 +412,7 @@ export default defineChannel({
 Semantics:
 
 - The target channel's authored `receive(input, { send })` hook owns the continuation-token
-  format and the initial state. Callers supply only `{ message, args, auth }`.
+  format and the initial state. Callers supply only `{ message, target, auth }`.
 - `auth` flows through to `session.auth.initiator` so the target's event handlers and the
   agent's tools can read who started the session.
 - Calling `args.receive(...)` does **not** also start a session on the current channel. The
@@ -441,7 +441,7 @@ import { Card, CardText } from "experimental-ash/channels/slack";
 
 await args.receive(slack, {
   message: "Begin investigation",
-  args: {
+  target: {
     channelId: "C0123ABC",
     initialMessage: {
       card: Card({ children: [CardText("Investigation Thread for INC-42")] }),

package/dist/docs/public/channels/teams.mdx

@@ -84,7 +84,7 @@ invoke activities can be handled with `onInvoke(ctx, activity)`.
 
 ## Proactive Sessions
 
-Use `receive(teams, args)` only when you already have a Teams conversation reference. Teams v1 does
+Use `receive(teams, { target })` only when you already have a Teams conversation reference. Teams v1 does
 not create new chats by AAD user id.
 
 ```ts

package/dist/docs/public/channels/telegram.mdx

@@ -174,7 +174,7 @@ channel posts, stickers, and outbound sandbox-file sharing are not included.
 
 ## Proactive Sessions
 
-Use `receive(telegram, { message, args, auth })` from a schedule `run` handler, or
+Use `receive(telegram, { message, target, auth })` from a schedule `run` handler, or
 `args.receive(telegram, ...)` from another channel, to start a Telegram session:
 
 ```ts
@@ -187,7 +187,7 @@ export default defineSchedule({
     waitUntil(
       receive(telegram, {
         message: "Post the daily summary.",
-        args: {
+        target: {
           chatId: "123456789",
           initialMessage: "Daily summary",
         },

package/dist/docs/public/meta.json

@@ -1,6 +1,7 @@
 {
   "pages": [
     "getting-started",
+    "onboarding",
     "---",
     "agent-ts",
     "skills",

package/dist/docs/public/onboarding.md

@@ -0,0 +1,119 @@
+---
+title: "Onboarding"
+description: "An executable procedure for an AI agent to set up a new Ash agent across channels on the user's behalf."
+---
+
+# Agent Onboarding Skill
+
+This page is an **executable procedure for an AI coding agent** (for example, Claude Code) to create and wire up a new Ash agent across channels on the user's behalf, end to end. A human runs the agent; the agent runs this skill.
+
+The flow is designed to be **seamless**: the agent asks the user only for genuine decisions and for the few browser/OAuth steps that cannot be automated, and verifies every step against machine-readable output before reporting success.
+
+## When to use
+
+Use this when the user wants to create a new Ash agent — "set up an Ash agent", "scaffold an agent", "create an agent on Slack and web". If an Ash app already exists in the working directory, skip scaffolding and jump to [Adding a channel later](#adding-a-channel-later).
+
+## Prerequisites
+
+- Node `>=24` and `pnpm`.
+- For Slack or a Vercel deployment: the `vercel` CLI, logged in. Check with `vercel whoami`. If it is not installed, install it with `pnpm add -g vercel`; to log in, hand the user `vercel login` (it opens a browser).
+
+## Decisions to collect
+
+Collect these up front. A capable agent should use a structured question UI (such as AskUserQuestion) so the user picks rather than free-types:
+
+1. **Name** — the project / directory name (kebab-case). Also used as the Slack connector slug.
+2. **Model** — for example `anthropic/claude-sonnet-4.6` or `openai/gpt-5-mini`. Baked into `agent/agent.ts`.
+3. **Channels** — `web` can be scaffolded headlessly. `slack` is an interactive follow-up because Vercel Connect opens a browser OAuth flow. The local REPL is always available via `ash dev`, regardless of channel choice.
+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.
+
+## Step 1 — Scaffold (non-interactive)
+
+Run the create CLI in headless mode. It scaffolds the project, provisions the model provider, and emits a structured JSON event stream. If the user chose Slack, do **not** pass `slack` here; add it in [Step 2](#step-2--add-slack-interactively).
+
+```bash
+npx create-experimental-ash-agent@latest <name> \
+  --model <model> \
+  --channels web \
+  [--team <slug>] \
+  [--project <slug>] \
+  [--gateway-api-key <key>] \
+  [--local-only] \
+  [--no-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.
+
+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:
+
+```json
+{
+  "type": "action-required",
+  "kind": "vercel-login",
+  "command": "vercel login",
+  "reason": "Provisioning a Vercel project requires you to be logged in to Vercel."
+}
+```
+
+When you see `action-required`: present `command` to the user to run themselves, wait for them to confirm, then **re-run the exact same create command**. Repeat until the stream emits `{ "type": "done" }`.
+
+> If the installed CLI does not support `--json` / headless flags (an older version), fall back to the interactive wizard `pnpm create experimental-ash-agent` and walk the user through the same decisions above.
+
+## Step 2 — Add Slack interactively
+
+If the user chose Slack, run the supported interactive channel setup from the project directory:
+
+```bash
+cd <project-dir>
+ash channels add slack
+```
+
+That Ash command creates the Slack connector through Vercel Connect, attaches it to the Ash Slack route (`/ash/v1/slack`), and deploys the project. The underlying Vercel Connect command it runs is:
+
+```bash
+vercel connect create slack --triggers --name <name>
+```
+
+Do not try to drive Slack through headless `create-experimental-ash-agent --channels slack`. Slack setup needs an interactive browser OAuth flow and is intentionally separate from headless scaffolding.
+
+## Step 3 — Verify
+
+From the project directory:
+
+```bash
+ash build
+ash info --json          # compiled routes, channels, tools, model, status
+ash channels list --json # e.g. { "channels": ["slack", "web"] }
+```
+
+For Slack, confirm the connector is attached to this project:
+
+```bash
+vercel connect list -F json --all-projects
+```
+
+Treat setup as successful only when `ash info --json` reports `status: "ready"` and the channels array contains every channel the user selected.
+
+## Step 4 — Run and test locally
+
+- Web chat: `pnpm dev`, open `http://localhost:3000`, send a message.
+- REPL: `ash dev`, chat in the terminal.
+
+The agent replies only if it can reach a model: either `AI_GATEWAY_API_KEY` is set in `.env.local`, or the Vercel project is linked and you have run `vercel env pull --yes`.
+
+## Adding a channel later
+
+In an existing Ash project, add a channel without re-scaffolding:
+
+```bash
+ash channels add web --yes
+ash channels add slack
+```
+
+This runs the same channel setup — and, for Slack, the same connector and deploy steps — as the create flow.

package/dist/docs/public/schedules.mdx

@@ -41,7 +41,7 @@ export default defineSchedule({
     waitUntil(
       receive(slack, {
         message: "Summarize yesterday's activity and post the digest.",
-        args: { channelId: "C0123ABC" },
+        target: { channelId: "C0123ABC" },
         auth: appAuth,
       }),
     );
@@ -51,7 +51,7 @@ export default defineSchedule({
 
 `ScheduleHandlerArgs`:
 
-- `receive(channel, { message, args, auth })` — same contract as a route handler's [`args.receive`](./channels/README.md#cross-channel-hand-off). Hands the work off to a channel's authored `receive` hook.
+- `receive(channel, { message, target, auth })` — same contract as a route handler's [`args.receive`](./channels/README.md#cross-channel-hand-off). Hands the work off to a channel's authored `receive` hook.
 - `waitUntil(promise)` — extends the cron task's lifetime past handler return so in-flight work settles before the Nitro task completes.
 - `appAuth` — pre-built APP auth context (`{ authenticator: "app", principalId: "ash:app", principalType: "runtime" }`). Pass to `receive(..., { auth: appAuth })` for schedules that run on behalf of the agent itself.
 
@@ -81,7 +81,7 @@ export default defineSchedule({
     waitUntil(
       receive(slack, {
         message: "Summarize today's production deploys.",
-        args: {
+        target: {
           channelId: "C0123ABC",
           initialMessage: {
             card: Card({ children: [CardText("Daily Deploy Digest")] }),
@@ -95,7 +95,7 @@ export default defineSchedule({
 });
 ```
 
-`threadTs` and `initialMessage` are mutually exclusive on Slack receive args.
+`threadTs` and `initialMessage` are mutually exclusive on Slack receive targets.
 
 ### Markdown (`markdown`)
 

package/dist/docs/public/subagents.mdx

@@ -118,7 +118,7 @@ Subagent execution gets:
 - its own tools
 - its own sandbox (independent of the parent's sandbox)
 - its own `skills/` set (independent of the parent's skills)
-- immediate parent lineage in `ctx.session.parent`
+- 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

package/dist/src/channel/compiled-channel.d.ts

@@ -3,7 +3,7 @@ import type { RouteHandler, SendFn } from "#channel/routes.js";
 import type { Session } from "#channel/session.js";
 import type { SessionAuthContext } from "#channel/types.js";
 export declare const CHANNEL_SENTINEL: "ash:channel";
-export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+export interface CompiledChannel<TState = undefined, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
     readonly __kind: typeof CHANNEL_SENTINEL;
     readonly routes: readonly {
         method: string;
@@ -14,7 +14,7 @@ export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<strin
     readonly __metadata?: TMetadata;
     readonly receive?: (input: {
         readonly message: string;
-        readonly args: Readonly<TReceiveArgs>;
+        readonly target: Readonly<TReceiveTarget>;
         readonly auth: SessionAuthContext | null;
     }, args: {
         send: SendFn<TState>;