experimental-ash 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # experimental-ash
 
+## 0.8.0
+
+### Minor Changes
+
+- a0710f7: feat(ash): update `SandboxSessionUseFn` to rely on backend-driven generic for its options instead of limiting to a central type
+
+### Patch Changes
+
+- 4c6db10: fix(ash): fix request errors due to tool results missing in model messages after tool approval in previous turn
+
+## 0.7.6
+
+### Patch Changes
+
+- 9b048ce: fix(ash): pass system messages to `agent.stream` under `instructions` to prevent AI SDK error
+
 ## 0.7.5
 
 ### Patch Changes

package/README.md

@@ -2,20 +2,9 @@
 
 Ash is a filesystem-first framework for durable backend agents on Vercel.
 
-You author an agent as a directory on disk. The directory is the contract:
+You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.
 
-- `instructions.md` defines the always-on instructions prompt
-- `skills/` define optional procedures
-- `tools/` define typed executable integrations
-- `connections/` define external MCP server connections
-- `sandbox/` overrides the agent's single sandbox (optional) and seeds workspace files
-- `channels/` define message ingress and delivery
-- `subagents/` define specialist child agents
-- `schedules/` define recurring jobs
-- `lib/` holds shared authored code
-- `agent.ts` holds additive runtime config such as model, metadata, build, compaction, and workspace settings
-
-The framework package is `experimental-ash`. The CLI binary is `ash`.
+The framework is called Ash. The published npm package is `experimental-ash`. The CLI binary is `ash`.
 
 ## What Ash Prioritizes
 
@@ -27,38 +16,53 @@ The framework package is `experimental-ash`. The CLI binary is `ash`.
 - A stable HTTP protocol with explicit `continuationToken` and `runId` contracts
 - A runtime model that keeps channels, harnesses, and workflow execution separate
 
-## Current Mental Model
-
-Ash’s internal split is:
-
-- the channel normalizes inbound transport, applies auth and delivery policy, and owns `continuationToken`
-- the harness does one unit of AI work and returns `{ session, next }`
-- the runtime persists state, follows `next`, streams events, and owns workflow primitives
-
-That split is why the public HTTP protocol separates:
-
-- `continuationToken` for the next user message
-- `runId` for streaming and inspection
-
-## Example Layout
+## Authored Directory
 
 ```text
 my-agent/
 ├── package.json
 ├── tsconfig.json
 └── agent/
-    ├── agent.ts
-    ├── instructions.md
-    ├── skills/
-    ├── tools/
-    ├── connections/
-    ├── sandbox/
-    ├── channels/
-    ├── subagents/
-    ├── schedules/
-    └── lib/
+    ├── agent.ts           # additive runtime config (model, name, build, compaction, …)
+    ├── instructions.md    # always-on instructions prompt
+    ├── tools/             # typed executable integrations
+    ├── skills/            # optional named procedures the model can load on demand
+    ├── hooks/             # lifecycle and stream-event subscribers
+    ├── channels/          # message ingress and delivery (HTTP, Slack, …)
+    ├── connections/       # external MCP server connections
+    ├── sandbox/           # the agent's single sandbox (optional override)
+    ├── workspace/         # files seeded into the sandbox on each session
+    ├── subagents/         # specialist child agents (reuse `defineAgent`)
+    ├── schedules/         # recurring jobs
+    └── lib/               # shared authored code imported by other files
 ```
 
