experimental-ash 0.16.3 → 0.18.0

package/dist/src/internal/nitro/routes/schedule-task.js

@@ -1,27 +1,57 @@
+import { expectScheduleRun, ScheduleDispatcher } from "#channel/schedule.js";
+import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
+import { loadResolvedModuleExport } from "#runtime/resolve-helpers.js";
 import { loadResolvedCompiledScheduleByTaskName } from "#runtime/schedules/resolve-schedule.js";
+import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
 import { resolveNitroCompiledArtifactsSource } from "#internal/nitro/routes/runtime-artifacts.js";
-import { resolveNitroScheduleDispatcher } from "#internal/nitro/routes/runtime-stack.js";
 /**
  * Dispatches one Ash authored schedule via the execution engine.
  *
  * Fire-and-forget: the workflow runtime owns terminal completion and
- * its own failure observability. The task return value reports only
- * that the session was dispatched.
+ * its own failure observability. The task return value reports which
+ * session ids the handler started so Nitro / dev tools can correlate.
  */
 export async function dispatchScheduleTask(taskName, config) {
     const compiledArtifactsSource = resolveNitroCompiledArtifactsSource(config);
     const schedule = await loadResolvedCompiledScheduleByTaskName(taskName, {
         compiledArtifactsSource,
     });
-    const dispatcher = resolveNitroScheduleDispatcher(config);
-    const triggerInput = {
-        channel: schedule.channel,
-        markdown: schedule.markdown,
-        scheduleId: schedule.name,
-    };
-    const session = await dispatcher.trigger(triggerInput);
+    const bundle = await getCompiledRuntimeAgentBundle({ compiledArtifactsSource });
+    const runtime = createWorkflowRuntime({ compiledArtifactsSource });
+    const dispatcher = new ScheduleDispatcher({
+        runtime,
+        channels: bundle.graph.root.channels,
+    });
+    const dispatchInput = { scheduleId: schedule.name };
+    if (schedule.hasRun) {
+        dispatchInput.run = await loadScheduleRun(schedule, bundle.moduleMap);
+    }
+    if (schedule.markdown !== undefined) {
+        dispatchInput.markdown = schedule.markdown;
+    }
+    const result = await dispatcher.trigger(dispatchInput);
+    if (result.waitUntilTasks.length > 0) {
+        await Promise.allSettled(result.waitUntilTasks);
+    }
     return {
         scheduleId: schedule.name,
-        sessionId: session.id,
+        sessionIds: result.sessions.map((session) => session.id),
     };
 }
+async function loadScheduleRun(schedule, moduleMap) {
+    if (schedule.sourceKind !== "module") {
+        throw new Error(`Schedule "${schedule.name}" claims hasRun but is not a module-backed schedule.`);
+    }
+    const moduleSchedule = schedule;
+    const exportValue = await loadResolvedModuleExport({
+        definition: {
+            exportName: moduleSchedule.exportName,
+            logicalPath: moduleSchedule.logicalPath,
+            sourceId: moduleSchedule.sourceId,
+        },
+        kindLabel: "schedule",
+        moduleMap,
+        nodeId: undefined,
+    });
+    return expectScheduleRun(exportValue, moduleSchedule.logicalPath, moduleSchedule.exportName);
+}

package/dist/src/public/channels/slack/index.d.ts

