experimental-ash 0.16.3 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # experimental-ash
 
+## 0.18.0
+
+### Minor Changes
+
+- 7304b4d: Replace the schedule `channel: receive(slack, args)` declarative form with
+  a `run` handler that receives the same `args.receive(channel, …)` route
+  handlers got in the previous release. Schedules now author one of:
+
+  - `markdown: "..."` — fire-and-forget agent invocation (channel-less,
+    output discarded). Markdown frontmatter form (`.md`) maps here.
+  - `async run({ receive, waitUntil, appAuth }) { ... }` — full handler.
+    `receive(channel, ...)` is the same cross-channel surface route
+    handlers use; `waitUntil(promise)` extends the cron task lifetime.
+
+  Migration:
+
+  ```ts
+  // before
+  export default defineSchedule({
+    cron: "0 9 * * 1-5",
+    markdown: "Post the digest.",
+    channel: receive(slack, { channelId: "C0123ABC" }),
+  });
+
+  // after
+  export default defineSchedule({
+    cron: "0 9 * * 1-5",
+    async run({ receive, waitUntil, appAuth }) {
+      waitUntil(
+        receive(slack, {
+          message: "Post the digest.",
+          args: { channelId: "C0123ABC" },
+          auth: appAuth,
+        })
+      );
+    },
+  });
+  ```
+
+  Pure-markdown schedules (both `.md` form and `.ts` form with `markdown`)
+  are unchanged.
+
+  Removed: the `receive(channel, args)` schedule helper, the
+  `ChannelReceiveRef` type, the `ChannelRouteIdentityMap` compile-time
+  plumbing, the `ash-channel-identity` Rolldown plugin, and the
+  `channel`/`schedule.channel` manifest entry. Authored schedule
+  identity is now derived entirely at runtime from the channel value the
+  handler imports, matching how `args.receive(channel, …)` already works
+  in route handlers.
+
+## 0.17.0
+
+### Minor Changes
+
+- eaa612b: Add `args.receive(channel, …)` to route handlers for cross-channel
+  hand-off. A route handler can now start a session on a different
+  channel — e.g. an inbound HTTP webhook on one channel hands the
+  conversation off to Slack — by calling
+  `args.receive(targetChannel, { message, args, auth })`. The target
+  channel's authored `receive(input, { send })` hook owns the
+  continuation-token format and initial state; `auth` flows through to
+  `session.initiatorAuth`.
+
+  `slackChannel().receive` accepts an optional `initialPost` so callers
+  can post an anchor card before the agent runs; the agent's first turn
+  threads under that card. `threadTs` and `initialPost` are mutually
+  exclusive.
+
+  The schedule dispatcher's receive invocation now shares its
+  implementation with the route-handler path so both call sites stay
+  byte-identical.
+
+### Patch Changes
+
+- 38fd773: fix(ash): fix broken sandbox `bootstrap()` to be aligned with `onSession()` but apply snapshot-wide
+
 ## 0.16.3
 
 ### Patch Changes

package/dist/docs/internals/schedule.md

@@ -1,16 +1,18 @@
 # Schedules
 
 Schedules let an authored agent run on a cron cadence. The runtime owns the
-dispatch contract; the channel layer (when present) owns delivery.
+dispatch contract; channels (when an author hands work off to one) own
+delivery.
 
 ## Authoring shape
 
 Each schedule is a single file under `schedules/`:
 
 - `schedules/<name>.{ts,cts,mts,js,cjs,mjs}` — TypeScript module with a default
-  export of `defineSchedule({ cron, markdown, channel? })`.
+  export of `defineSchedule({ cron, markdown? | run? })`. Exactly one of
+  `markdown` (fire-and-forget) or `run` (handler) is provided.
 - `schedules/<name>.md` — markdown with frontmatter (`cron:`) and the body as
-  the prompt. The markdown form does not support a channel.
+  the prompt. Always fire-and-forget; markdown form cannot declare `run`.
 
 Recursive nesting is supported. The schedule name is derived from the relative
 path under `schedules/` minus the file extension
@@ -28,40 +30,45 @@ to the unified `discoverNamedSourceDirectory` walker with
 hydrates each `ScheduleSourceRef` into a `CompiledScheduleDefinition`:
 
 - TypeScript modules go through `loadModuleBackedDefinition` and