+## Authoring Helpers
+
+Every authored directory has a typed helper. Import each from the matching subpath:
+
+| Helper                                                                                                              | Subpath                                            | Authored Location                                |
+| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------ |
+| `defineAgent(...)`                                                                                                  | `experimental-ash`                                 | `agent.ts`, `subagents/<id>/agent.ts`            |
+| `defineInstructions(...)`                                                                                           | `experimental-ash/instructions`                    | `instructions.ts` (or `instructions.md`)         |
+| `defineTool(...)`, `defineBashTool(...)`, `defineReadFileTool(...)`, `defineWriteFileTool(...)`, `disableTool(...)` | `experimental-ash/tools`                           | `tools/<name>.ts`                                |
+| `defineSkill(...)`, `getSkill(...)`                                                                                 | `experimental-ash/skills`                          | `skills/<name>.ts` (or `skills/<name>.md`)       |
+| `defineHook(...)`                                                                                                   | `experimental-ash/hooks`                           | `hooks/<slug>.ts`                                |
+| `defineChannel(...)`, `POST`, `GET`                                                                                 | `experimental-ash/channels`                        | `channels/<name>.ts`                             |
+| `ashChannel(...)`, `slack`, `slackChannel(...)`, `vercelOidc(...)`                                                  | `experimental-ash/channels/ash`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
+| `defineSandbox(...)`                                                                                                | `experimental-ash/sandbox`                         | `sandbox.ts` (or `sandbox/sandbox.ts`)           |
+| `defineSchedule(...)`                                                                                               | `experimental-ash/schedules`                       | `schedules/<name>.ts` (or `schedules/<name>.md`) |
+| `defineEvalSuite(...)`                                                                                              | `experimental-ash/evals`                           | `evals/<name>.eval.ts`                           |
+
+Runtime accessors live on the subpath that owns the concern:
+
+- `getSession()` — current session, turn, auth, parent lineage (`experimental-ash/context`)
+- `getSandbox()` — live sandbox handle for the current agent (`experimental-ash/sandbox`)
+- `getSkill(identifier)` — handle for a named skill visible to the current agent (`experimental-ash/skills`)
+- `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`experimental-ash/context`)
+
+The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/typescript-api.md`](./dist/docs/public/typescript-api.md).
+
 ## Tiny Example
 
 `agent/instructions.md`
@@ -95,7 +99,6 @@ import { defineAgent } from "experimental-ash";
 
 export default defineAgent({
   model: "openai/gpt-5.4-mini",
-  name: "weather-agent",
 });
 ```
 
@@ -104,31 +107,51 @@ export default defineAgent({
 ```bash
 pnpm create experimental-ash-agent
 cd my-agent