@@ -1,4 +1,4 @@
-export { slackChannel, type SlackApiResponse, type SlackBotToken, type SlackChannel, type SlackChannelConfig, type SlackChannelCredentials, type SlackChannelEvents, type SlackChannelState, type SlackContext, type SlackEventContext, type SlackHandle, type SlackInboundResult, type SlackInboundResultOrPromise, type SlackInteractionAction, type SlackMentionResult, type SlackMentionResultOrPromise, type SlackReceiveArgs, type SlackThread, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
+export { slackChannel, type SlackApiResponse, type SlackBotToken, type SlackChannel, type SlackChannelConfig, type SlackChannelCredentials, type SlackChannelEvents, type SlackChannelState, type SlackContext, type SlackEventContext, type SlackHandle, type SlackInboundResult, type SlackInboundResultOrPromise, type SlackInitialPost, type SlackInteractionAction, type SlackMentionResult, type SlackMentionResultOrPromise, type SlackReceiveArgs, type SlackThread, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
 export type { SlackAttachment, SlackAuthor, SlackInboundContext, SlackMessage, } from "#public/channels/slack/inbound.js";
 export type { SlackPostInput, SlackPostedMessage, SlackThreadMessage, SlackUploadFilesOptions, SlackUploadFilesResult, } from "#public/channels/slack/api.js";
 export { cardToBlocks, cardToFallbackText, type BlockKitBlock, } from "#public/channels/slack/blocks.js";

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -1,4 +1,6 @@
+import type { TypedReceiveRoute } from "#channel/receive-args.js";
 import type { SessionAuthContext } from "#channel/types.js";
+import type { CardElement } from "#compiled/chat/index.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import { type SlackBotToken, type SlackHandle, type SlackThread } from "#public/channels/slack/api.js";
 import { type SlackMessage } from "#public/channels/slack/inbound.js";
@@ -94,6 +96,23 @@ export interface SlackChannelCredentials {
 export interface SlackReceiveArgs {
     readonly channelId: string;
     readonly threadTs?: string;
+    /**
+     * Optional message posted into the Slack channel before the agent
+     * runs. The post becomes the thread root and the agent's first turn
+     * lands threaded under it. Useful for cross-channel handoffs where
+     * the caller wants a visible "this is why we're here" anchor before
+     * the model speaks. Mutually exclusive with {@link threadTs}.
+     */
+    readonly initialPost?: SlackInitialPost;
+}
+/**
+ * Pre-agent post issued by `slackChannel().receive` when the caller
+ * provides `args.initialPost`. The shape mirrors `ctx.thread.post`'s
+ * card variant so the same `Card({...})` construction can be reused.
+ */
+export interface SlackInitialPost {
+    readonly card: CardElement;
+    readonly fallbackText?: string;
 }
 export interface SlackInteractionAction {
     readonly actionId: string;
@@ -260,7 +279,7 @@ export interface SlackChannelConfig {
  * default-export a `slackChannel(...)` call under `declaration: true`
  * without TypeScript falling back to an internal path for `Channel`.
  */
-export interface SlackChannel extends Channel<SlackChannelState> {
+export interface SlackChannel extends Channel<SlackChannelState>, TypedReceiveRoute<SlackReceiveArgs> {
 }
 /**
  * Slack channel factory. Wires up the Slack webhook route, mention

package/dist/src/public/channels/slack/slackChannel.js

@@ -72,11 +72,33 @@ export function slackChannel(config = {}) {
             }),
         ],
         async receive(input, { send }) {
-            const channelId = input.args.channelId;
-            if (!channelId) {
+            const receiveArgs = input.args;
+            const channelId = receiveArgs.channelId;
+            if (!channelId || typeof channelId !== "string") {
                 throw new Error("slackChannel().receive requires args.channelId.");
             }
-            const threadTs = typeof input.args.threadTs === "string" ? input.args.threadTs : "";
+            const requestedThreadTs = typeof receiveArgs.threadTs === "string" ? receiveArgs.threadTs : "";
+            const initialPost = receiveArgs.initialPost;
+            if (initialPost && requestedThreadTs.length > 0) {
+                throw new Error("slackChannel().receive: `threadTs` and `initialPost` are mutually exclusive.");
+            }
+            let threadTs = requestedThreadTs;
+            if (initialPost) {
+                const { thread } = buildSlackBinding({
+                    botToken: config.credentials?.botToken,
+                    channelId,
+                    threadTs: "",
+                    teamId: undefined,
+                });
+                const postInput = {
+                    card: initialPost.card,
+                };
+                if (initialPost.fallbackText !== undefined) {
+                    postInput.fallbackText = initialPost.fallbackText;
+                }
+                const posted = await thread.post(postInput);
+                threadTs = posted.id;
+            }
             return send(input.message, {
                 auth: input.auth,
                 continuationToken: encodeSlackContinuationToken(channelId, threadTs),

package/dist/src/public/channels/twilio/twilioChannel.d.ts

@@ -1,3 +1,4 @@
+import type { TypedReceiveRoute } from "#channel/receive-args.js";
 import type { SessionAuthContext } from "#channel/types.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import { type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials } from "#public/channels/twilio/api.js";
@@ -172,7 +173,7 @@ export interface TwilioSendMessageOptions {
     readonly statusCallbackUrl?: string;
 }
 /** Concrete return type of {@link twilioChannel}. */
-export interface TwilioChannel extends Channel<TwilioChannelState> {
+export interface TwilioChannel extends Channel<TwilioChannelState>, TypedReceiveRoute<TwilioReceiveArgs> {
 }
 /** Twilio channel factory for SMS and speech-transcribed inbound calls. */
 export declare function twilioChannel(config: TwilioChannelConfig): TwilioChannel;

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

@@ -2,9 +2,9 @@ import type { Optional } from "#shared/optional.js";
 import type { SandboxSession } from "#shared/sandbox-session.js";
 import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
 export type { SandboxCommandOptions, SandboxCommandResult, SandboxReadTextFileOptions, SandboxSession, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
-export type { SandboxBootstrapUseOptions, SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
-export type SandboxDefinition<S extends SandboxSession = SandboxSession, O = Record<string, never>> = Optional<SharedSandboxDefinition<S, O>, "backend">;
+export type { SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
+export type SandboxDefinition<S extends SandboxSession = SandboxSession, BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinition<S, BO, SO>, "backend">;
 /**
  * Defines a sandbox configuration.
  */
-export declare function defineSandbox<S extends SandboxSession = SandboxSession, O = Record<string, never>>(definition: SandboxDefinition<S, O>): SandboxDefinition<S, O>;
+export declare function defineSandbox<S extends SandboxSession = SandboxSession, BO = Record<string, never>, SO = Record<string, never>>(definition: SandboxDefinition<S, BO, SO>): SandboxDefinition<S, BO, SO>;

package/dist/src/public/definitions/schedule.d.ts

@@ -1,77 +1,75 @@
-declare const receiveArgsMarker: unique symbol;
+import type { CrossChannelReceiveFn } from "#channel/cross-channel-receive.js";
+import type { SessionAuthContext } from "#channel/types.js";
+export type { InferReceiveArgs, TypedReceiveRoute } from "#channel/receive-args.js";
 /**
- * A route that declares its receive args type. Channel route factories
- * return this so {@link receive} can infer the
- * correct args type from the channel import.
- *
- * Accepts both old Route-style and new CompiledChannel values.
+ * Arguments handed to {@link ScheduleDefinition.run}. Tight subset of
+ * `RouteHandlerArgs` — schedules can hand work off to a channel via
+ * {@link receive} and extend the task lifetime via {@link waitUntil}.
+ * No `send` because schedules have no current channel.
  */
-export interface TypedReceiveRoute<TArgs = Record<string, unknown>> {
-    readonly [receiveArgsMarker]?: TArgs;
+export interface ScheduleHandlerArgs {
+    /**
+     * Starts a session on another channel — same contract as a route
+     * handler's `args.receive(channel, ...)`.
+     */
+    readonly receive: CrossChannelReceiveFn;
+    /**
+     * Extends the cron task's lifetime past handler return so background
+     * work (the parked workflow session, in-flight fetches, etc.) is
+     * awaited before the Nitro task settles.
+     */
+    readonly waitUntil: (task: Promise<unknown>) => void;
+    /**
+     * Pre-built APP auth context. Pass this to `receive(channel, { auth })`
+     * for schedules that run on behalf of the agent itself.
+     */
+    readonly appAuth: SessionAuthContext;
 }
 /**
- * Extracts the receive args type from a channel value.
- */
-type InferReceiveArgs<TChannel> = TChannel extends TypedReceiveRoute<infer TArgs> ? TArgs : Record<string, unknown>;
-/**
- * A channel reference with typed args, produced by {@link receive}.
- * Carries the route/channel object for identity resolution at compile time
- * and the args for the compiled manifest.
+ * Handler invoked when the cron fires.
  */
-export interface ChannelReceiveRef<TArgs = Record<string, unknown>> {
-    readonly __route: any;
-    readonly args: TArgs;
-}
+export type ScheduleRunHandler = (args: ScheduleHandlerArgs) => Promise<void> | void;
 /**
- * Creates a typed channel reference for a schedule. Import the channel
- * module and pass it with the args — TypeScript infers the correct
- * args type from the channel's route type.
- *
- * Accepts both old Route-style channels and new CompiledChannel values.
+ * Public definition for a schedule authored in TypeScript.
  *
- * @example
- * ```ts
- * import slack from "../../channels/slack.js";
+ * Provide exactly one of `markdown` or `run`:
  *
- * export default defineSchedule({
- *   cron: "0 9 * * 1-5",
- *   channel: receive(slack, { channelId: "C0123ABC" }),
- * });
- * ```
- */
-export declare function receive<TChannel extends TypedReceiveRoute<any> | {
-    readonly __kind: any;
-}>(channel: TChannel, args: InferReceiveArgs<TChannel>): ChannelReceiveRef<InferReceiveArgs<TChannel>>;
-/**
- * Public definition for a schedule authored in TypeScript.
+ * - `markdown` — fire-and-forget agent invocation. The framework runs
+ *   the agent on the prompt and discards the output. Equivalent to the
+ *   markdown form (`<name>.md`).
+ * - `run` — full handler. Receives `{ receive, waitUntil, appAuth }`
+ *   and decides what to do.
  *
  * Identity is derived from the file path under `agent/schedules/`;
- * authored definitions do not carry a `name` field. The optional
- * `channel` delivers the agent's output to a typed channel target;
- * when omitted, the agent runs and the output is discarded (the
- * agent is still free to call tools, log, or hit backends).
+ * authored definitions do not carry a `name` field.
  */
 export interface ScheduleDefinition {
-    cron: string;
-    markdown: string;
-    channel?: ChannelReceiveRef<any>;
+    readonly cron: string;
+    readonly markdown?: string;
+    readonly run?: ScheduleRunHandler;
 }
 /**
  * Defines a schedule in TypeScript. Export as the default from
  * `agent/schedules/<name>.ts`.
  *
- * @example
+ * @example Hand off to Slack:
  * ```ts
+ * import { defineSchedule } from "experimental-ash/schedules";
  * import slack from "../channels/slack.js";
  *
  * export default defineSchedule({
  *   cron: "0 9 * * 1-5",
- *   markdown: "Post the daily standup summary.",
- *   channel: receive(slack, { channelId: "C0123ABC" }),
+ *   async run({ receive, waitUntil, appAuth }) {
+ *     waitUntil(receive(slack, {
+ *       message: "Post the daily standup summary.",
+ *       args: { channelId: "C0123ABC" },
+ *       auth: appAuth,
+ *     }));
+ *   },
  * });
  * ```
  *
- * @example Without a channel — fire-and-forget:
+ * @example Fire-and-forget:
  * ```ts
  * export default defineSchedule({
  *   cron: "* / 5 * * * *",
@@ -80,4 +78,3 @@ export interface ScheduleDefinition {
  * ```
  */
 export declare function defineSchedule<TSchedule extends ScheduleDefinition>(definition: TSchedule): TSchedule;
-export {};

package/dist/src/public/definitions/schedule.js

@@ -1,40 +1,25 @@
-/**
- * Creates a typed channel reference for a schedule. Import the channel
- * module and pass it with the args — TypeScript infers the correct
- * args type from the channel's route type.
- *
- * Accepts both old Route-style channels and new CompiledChannel values.
- *
- * @example
- * ```ts
- * import slack from "../../channels/slack.js";
- *
- * export default defineSchedule({
- *   cron: "0 9 * * 1-5",
- *   channel: receive(slack, { channelId: "C0123ABC" }),
- * });
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function receive(channel, args) {
-    return { __route: channel, args };
-}
 /**
  * Defines a schedule in TypeScript. Export as the default from
  * `agent/schedules/<name>.ts`.
  *
- * @example
+ * @example Hand off to Slack:
  * ```ts
+ * import { defineSchedule } from "experimental-ash/schedules";
  * import slack from "../channels/slack.js";
  *
  * export default defineSchedule({
  *   cron: "0 9 * * 1-5",
- *   markdown: "Post the daily standup summary.",
- *   channel: receive(slack, { channelId: "C0123ABC" }),
+ *   async run({ receive, waitUntil, appAuth }) {
+ *     waitUntil(receive(slack, {
+ *       message: "Post the daily standup summary.",
+ *       args: { channelId: "C0123ABC" },
+ *       auth: appAuth,
+ *     }));
+ *   },
  * });
  * ```
  *
- * @example Without a channel — fire-and-forget:
+ * @example Fire-and-forget:
  * ```ts
  * export default defineSchedule({
  *   cron: "* / 5 * * * *",

package/dist/src/public/helpers/markdown.d.ts

@@ -55,12 +55,12 @@ export interface LowerSkillMarkdownInput {
  */
 /**
  * Lowers an authored schedule markdown file into the shared public
- * definition shape. The frontmatter must contain `cron`; no other keys
- * are accepted (markdown-form schedules cannot reference a channel —
- * use the `.ts` form for that). The body becomes the schedule's
- * `markdown` (the prompt delivered when the schedule fires). Schedule
- * identity is path-derived, so the lowered definition never carries a
- * `name`.
+ * definition shape. The frontmatter must contain `cron`. The body
+ * becomes the schedule's `markdown` (the fire-and-forget prompt the
+ * agent runs when the cron fires). Markdown-form schedules cannot
+ * declare a `run` handler — use the `.ts` form for handler-based
+ * schedules. Schedule identity is path-derived, so the lowered
+ * definition never carries a `name`.
  */
 export declare function lowerScheduleMarkdown(source: string): ScheduleDefinition;
 export declare function lowerSkillMarkdown(source: string, input?: LowerSkillMarkdownInput): SkillDefinition;

package/dist/src/public/helpers/markdown.js

@@ -56,20 +56,20 @@ export function lowerInstructionsMarkdown(markdown) {
  */
 /**
  * Lowers an authored schedule markdown file into the shared public
- * definition shape. The frontmatter must contain `cron`; no other keys
- * are accepted (markdown-form schedules cannot reference a channel —
- * use the `.ts` form for that). The body becomes the schedule's
- * `markdown` (the prompt delivered when the schedule fires). Schedule
- * identity is path-derived, so the lowered definition never carries a
- * `name`.
+ * definition shape. The frontmatter must contain `cron`. The body
+ * becomes the schedule's `markdown` (the fire-and-forget prompt the
+ * agent runs when the cron fires). Markdown-form schedules cannot
+ * declare a `run` handler — use the `.ts` form for handler-based
+ * schedules. Schedule identity is path-derived, so the lowered
+ * definition never carries a `name`.
  */
 export function lowerScheduleMarkdown(source) {
     const document = parseMarkdownDocument(source);
     if (!document.hasFrontmatter) {
         throw new Error('Schedule markdown must start with YAML frontmatter declaring "cron".');
     }
-    if ("channel" in document.frontmatter) {
-        throw new Error('Markdown-form schedules do not support the "channel" frontmatter key. Use a TypeScript schedule (`<name>.ts`) to deliver to a channel.');
+    if ("run" in document.frontmatter) {
+        throw new Error('Markdown-form schedules do not support the "run" frontmatter key. Use a TypeScript schedule (`<name>.ts`) to author a handler.');
     }
     const rawDefinition = {
         ...document.frontmatter,

package/dist/src/public/sandbox/backends/vercel.d.ts

@@ -1,11 +1,11 @@
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
-import type { VercelSandbox, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+import type { VercelSandbox, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
- * Creation-time config (runtime, ports, env) lives in `bootstrap`'s
- * `create()` call; session-level config (networkPolicy, resources,
- * timeout) lives in `onSession`'s `create()` call or
+ * `bootstrap({ use })` applies its options to the template via
+ * `sandbox.update(...)`; those settings persist into the snapshot.
+ * `onSession({ use })` applies its options to the live session via
  * `VercelSandbox.update()`.
  */
-export declare function vercelBackend(): SandboxBackend<VercelSandbox, VercelSandboxSessionUseOptions>;
+export declare function vercelBackend(): SandboxBackend<VercelSandbox, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;

package/dist/src/public/sandbox/backends/vercel.js

@@ -2,9 +2,9 @@ import { createVercelSandboxBackend } from "#execution/sandbox/bindings/vercel.j
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
- * Creation-time config (runtime, ports, env) lives in `bootstrap`'s
- * `create()` call; session-level config (networkPolicy, resources,
- * timeout) lives in `onSession`'s `create()` call or
+ * `bootstrap({ use })` applies its options to the template via
+ * `sandbox.update(...)`; those settings persist into the snapshot.
+ * `onSession({ use })` applies its options to the live session via
  * `VercelSandbox.update()`.
  */
 export function vercelBackend() {

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

@@ -3,10 +3,10 @@
  * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
  */
 export { getSandbox } from "#context/accessors.js";
-export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxBootstrapUseOptions, type SandboxCommandOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxReadTextFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
+export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxReadTextFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
 export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
 export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
 export { defaultBackend } from "#public/sandbox/backends/default.js";
 export { localBackend } from "#public/sandbox/backends/local.js";
 export { vercelBackend } from "#public/sandbox/backends/vercel.js";
-export type { VercelSandbox, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";
+export type { VercelSandbox, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -1,5 +1,18 @@
 import type { SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
 import type { SandboxSession } from "#public/definitions/sandbox.js";
+/**
+ * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
+ * Aliases the Vercel SDK's `SandboxUpdateParams` because bootstrap
+ * applies its options to the template via `sandbox.update(...)` after
+ * `Sandbox.create()` and before the snapshot is captured. The Vercel
+ * SDK persists `update`-d settings on the sandbox so they survive into
+ * the snapshot, which becomes the seed for every later session.
+ *
+ * Today this is the same shape as
+ * {@link VercelSandboxSessionUseOptions}; both are exposed as separate
+ * named aliases so future divergence is non-breaking.
+ */
+export type VercelSandboxBootstrapUseOptions = SandboxUpdateParams;
 /**
  * Options accepted by the Vercel backend's `onSession({ use })` hook
  * and `VercelSandbox.update()`. Aliases the Vercel SDK's

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

@@ -1,4 +1,4 @@
 /**
  * Schedule authoring helpers for `agent/schedules/*` files.
  */
-export { type ChannelReceiveRef, defineSchedule, receive, type ScheduleDefinition, type TypedReceiveRoute, } from "#public/definitions/schedule.js";
+export { defineSchedule, type ScheduleDefinition, type ScheduleHandlerArgs, type ScheduleRunHandler, type TypedReceiveRoute, } from "#public/definitions/schedule.js";

package/dist/src/public/schedules/index.js

@@ -1,4 +1,4 @@
 /**
  * Schedule authoring helpers for `agent/schedules/*` files.
  */
-export { defineSchedule, receive, } from "#public/definitions/schedule.js";
+export { defineSchedule, } from "#public/definitions/schedule.js";

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

@@ -45,6 +45,7 @@ export async function resolveChannelDefinition(definition, moduleMap, nodeId) {
             },
             handler: matchedRoute?.handler,
             receive: channelDefinition.receive,
+            definition: channelDefinition,
             adapter,
             ...sourceRef,
         };

package/dist/src/runtime/schedules/resolve-schedule.js

@@ -19,18 +19,18 @@ export class ResolveScheduleError extends Error {
  */
 export async function resolveSchedules(input) {
     return [...input.manifest.schedules].map((schedule) => {
-        const resolved = {
+        const base = {
             cron: schedule.cron,
+            hasRun: schedule.hasRun,
             logicalPath: schedule.logicalPath,
-            markdown: schedule.markdown,
             name: schedule.name,
             sourceId: schedule.sourceId,
             sourceKind: schedule.sourceKind,
         };
-        if (schedule.channel !== undefined) {
-            return { ...resolved, channel: schedule.channel };
+        if (schedule.markdown !== undefined) {
+            return { ...base, markdown: schedule.markdown };
         }
-        return resolved;
+        return base;
     });
 }
 /**

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

@@ -43,20 +43,17 @@ export type ResolvedSkillDefinition = Readonly<InternalSkillDefinition & (Omit<M
 /**
  * Runtime-owned authored schedule definition resolved from compiler artifacts.
  *
- * `channel` is optional — schedules without a channel run the agent on a
- * cron and discard the output. The agent is still free to call tools,
- * write to backends, and log. `sourceKind` reflects whether the schedule
- * was authored as a TypeScript module or as a markdown file with
- * frontmatter.
+ * A schedule has exactly one of `markdown` (fire-and-forget agent run)
+ * or `hasRun: true` (authored handler). For the handler form the
+ * runtime loads the schedule's module and invokes `definition.run` with
+ * a {@link ScheduleHandlerArgs}-shaped argument; for the markdown form
+ * the dispatcher synthesizes a channel-less SCHEDULE_ADAPTER run.
  */
 export type ResolvedSchedule = Readonly<SourceRef & {
-    readonly channel?: {
-        readonly name: string;
-        readonly args: Readonly<Record<string, unknown>>;
-    };
     readonly cron: string;
     readonly name: string;
-    readonly markdown: string;
+    readonly markdown?: string;
+    readonly hasRun: boolean;
     readonly sourceKind: "markdown" | "module";
 } & (Omit<MarkdownSourceRef<undefined>, "definition"> | ModuleSourceRef)>;
 /**
@@ -187,6 +184,14 @@ export interface ResolvedChannelDefinition extends ResolvedModuleSourceRef {
      * accepting a different shape.
      */
     readonly receive?: CompiledChannel["receive"];
+    /**
+     * Reference to the authored {@link CompiledChannel} value the channel
+     * module exported. Preserved so callers of `args.receive(channel, …)`
+     * can identify a target by the same imported reference. `undefined`
+     * for framework-internal channels constructed without going through
+     * `defineChannel`.
+     */
+    readonly definition?: CompiledChannel;
     /**
      * New-style route handler from CompiledChannel. When present, the
      * dispatch layer uses this instead of `fetch`.

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

@@ -7,9 +7,9 @@ import type { SandboxSession } from "#shared/sandbox-session.js";
  * runtime orchestrator can persist reconnect metadata and release
  * resources.
  */
-export interface SandboxBackendHandle<S extends SandboxSession = SandboxSession, O = Record<string, never>> {
+export interface SandboxBackendHandle<S extends SandboxSession = SandboxSession, SO = Record<string, never>> {
     readonly session: SandboxSession;
-    readonly useSessionFn: SandboxSessionUseFn<S, O>;
+    readonly useSessionFn: SandboxSessionUseFn<S, SO>;
     captureState(): Promise<SandboxBackendSessionState>;
     dispose(): Promise<void>;
 }
@@ -79,9 +79,9 @@ export interface SandboxBackendCreateInput {
  * `bootstrap` hook and `seedFiles`, then `backend.create(...)` opens
  * durable sessions from that snapshot.
  */
-export interface SandboxBackendPrewarmInput {
+export interface SandboxBackendPrewarmInput<BO = Record<string, never>> {
     readonly templateKey: string;
-    readonly bootstrap?: (input: SandboxBootstrapContext) => void | Promise<void>;
+    readonly bootstrap?: (input: SandboxBootstrapContext<BO>) => void | Promise<void>;
     readonly runtimeContext: SandboxBackendRuntimeContext;
     readonly seedFiles: ReadonlyArray<SandboxSeedFile>;
 }
@@ -97,7 +97,7 @@ export interface SandboxBackendPrewarmInput {
  * Each backend owns the full template-then-session lifecycle internally;
  * callers only need a single `create` call.
  */
-export interface SandboxBackend<S extends SandboxSession = SandboxSession, O = Record<string, never>> {
+export interface SandboxBackend<S extends SandboxSession = SandboxSession, BO = Record<string, never>, SO = Record<string, never>> {
     /**
      * Stable identifier for this backend implementation.
      *
@@ -113,12 +113,12 @@ export interface SandboxBackend<S extends SandboxSession = SandboxSession, O = R
      * {@link SandboxTemplateNotProvisionedError} when the requested
      * template is missing.
      */
-    create(input: SandboxBackendCreateInput): Promise<SandboxBackendHandle<S, O>>;
+    create(input: SandboxBackendCreateInput): Promise<SandboxBackendHandle<S, SO>>;
     /**
      * Build-time prewarm hook. Ash invokes this for every authored
      * sandbox in the compiled graph before serving traffic so the backend
      * can capture a reusable template snapshot. Idempotent against an
      * existing snapshot keyed by `templateKey`.
      */
-    prewarm(input: SandboxBackendPrewarmInput): Promise<void>;
+    prewarm(input: SandboxBackendPrewarmInput<BO>): Promise<void>;
 }