-  `normalizeScheduleDefinition` (rejects unknown keys).
+  `normalizeScheduleDefinition` (rejects unknown keys; enforces the
+  `markdown` / `run` exclusivity rule).
 - Markdown sources have already been lowered at discovery time; the compiler
   re-runs `normalizeScheduleDefinition` for type safety.
-- When `channel` is present, the compiler resolves the imported route to a
-  channel name through the `channelIdentityMap` built when channels were
-  loaded. Plain `{ name, args }` literals are accepted as a test-fixture
-  fallback.
-- The compiled `markdown` field is `definition.markdown.trim()`.
+- The compiled entry carries `hasRun: boolean` plus an optional `markdown`
+  string. The schedule's TypeScript module (for `hasRun` schedules) is
+  loaded at dispatch time via the standard module map; the compiler does
+  not bake the handler into the manifest.
 - The schedule name is derived from the logical path
   (`stripLogicalPathExtension(...).replace(/^schedules\//, "")`).
 
 ## Runtime
 
-`ScheduleDispatcher.trigger` (`packages/ash/src/channel/schedule.ts`) takes
-two paths:
+`ScheduleDispatcher.trigger` (`packages/ash/src/channel/schedule.ts`) builds
+`ScheduleHandlerArgs` (a subset of `RouteHandlerArgs`) against the
+request-scoped channel bundle and routes on the schedule shape:
 
-- **With a channel:** resolve the channel by name, call its `receive()` with
-  `{ message: markdown, args, auth: APP_AUTH }`. The channel handles delivery
-  through its normal code path.
-- **Without a channel:** start a session via `runtime.run({...})` directly with
-  a minimal `{ kind: "schedule" }` adapter, `auth: APP_AUTH`, `mode: "task"`,
-  and the schedule's `markdown` as the seed message. Output is discarded; the
-  agent can still call tools, log, or hit backends.
+- **Handler (`run`):** invoke `definition.run(args)`. The handler decides
+  control flow; `args.receive(channel, …)` hands the work off to a channel,
+  `args.waitUntil(promise)` keeps the Nitro task open until the promise
+  settles. `appAuth` is the framework app principal pre-built for
+  convenience.
+- **Markdown:** the dispatcher synthesizes a channel-less run by calling
+  `runtime.run({ adapter: SCHEDULE_ADAPTER, mode: "task", auth: APP_AUTH,
+input: { message: markdown } })`. Output is discarded; the agent can still
+  call tools, log, or hit backends.
 
 Both branches use the framework app principal: `principalId: "ash:app"`,
 `principalType: "runtime"`.
 
-## Why markdown form omits channel
+`SCHEDULE_ADAPTER` is registered in `FRAMEWORK_ADAPTERS`
+(`runtime/channels/registry.ts`) so the adapter registry can rehydrate
+`{ kind: "schedule" }` at every workflow step boundary.
 
-A typed `receive(channel, args)` reference depends on importing the channel
-module so the route's args type is in scope. Markdown frontmatter has no such
-import boundary — args would have to be opaque `Record<string, unknown>`,
-losing the type safety that makes `receive()` worth using. The simple,
-type-safe answer is: if you need a channel, write a `.ts` schedule.
+## Why markdown form omits `run`
+
+Markdown frontmatter has no JavaScript scope; declaring a handler requires
+TypeScript anyway. Markdown stays the path for fire-and-forget prompts;
+`.ts` schedules cover everything else.
 
 ## Nitro task wiring
 
@@ -73,7 +80,8 @@ event name plus a baked-in artifacts config.
 
 ## Tests
 
-- `src/channel/schedule.test.ts` — dispatcher behavior in both branches.
+- `src/channel/schedule.test.ts` — dispatcher behavior for both handler and
+  markdown branches plus the `waitUntil` accumulator.
 - `src/discover/agent.integration.test.ts` — discovery shapes including
   recursive nesting, markdown form, .md/.ts collision, legacy migration
   diagnostic, and unsupported leaves.
@@ -83,6 +91,9 @@ event name plus a baked-in artifacts config.
   — runtime resolution and Nitro task registration with mixed module/markdown
   schedules.
 - `test/scenarios/compile-agent.scenario.test.ts` — end-to-end compile with
-  module + markdown schedules including the no-channel form.
+  module + markdown schedules in both forms.
+- `test/scenarios/schedule-trigger.scenario.test.ts` — markdown schedule
+  end-to-end through the real dispatcher, including the SCHEDULE_ADAPTER
+  step-boundary rehydration.
 - `test/scenarios/runtime-loaders.scenario.test.ts` — runtime artifact
   loaders round-trip.

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