-pnpm install
 pnpm dev
 ```
 
-To create an agent in the current empty directory, run `pnpm create experimental-ash-agent .`.
+The wizard scaffolds the project, picks a model, and (for the REPL channel) installs dependencies and starts the dev server for you. To scaffold into the current empty directory, run `pnpm create experimental-ash-agent .`.
+
+CLI commands:
+
+- `ash info` — discovery results and compiled artifacts
+- `ash build` — compile `.ash/` and build the host output
+- `ash dev` — start the local runtime and REPL
+
+## Deploying
+
+Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/vercel-deployment.md`](./dist/docs/public/vercel-deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
+
+## Read Next
+
+These files ship inside the installed package at `node_modules/experimental-ash/dist/docs/public/`:
+
+- [Full docs index](./dist/docs/public/README.md) — recommended entry point
+- [Getting Started](./dist/docs/public/getting-started.md) — install, scaffold, and run locally
+- [Project Layout](./dist/docs/public/project-layout.md) — every authored directory in depth
+- [`agent.ts`](./dist/docs/public/agent-ts.md) — agent config reference
+- [TypeScript API](./dist/docs/public/typescript-api.md) — complete `define*` and runtime helper reference
+- [Vercel Deployment](./dist/docs/public/vercel-deployment.md) — deploy to production
+
+By authoring concern: [Tools](./dist/docs/public/tools.md) · [Channels](./dist/docs/public/channels/README.md) · [Hooks](./dist/docs/public/hooks.md) · [Skills](./dist/docs/public/skills.md) · [Sandbox](./dist/docs/public/sandbox.md) · [Workspace](./dist/docs/public/workspace.md) · [Connections](./dist/docs/public/connections.md) · [Subagents](./dist/docs/public/subagents.md) · [Schedules](./dist/docs/public/schedules.md) · [Human In The Loop](./dist/docs/public/human-in-the-loop.md) · [Evals](./dist/docs/public/evals.md)
+
+By runtime concern: [Sessions and Streaming](./dist/docs/public/runs-and-streaming.md) · [Session Context](./dist/docs/public/session-context.md) · [Context Control](./dist/docs/public/context-control.md) · [Auth and Route Protection](./dist/docs/public/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/cli-build-and-debugging.md) · [Instrumentation](./dist/docs/public/instrumentation.md)
+
+## Architecture (Internals)
 
-Useful commands:
+You do not need this section to author an Ash agent — it documents the public HTTP protocol contracts so Ash composes predictably with other systems.
 
-- `ash info` shows discovery results and compiled artifacts
-- `ash build` compiles `.ash/` and builds the host output
-- `ash dev` starts the local runtime and REPL
+Ash's internal split is:
 
-## Public Docs
+- the **channel** normalizes inbound transport, applies auth and delivery policy, and owns `continuationToken`
+- the **harness** does one unit of AI work and returns `{ session, next }`
+- the **runtime** persists state, follows `next`, streams events, and owns workflow primitives (`start()`, `resumeHook()`, `createHook()`, `getWritable()`)
 
-Start here:
+That split is why the public HTTP protocol separates two distinct identifiers:
 
-1. [`docs/public/README.md`](docs/public/README.md)
-2. [`docs/public/getting-started.md`](docs/public/getting-started.md)
-3. [`docs/public/project-layout.md`](docs/public/project-layout.md)
-4. [`docs/public/agent-ts.md`](docs/public/agent-ts.md)
-5. [`docs/public/typescript-api.md`](docs/public/typescript-api.md)
-6. [`docs/public/connections.md`](docs/public/connections.md)
+- `continuationToken` — channel-owned handle the caller uses to start the next user turn
+- `runId` — runtime-owned handle for streaming and inspection
 
-## Repo Guide
+## Changelog
 
-- [`packages/ash/README.md`](packages/ash/README.md) is the package-facing overview
-- [`skills/agent/SKILL.md`](skills/agent/SKILL.md) is the app-authoring skill
-- [`skills/framework/SKILL.md`](skills/framework/SKILL.md) is the internals skill
+See [`./CHANGELOG.md`](./CHANGELOG.md) for the release history. The changelog ships inside the published package so agents can read it directly from `node_modules/experimental-ash/CHANGELOG.md` to evaluate upgrades.

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

@@ -217,42 +217,52 @@ and channel file.
 pass a `UserContent` array mixing text and file parts:
 
 ```ts
-POST("/message", async (req, { send }) => {
-  const body = await req.json();
-
-  await send(
-    [
-      { type: "text", text: body.message },
-      { type: "file", data: body.fileData, mediaType: "image/png" },
-    ],
-    { auth: null, continuationToken: token },
-  );
-});
+await send(
+  [
+    { type: "text", text: body.message },
+    { type: "file", data: imageBytes, mediaType: "image/png" },
+  ],
+  { auth: null, continuationToken: token },
+);
 ```
 
 For platforms like Slack where files are behind authenticated URLs,
-the channel fetches the bytes before calling `send()`:
+put `URL` objects in `FilePart.data` and declare `fetchFile` on the
+channel config:
 
 ```ts
-chat.onNewMention(async (thread, message) => {
-  const parts = [{ type: "text", text: message.text }];
-
-  for (const attachment of message.attachments) {
-    const bytes = await fetchSlackFile(attachment.url, botToken);
-    parts.push({ type: "file", data: bytes, mediaType: attachment.mediaType });
-  }
+defineChannel({
+  fetchFile(url) {
+    if (!url.startsWith("https://files.slack.com/")) return null;
+    return fetch(url, { headers: { authorization: `Bearer ${token}` } })
+      .then((r) => r.arrayBuffer())
+      .then((b) => ({ bytes: Buffer.from(b) }));
+  },
 
-  await send(parts, { auth, continuationToken, state });
+  routes: [
+    POST("/webhook", async (req, { send }) => {
+      await send(
+        [
+          { type: "text", text: message.text },
+          ...message.attachments.map((a) => ({
+            type: "file" as const,
+            data: new URL(a.url),
+            mediaType: a.mediaType,
+          })),
+        ],
+        { auth, continuationToken, state },
+      );
+    }),
+  ],
 });
 ```
 
-No ref system or deferred resolution — the channel resolves bytes
-at send time.
+See [Channel file uploads](./attachments.md) for the full guide.
 
 ## What To Read Next
 
 - [Slack channel setup](./slack.md)
-- [Channel attachments](./attachments.md)
+- [Channel file uploads](./attachments.md)
 - [Project Layout](../project-layout.md)
 - [TypeScript API](../typescript-api.md)
 - [Auth And Route Protection](../auth-and-route-protection.md)

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

@@ -1,15 +1,19 @@
 ---
-title: "Channel attachments"
+title: "Channel file uploads"
 description: "Deliver inbound file attachments to the agent."
 ---
 
-This guide explains how channels deliver inbound file attachments to the agent.
+This guide explains how channels deliver inbound files to the agent.
 
 ## How it works
 
 `send()` accepts `string | UserContent`. To include file attachments,
 pass a `UserContent` array mixing text and file parts:
 
+### Inline bytes
+
+Use for small files where bytes are available in the route handler:
+
 ```ts
 await send(
   [
@@ -20,39 +24,48 @@ await send(
 );
 ```
 
-The channel is responsible for resolving file bytes before calling `send`.
+### URL-based files with fetchFile
+
 For platforms like Slack where files are behind authenticated URLs,
-the channel fetches the bytes at send time:
+put a `URL` object in `FilePart.data` and declare `fetchFile` on the
+channel config:
 
 ```ts
-chat.onNewMention(async (thread, message) => {
-  const parts = [{ type: "text", text: message.text }];
+defineChannel({
+  fetchFile(url) {
+    if (!url.startsWith("https://files.slack.com/")) return null;
+    return fetch(url, { headers: { authorization: `Bearer ${token}` } })
+      .then((r) => r.arrayBuffer())
+      .then((b) => ({ bytes: Buffer.from(b) }));
+  },
 
-  for (const attachment of message.attachments) {
-    const bytes = await fetchSlackFile(attachment.url, botToken);
-    parts.push({ type: "file", data: bytes, mediaType: attachment.mediaType });
-  }
-
-  await send(parts, { auth, continuationToken, state });
+  routes: [
+    POST("/webhook", async (req, { send }) => {
+      await send(
+        [
+          { type: "text", text: message.text },
+          ...message.attachments.map((a) => ({
+            type: "file" as const,
+            data: new URL(a.url),
+            mediaType: a.mediaType,
+          })),
+        ],
+        { auth, continuationToken, state },
+      );
+    }),
+  ],
 });
 ```
 
-## Dropped attachments
-
-Attachments that can't be fetched (no URL, expired token, network failure)
-should be logged and dropped:
-
-```ts
-if (attachment.url === undefined) {
-  console.warn("[my-channel] dropped attachment — no url available", {
-    name: attachment.name,
-  });
-  continue;
-}
-```
+The `URL` object survives the queue boundary as a string and is
+reconstituted inside the workflow step. The staging pipeline calls
+`fetchFile(url)` — return bytes to stage the file to the sandbox,
+or return `null` to let the URL pass through to the model provider.
 
-## What you do NOT have to do
+## What the framework handles
 
-- Build refs or deferred resolution — bytes are resolved at send time.
-- Stream the bytes yourself — the harness writes them to the sandbox.
-- Worry about step boundaries — the bytes travel with the message payload.
+- Staging bytes to the sandbox
+- Enforcing upload policy (size and media-type limits)
+- Hydrating files for the model call (inline bytes for images/PDFs, text
+  references for everything else)
+- Reconstituting `URL` objects after queue serialization

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

@@ -1,7 +1,6 @@
 import type { ContextAccessor } from "#context/key.js";
 import type { ContextProvider } from "#context/provider.js";
 import type { StepInput } from "#harness/types.js";
-import type { AttachmentRef } from "#internal/attachments/refs.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { DeliverPayload } from "#channel/types.js";
 /**
@@ -54,43 +53,33 @@ export type ChannelEventHandlers<TCtx extends ChannelAdapterContext<any> = Chann
     [K in HandleMessageStreamEvent["type"]]?: EventHandler<K, TCtx>;
 };
 /**
- * Enriched resolver return shape. A resolver can return either a bare
- * {@link Buffer} or this record when it learns a more accurate
- * `mediaType` or `filename` mid-fetch (e.g. from an HTTP
- * `Content-Type` header or a storage-service listing).
+ * Enriched return shape from a channel's {@link ChannelAdapter.fetchFile}
+ * function. Return a bare {@link Buffer} when only bytes are known, or
+ * this record when the fetch discovers a more accurate `mediaType` or
+ * `filename` (e.g. from an HTTP `Content-Type` header).
  *
  * When fields are provided, staging prefers them over the values the
- * channel populated at ingestion time — the resolver is the source of
- * truth for bytes *and* for anything it discovers while fetching.
+ * channel populated at ingestion time.
  */
-export interface ResolvedAttachment {
+export interface FetchFileResult {
     readonly bytes: Buffer;
     readonly mediaType?: string;
     readonly filename?: string;
 }
-/**
- * Channel-owned resolver that turns an opaque {@link AttachmentRef} back
- * into raw bytes.
- *
- * Channels that emit `ash-attachment:` refs provide this so staging can
- * re-fetch bytes inside a step boundary. Return a bare {@link Buffer} or
- * a {@link ResolvedAttachment} when fetch-time metadata should override
- * the original file part.
- */
-export interface AttachmentResolver<TParams = unknown, TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> {
-    resolve(ref: AttachmentRef<TParams>, ctx: TCtx): Promise<Buffer | ResolvedAttachment>;
-}
 /**
  * Plain-object channel adapter with durable state, an optional inbound
  * delivery hook, event handlers, and optional attachment resolution.
  */
-export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext, TAttachmentParams = unknown> = {
+export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> = {
     /**
      * Stable durable identifier for serialization across step boundaries.
      * Must be unique across all adapters visible to one runtime bundle.
      *
-     * Optional — defaults to `"http"` for the HTTP channel
-     * or derived from the route file path.
+     * Optional — defaults to {@link HTTP_ADAPTER_KIND} (`"http"`) for the
+     * canonical session channel and every behaviorless authored channel,
+     * or is derived from the route file path as `channel:<name>` once
+     * `runtime/resolve-channel.ts` rewrites authored adapters that carry
+     * behavior.
      */
     readonly kind?: string;
     /**
@@ -121,13 +110,17 @@ export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdap
      */
     createAdapterContext?(base: ChannelAdapterContext<StateOf<TCtx>>): TCtx;
     /**
-     * Optional resolver that turns an opaque {@link AttachmentRef}
-     * produced by this adapter into raw bytes.
+     * Fetches bytes for a URL encountered in `FilePart.data`.
+     *
+     * Called by the staging pipeline when it encounters a `URL` object
+     * on a `FilePart`. Return `null` to let the URL pass through to the
+     * model provider (e.g. public images). Return bytes or
+     * {@link FetchFileResult} to stage the file to the sandbox.
      *
-     * Required only for channels that put `ash-attachment:` URLs into
-     * `FilePart.data`.
+     * Credentials should be captured in the closure at channel
+     * construction time.
      */
-    readonly attachments?: AttachmentResolver<TAttachmentParams, TCtx>;
+    readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
     /**
      * Derives the continuation token from adapter state.
      *

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

@@ -10,7 +10,7 @@ export interface CompiledChannel<TState = undefined> {
         path: string;
         handler: RouteHandler<TState>;
     }[];
-    readonly adapter: ChannelAdapter<any, any>;
+    readonly adapter: ChannelAdapter<any>;
     readonly receive?: (input: {
         readonly message: string;
         readonly args: Readonly<Record<string, unknown>>;

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

@@ -0,0 +1,29 @@
+import type { ChannelAdapter } from "#channel/adapter.js";
+/**
+ * Durable adapter kind for the canonical session channel and for every
+ * behaviorless user-authored channel returned by the `defineChannel`
+ * fast-path (no state, no `context()`, no event handlers, no `fetchFile`).
+ *
+ * The value is locked at `"http"` because it is persisted into durable
+ * workflow state under `serializedContext["ash.channel"].kind` and into
+ * sandbox telemetry tags as `channel: "http"`. Renaming the value would
+ * break rehydration for every in-flight session started under any prior
+ * build with "Unknown adapter kind: \"http\"". The `httpChannel` →
+ * `ashChannel` rename (commit `bd3d1b43`) intentionally renamed the
+ * channel identifier (file name, function name, framework constant) but
+ * deliberately left this adapter kind alone — the kind labels the
+ * adapter's transport class, not the channel's name, and the same slot
+ * is the rehydration target for every behaviorless authored channel
+ * regardless of which protocol it speaks.
+ */
+export declare const HTTP_ADAPTER_KIND = "http";
+/**
+ * Framework adapter installed for the canonical session channel and
+ * for every behaviorless user-authored channel.
+ *
+ * Carries no behavior — it is a bare discriminator that the runtime
+ * adapter registry uses to rehydrate `{ kind: "http" }` at every
+ * workflow step boundary. Registered in `FRAMEWORK_ADAPTERS`
+ * (`runtime/channels/registry.ts`).
+ */
+export declare const HTTP_ADAPTER: ChannelAdapter;

package/dist/src/channel/http.js

@@ -0,0 +1,30 @@
+/**
+ * Durable adapter kind for the canonical session channel and for every
+ * behaviorless user-authored channel returned by the `defineChannel`
+ * fast-path (no state, no `context()`, no event handlers, no `fetchFile`).
+ *
+ * The value is locked at `"http"` because it is persisted into durable
+ * workflow state under `serializedContext["ash.channel"].kind` and into
+ * sandbox telemetry tags as `channel: "http"`. Renaming the value would
+ * break rehydration for every in-flight session started under any prior
+ * build with "Unknown adapter kind: \"http\"". The `httpChannel` →
+ * `ashChannel` rename (commit `bd3d1b43`) intentionally renamed the
+ * channel identifier (file name, function name, framework constant) but
+ * deliberately left this adapter kind alone — the kind labels the
+ * adapter's transport class, not the channel's name, and the same slot
+ * is the rehydration target for every behaviorless authored channel
+ * regardless of which protocol it speaks.
+ */
+export const HTTP_ADAPTER_KIND = "http";
+/**
+ * Framework adapter installed for the canonical session channel and
+ * for every behaviorless user-authored channel.
+ *
+ * Carries no behavior — it is a bare discriminator that the runtime
+ * adapter registry uses to rehydrate `{ kind: "http" }` at every
+ * workflow step boundary. Registered in `FRAMEWORK_ADAPTERS`
+ * (`runtime/channels/registry.ts`).
+ */
+export const HTTP_ADAPTER = {
+    kind: HTTP_ADAPTER_KIND,
+};

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

@@ -1,6 +1,26 @@
+import type { ChannelAdapter } from "#channel/adapter.js";
 import { type Session } from "#channel/session.js";
 import type { Runtime } from "#channel/types.js";
 import type { ResolvedChannelDefinition } from "#runtime/types.js";
+/**
+ * Durable adapter kind used when a schedule triggers a session that does
+ * not target a channel.
+ *
+ * Framework-owned — authored code never constructs a schedule adapter
+ * directly. Emitted by {@link ScheduleDispatcher.trigger} when the
+ * authored schedule has no `channel` field (the only path available to
+ * markdown schedules, which are forbidden from declaring a channel).
+ */
+export declare const SCHEDULE_ADAPTER_KIND = "schedule";
+/**
+ * Framework adapter installed for channel-less schedules.
+ *
+ * Carries no behavior — it is a bare discriminator so the runtime adapter
+ * registry can rehydrate `{ kind: "schedule" }` at every workflow step
+ * boundary. Registered in `FRAMEWORK_ADAPTERS`
+ * (`runtime/channels/registry.ts`).
+ */
+export declare const SCHEDULE_ADAPTER: ChannelAdapter;
 type ScheduleChannel = Pick<ResolvedChannelDefinition, "receive" | "adapter">;
 export interface ScheduleTriggerInput {
     readonly channel?: {

package/dist/src/channel/schedule.js

@@ -6,6 +6,27 @@ const APP_AUTH = {
     principalId: "ash:app",
     principalType: "runtime",
 };
+/**
+ * Durable adapter kind used when a schedule triggers a session that does
+ * not target a channel.
+ *
+ * Framework-owned — authored code never constructs a schedule adapter
+ * directly. Emitted by {@link ScheduleDispatcher.trigger} when the
+ * authored schedule has no `channel` field (the only path available to
+ * markdown schedules, which are forbidden from declaring a channel).
+ */
+export const SCHEDULE_ADAPTER_KIND = "schedule";
+/**
+ * Framework adapter installed for channel-less schedules.
+ *
+ * Carries no behavior — it is a bare discriminator so the runtime adapter
+ * registry can rehydrate `{ kind: "schedule" }` at every workflow step
+ * boundary. Registered in `FRAMEWORK_ADAPTERS`
+ * (`runtime/channels/registry.ts`).
+ */
+export const SCHEDULE_ADAPTER = {
+    kind: SCHEDULE_ADAPTER_KIND,
+};
 /**
  * Dispatcher for scheduled task execution.
  *
@@ -27,7 +48,7 @@ export class ScheduleDispatcher {
     async trigger(input) {
         if (input.channel === undefined) {
             const handle = await this.runtime.run({
-                adapter: { kind: "schedule" },
+                adapter: SCHEDULE_ADAPTER,
                 auth: APP_AUTH,
                 input: { message: input.markdown },
                 mode: "task",

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

@@ -1,4 +1,4 @@
 import type { ChannelAdapter } from "#channel/adapter.js";
 import type { Runtime } from "#channel/types.js";
 import type { SendFn } from "#channel/routes.js";
-export declare function createSendFn<TState = undefined>(runtime: Runtime, adapter: ChannelAdapter<any, any>, channelName: string): SendFn<TState>;
+export declare function createSendFn<TState = undefined>(runtime: Runtime, adapter: ChannelAdapter<any>, channelName: string): SendFn<TState>;

package/dist/src/channel/send.js

@@ -1,4 +1,5 @@
 import { createSession } from "#channel/session.js";
+import { serializeUrlFilePart } from "#internal/attachments/url-refs.js";
 import { createLogger } from "#internal/logging.js";
 const log = createLogger("channel.send");
 export function createSendFn(runtime, adapter, channelName) {
@@ -7,7 +8,8 @@ export function createSendFn(runtime, adapter, channelName) {
         const rawToken = options.continuationToken;
         const continuationToken = `${channelName}:${rawToken}`;
         const state = options.state;
-        const { message, inputResponses } = normalizeSendInput(input);
+        const { message: rawMessage, inputResponses } = normalizeSendInput(input);
+        const message = serializeUrlFilePartsInMessage(rawMessage);
         try {
             const { sessionId } = await runtime.deliver({
                 auth,
@@ -36,6 +38,25 @@ export function createSendFn(runtime, adapter, channelName) {
         return createSession(handle.sessionId, rawToken, runtime);
     };
 }
+/**
+ * Serializes `URL` objects in `FilePart.data` to `ash-url:` strings
+ * before the message crosses the queue boundary. The staging pipeline
+ * reconstitutes them on the other side.
+ */
+function serializeUrlFilePartsInMessage(message) {
+    if (message === undefined || typeof message === "string") {
+        return message;
+    }
+    let changed = false;
+    const result = message.map((part) => {
+        if (part.type === "file" && part.data instanceof URL && part.data.protocol !== "data:") {
+            changed = true;
+            return { ...part, data: serializeUrlFilePart(part.data) };
+        }
+        return part;
+    });
+    return changed ? result : message;
+}
 function normalizeSendInput(input) {
     if (typeof input === "string") {
         return { message: input };