@@ -253,6 +253,77 @@ resolver when the allowed phone numbers come from dynamic state. Use `allowFrom:
 
 See [Twilio channel setup](./twilio.md) for webhook URLs, environment variables, and overrides.
 
+## Cross-Channel Hand-off
+
+Route handlers can start a session on a different channel via `args.receive(channel, ...)`.
+Use this when an inbound request on one channel should pivot the conversation onto another
+-- for example, an incident webhook hits an HTTP route and the operator interacts in Slack.
+
+```ts
+import { defineChannel, POST } from "experimental-ash/channels";
+import slack from "./slack.js";
+
+export default defineChannel({
+  routes: [
+    POST("/incident", async (req, args) => {
+      const incident = await req.json();
+      args.waitUntil(
+        args.receive(slack, {
+          message: `Investigate ${incident.reference}: ${incident.title}`,
+          args: { channelId: "C0123ABC" },
+          auth: {
+            authenticator: "incidentio",
+            principalType: "service",
+            principalId: incident.actor.id,
+            attributes: { reference: incident.reference, severity: incident.severity },
+          },
+        }),
+      );
+      return new Response("ok");
+    }),
+  ],
+});
+```
+
+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 }`.
+- `auth` flows through to `session.initiatorAuth` 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
+  inbound channel's response is whatever the route handler returns explicitly (e.g.
+  `200 OK` to acknowledge the webhook).
+- The first argument is the target channel module's default export -- import it directly
+  from `agent/channels/<name>.ts`. Identity is matched by reference.
+
+Slack's `receive` accepts an optional `initialPost` so the target channel can post a card
+before the agent runs; subsequent agent turns thread under that card.
+
+```ts
+import { Card, CardText } from "experimental-ash/channels/slack";
+
+await args.receive(slack, {
+  message: "Begin investigation",
+  args: {
+    channelId: "C0123ABC",
+    initialPost: {
+      card: Card({ children: [CardText("Investigation Thread for INC-42")] }),
+      fallbackText: "Investigation Thread for INC-42",
+    },
+  },
+  auth,
+});
+```
+
+`threadTs` and `initialPost` are mutually exclusive: pass `threadTs` to join an existing
+thread, or `initialPost` to anchor a new one.
+
+The card's `ts` becomes the session's continuation token, so any later `@mention` reply
+inside that thread resumes the same session instead of starting a new one. Without
+`initialPost`, programmatically-started Slack sessions have no thread to anchor under and
+follow-up mentions land in a fresh session.
+
 ## File Uploads
 
 `send()` accepts `string | UserContent`. To include file attachments,

package/dist/docs/public/schedules.md

@@ -1,9 +1,9 @@
 ---
 title: "Schedules"
-description: "Define recurring cron jobs that run an agent and optionally deliver the result through a channel."
+description: "Define recurring cron jobs that run an agent and optionally hand off to a channel."
 ---
 
-Schedules let an agent initiate recurring work — digests, syncs, maintenance, heartbeat checks — on a cron cadence. The agent can either deliver its output through a channel (e.g. Slack) or run fire-and-forget while calling tools, hitting backends, or writing logs.
+Schedules let an agent initiate recurring work — digests, syncs, maintenance, heartbeat checks — on a cron cadence. Each schedule is either a fire-and-forget markdown prompt or a TypeScript handler that decides what to do (typically by handing the work off to a channel).
 
 Schedules live under `schedules/` at the root agent package.
 
@@ -11,27 +11,77 @@ Schedules live under `schedules/` at the root agent package.
 
 - schedules are root-only — local subagents cannot declare `schedules/`
 - a schedule is a single file: `<name>.ts` or `<name>.md`
-- the markdown form does not support targeting a channel — use the `.ts` form for that
-- the channel argument is **optional**
+- every schedule provides exactly one of `markdown` (fire-and-forget) or `run` (handler)
+- markdown-form (`.md`) schedules cannot declare a handler — use `.ts` for that
 
 ## Authoring shapes
 
-### TypeScript
+### TypeScript handler (`run`)
+
+Use a handler when the schedule should deliver to a channel, branch on conditions, or compute args at fire time. The handler receives a tight subset of `RouteHandlerArgs`:
 
 ```ts
 // agent/schedules/daily-digest.ts
-import { defineSchedule, receive } from "experimental-ash/schedules";
+import { defineSchedule } from "experimental-ash/schedules";
 
 import slack from "../channels/slack.js";
 
 export default defineSchedule({
   cron: "0 9 * * 1-5",
-  markdown: "Summarize yesterday's activity and post the digest.",
-  channel: receive(slack, { channelId: "C0123ABC" }),
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(slack, {
+        message: "Summarize yesterday's activity and post the digest.",
+        args: { channelId: "C0123ABC" },
+        auth: appAuth,
+      }),
+    );
+  },
+});
+```
+
+`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.
+- `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.
+
+#### Announce-then-deliver
+
+A handler that hands off to Slack can post an anchor card before the agent runs so the thread shows "what this is about" up front; the agent's reply then lands threaded under that card. Same `initialPost` field [Slack's `receive`](./channels/README.md#cross-channel-hand-off) accepts from a route handler:
+
+```ts
+// agent/schedules/deploy-digest.ts
+import { defineSchedule } from "experimental-ash/schedules";
+import { Card, CardText } from "experimental-ash/channels/slack";
+
+import slack from "../channels/slack.js";
+
+export default defineSchedule({
+  cron: "0 17 * * 1-5",
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(slack, {
+        message: "Summarize today's production deploys.",
+        args: {
+          channelId: "C0123ABC",
+          initialPost: {
+            card: Card({ children: [CardText("Daily Deploy Digest")] }),
+            fallbackText: "Daily Deploy Digest",
+          },
+        },
+        auth: appAuth,
+      }),
+    );
+  },
 });
 ```
 
-Without a channel — the agent runs and the output is discarded:
+`threadTs` and `initialPost` are mutually exclusive on Slack receive args. The anchor card's `ts` becomes the session's continuation token, so any later `@mention` reply in that thread resumes the same session — a digest that sparks a question can be answered in-thread without spinning up a new session.
+
+### Markdown (`markdown`)
+
+Fire-and-forget: the agent runs the prompt and the output is discarded. The agent is still free to call tools, write to backends, log, etc.
 
 ```ts
 // agent/schedules/heartbeat.ts
@@ -43,7 +93,7 @@ export default defineSchedule({
 });
 ```
 
-### Markdown
+Markdown frontmatter form:
 
 ```md
 ## <!-- agent/schedules/cleanup.md -->
@@ -53,7 +103,7 @@ export default defineSchedule({
 Sweep stale workflow state.
 ```
 
-The body is the prompt. The frontmatter accepts `cron` only — markdown-form schedules cannot reference a channel.
+The body is the prompt. The frontmatter accepts `cron` only.
 
 ## Recursive nesting
 
@@ -73,62 +123,40 @@ agent/schedules/
 ```ts
 interface ScheduleDefinition {
   cron: string;
-  markdown: string;
-  channel?: ChannelReceiveRef<unknown>;
+  markdown?: string;
+  run?: (args: ScheduleHandlerArgs) => Promise<void> | void;
 }
-```
-
-- `cron` (required) — a cron expression for when the schedule fires
-- `markdown` (required) — the prompt the agent receives when the schedule runs
-- `channel` (optional) — a typed channel reference produced by `receive(channel, args)`
-
-The `markdown` field is the prompt body — the same convention used by `defineInstructions({ markdown })` and `defineSkill({ markdown })`.
-
-## Channel targeting
-
-When a schedule should deliver its output through a channel, use the `receive(channel, args)` helper from `experimental-ash/schedules`:
-
-```ts
-import { receive } from "experimental-ash/schedules";
-import slack from "../channels/slack.js";
 
-receive(slack, { channelId: "C0123ABC" });
+interface ScheduleHandlerArgs {
+  receive: CrossChannelReceiveFn;
+  waitUntil: (task: Promise<unknown>) => void;
+  appAuth: SessionAuthContext;
+}
 ```
 
-The `args` object's shape is inferred from the channel's typed receive route — Slack requires `channelId`; other channels define their own args shape. At compile time, Ash validates that the channel reference resolves to an authored channel under `agent/channels/` whose route implements a `receive()` method.
+Exactly one of `markdown` or `run` must be provided. `defineSchedule` is a pass-through that exists to attach TypeScript types — it does not validate at authoring time; the compiler enforces the exclusivity rule.
 
 ## Runtime behavior
 
 When a schedule fires, the dispatcher takes one of two paths:
 
-### With a channel
+### Handler form (`run`)
 
-1. The dispatcher resolves the channel route by name.
-2. It calls `route.receive()` with the schedule's `markdown` and the channel-specific `args`.
-3. The channel builds its adapter, starts a session, and handles output delivery the same way it handles webhook-initiated messages.
+1. The dispatcher loads the schedule's compiled module and reads `definition.run`.
+2. It builds `ScheduleHandlerArgs` against the request-scoped channel bundle and invokes `run(args)`.
+3. The handler decides everything: which channels to target, what auth to use, whether to short-circuit on holidays, etc.
+4. Any promises the handler passes to `waitUntil` are awaited before the Nitro task settles.
 
-### Without a channel
+### Markdown form
 
-1. The dispatcher starts a session through the runtime directly with a minimal scheduled-task adapter.
+1. The dispatcher starts a session through the runtime directly with the framework-owned `SCHEDULE_ADAPTER`.
 2. The agent runs in **task mode** with the app principal.
-3. Output is discarded — but the agent is still free to call tools, write to backends, log, etc.
+3. Output is discarded.
 
 In both cases, the schedule session uses the **app principal**: `getSession().auth.current` and `getSession().auth.initiator` are set to `"ash:app"` with `principalType: "runtime"`.
 
 The session goes through the same durable runtime engine as any other Ash session.
 
-## Migrating from the legacy directory form
-
-The directory form (`schedules/<name>/schedule.ts` + `schedules/<name>/prompt.md`) is no longer supported. To migrate, collapse each directory into a single file:
-
-```text
-agent/schedules/daily-digest/schedule.ts   →   agent/schedules/daily-digest.ts
-agent/schedules/daily-digest/prompt.md     →   inlined as `markdown:` on
-                                                the `defineSchedule({...})` call
-```
-
-Discovery emits a clear migration diagnostic when it sees a legacy directory layout.
-
 ## When to use a schedule
 
 Use a schedule when the agent should initiate work on its own cadence:

package/dist/src/channel/cross-channel-receive.d.ts

@@ -0,0 +1,61 @@
+import type { UserContent } from "ai";
+import type { ChannelAdapter } from "#channel/adapter.js";
+import type { CompiledChannel } from "#channel/compiled-channel.js";
+import type { InferReceiveArgs } from "#channel/receive-args.js";
+import type { Session } from "#channel/session.js";
+import type { Runtime, SessionAuthContext } from "#channel/types.js";
+/**
+ * Options accepted by {@link CrossChannelReceiveFn}. Mirrors the input
+ * argument of a channel's authored `receive(input, { send })` hook —
+ * the runtime constructs `send` internally so route-handler callers
+ * only supply the platform args, payload, and auth.
+ */
+export interface CrossChannelReceiveOptions<TArgs = Record<string, unknown>> {
+    readonly message: string | UserContent;
+    readonly args: TArgs;
+    readonly auth: SessionAuthContext | null;
+}
+/**
+ * Starts a session on a different channel from inside a route handler.
+ * The target channel's authored `receive` hook owns continuation-token
+ * format and initial state; `auth` is forwarded verbatim and becomes
+ * `session.initiatorAuth`.
+ */
+export type CrossChannelReceiveFn = <TChannel>(channel: TChannel, options: CrossChannelReceiveOptions<InferReceiveArgs<TChannel>>) => Promise<Session>;
+/**
+ * Channel record consumed by the receiver — keeps the public-facing
+ * `definition` reference so callers can identify a target by value
+ * (the same module-default they imported in their route file).
+ */
+export interface CrossChannelTarget {
+    readonly name: string;
+    readonly definition?: CompiledChannel;
+    readonly receive?: CompiledChannel["receive"];
+    readonly adapter?: ChannelAdapter;
+}
+/**
+ * Builds the `args.receive` closure used by every route handler. The
+ * closure resolves the target channel by reference identity against
+ * the request-scoped channel bundle, then delegates to the target's
+ * authored `receive` hook with a per-target `send` factory.
+ */
+export declare function createCrossChannelReceiveFn(runtime: Runtime, channels: readonly CrossChannelTarget[]): CrossChannelReceiveFn;
+interface InvokeChannelReceiveInput {
+    readonly runtime: Runtime;
+    readonly target: Pick<CrossChannelTarget, "name" | "receive" | "adapter">;
+    readonly input: {
+        readonly message: string;
+        readonly args: Readonly<Record<string, unknown>>;
+        readonly auth: SessionAuthContext | null;
+    };
+    readonly describeMissingReceive: () => string;
+    readonly describeMissingAdapter: () => string;
+}
+/**
+ * Shared `receive(input, { send })` invocation used by both the route-
+ * handler cross-channel surface and the schedule dispatcher. Owns the
+ * receive/adapter precondition checks and the per-target `send`
+ * factory so both call sites stay byte-identical.
+ */
+export declare function invokeChannelReceive(args: InvokeChannelReceiveInput): Promise<Session>;
+export {};

package/dist/src/channel/cross-channel-receive.js

@@ -0,0 +1,50 @@
+import { createSendFn } from "#channel/send.js";
+/**
+ * Builds the `args.receive` closure used by every route handler. The
+ * closure resolves the target channel by reference identity against
+ * the request-scoped channel bundle, then delegates to the target's
+ * authored `receive` hook with a per-target `send` factory.
+ */
+export function createCrossChannelReceiveFn(runtime, channels) {
+    return async (channel, options) => {
+        const target = resolveTargetByReference(channel, channels);
+        return await invokeChannelReceive({
+            runtime,
+            target,
+            input: {
+                message: options.message,
+                args: (options.args ?? {}),
+                auth: options.auth,
+            },
+            describeMissingReceive: () => `args.receive(): channel "${target.name}" does not implement receive(). ` +
+                `Declare a receive hook on the channel to accept cross-channel sessions.`,
+            describeMissingAdapter: () => `args.receive(): channel "${target.name}" has no adapter — cannot build send().`,
+        });
+    };
+}
+/**
+ * Shared `receive(input, { send })` invocation used by both the route-
+ * handler cross-channel surface and the schedule dispatcher. Owns the
+ * receive/adapter precondition checks and the per-target `send`
+ * factory so both call sites stay byte-identical.
+ */
+export async function invokeChannelReceive(args) {
+    if (!args.target.receive) {
+        throw new Error(args.describeMissingReceive());
+    }
+    if (!args.target.adapter) {
+        throw new Error(args.describeMissingAdapter());
+    }
+    const send = createSendFn(args.runtime, args.target.adapter, args.target.name);
+    return await args.target.receive(args.input, { send });
+}
+function resolveTargetByReference(ref, channels) {
+    for (const channel of channels) {
+        if (channel.definition !== undefined && channel.definition === ref) {
+            return channel;
+        }
+    }
+    throw new Error("args.receive(): the channel passed as the first argument is not registered " +
+        "in this agent's channels/. Import the channel module's default export from " +
+        "agent/channels/<name>.ts and pass that value.");
+}

package/dist/src/channel/receive-args.d.ts

@@ -0,0 +1,17 @@
+declare const receiveArgsMarker: unique symbol;
+/**
+ * Structural marker attached by channel factories (e.g. `slackChannel`,
+ * `twilioChannel`) to advertise the args type their `receive()` accepts.
+ * `receive(channel, args)` helpers and the route-handler
+ * `args.receive(channel, ...)` use this marker to infer typed args
+ * from a plain channel import.
+ */
+export interface TypedReceiveRoute<TArgs = Record<string, unknown>> {
+    readonly [receiveArgsMarker]?: TArgs;
+}
+/**
+ * Extracts the receive-args type from a channel value, falling back to
+ * `Record<string, unknown>` when the channel does not advertise one.
+ */
+export type InferReceiveArgs<TChannel> = TChannel extends TypedReceiveRoute<infer TArgs> ? TArgs : Record<string, unknown>;
+export {};

package/dist/src/channel/receive-args.js

@@ -0,0 +1 @@
+export {};

package/dist/src/channel/routes.d.ts

@@ -1,10 +1,19 @@
 import type { UserContent } from "ai";
+import type { CrossChannelReceiveFn } from "#channel/cross-channel-receive.js";
 import type { SessionAuthContext } from "#channel/types.js";
 import type { InputResponse } from "#runtime/input/types.js";
 import type { Session } from "#channel/session.js";
 export interface RouteHandlerArgs<TState = undefined> {
     send: SendFn<TState>;
     getSession: GetSessionFn;
+    /**
+     * Starts a session on a different channel. Use to hand off inbound
+     * work — e.g. an HTTP webhook receives a notification and pivots the
+     * conversation onto Slack. The target's authored `receive` hook owns
+     * continuation-token format and initial state; the caller supplies
+     * the payload, channel-specific args, and auth.
+     */
+    receive: CrossChannelReceiveFn;
     params: Readonly<Record<string, string>>;
     waitUntil: (task: Promise<unknown>) => void;
     requestIp: string | null;