experimental-ash 0.16.2 → 0.17.0

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/channels/upload-policy.d.ts

@@ -3,25 +3,29 @@
  */
 import type { FilePart, UserContent } from "ai";
 /**
- * Framework policy for inbound attachments.
- *
- * - `maxBytes` caps the decoded payload size. Zero means "reject every
- *   attachment"; negative values are invalid.
- * - `allowedMediaTypes` is either `"*"` (accept every type) or a list
- *   of exact or wildcard patterns. A pattern ending in `/*` matches any
- *   subtype under that top-level type (e.g. `image/*` matches
- *   `image/png`, `image/jpeg`, etc.).
+ * Framework policy for inbound attachments. Either the literal
+ * `"disabled"` (reject every attachment) or a structural config.
+ */
+export type UploadPolicy = "disabled" | UploadPolicyConfig;
+/**
+ * - `maxBytes` caps the decoded payload size. Zero also rejects every
+ *   attachment; negative values are invalid.
+ * - `allowedMediaTypes` is either `"*"` or a list of exact or wildcard
+ *   patterns. A pattern ending in `/*` matches any subtype (e.g.
+ *   `image/*` matches `image/png`).
  */
-export interface UploadPolicy {
+export interface UploadPolicyConfig {
     readonly maxBytes: number;
     readonly allowedMediaTypes: readonly string[] | "*";
 }
+/** Author-facing input accepted by channel factories. */
+export type UploadPolicyInput = "disabled" | Partial<UploadPolicyConfig>;
 /**
  * Framework default: 25 MB cap, unrestricted media types. Channels
  * override this per-route; authors override per-channel /
  * channel factory call via the `uploadPolicy` option.
  */
-export declare const DEFAULT_UPLOAD_POLICY: UploadPolicy;
+export declare const DEFAULT_UPLOAD_POLICY: UploadPolicyConfig;
 /**
  * Describes the reason one inbound `FilePart` failed the policy check.
  *
@@ -43,13 +47,16 @@ export type UploadPolicyViolation = {
 };
 /**
  * Produces a final {@link UploadPolicy} by merging an optional partial
- * override on top of {@link DEFAULT_UPLOAD_POLICY} (or another base).
- *
- * Unset fields fall through to the base policy. Callers must validate
- * structural invariants (`maxBytes >= 0`) upstream — this helper only
- * does field-level merge.
+ * override on top of `base` (default: {@link DEFAULT_UPLOAD_POLICY}).
+ * Returns `"disabled"` unchanged when passed as the override.
+ */
+export declare function mergeUploadPolicy(override?: UploadPolicyInput, base?: UploadPolicyConfig): UploadPolicy;
+/**
+ * Returns `true` when `policy` rejects every attachment — the explicit
+ * `"disabled"` literal, `maxBytes: 0`, or an empty `allowedMediaTypes`
+ * array. Channels use this to skip attachment-discovery work.
  */
-export declare function mergeUploadPolicy(override?: Partial<UploadPolicy>, base?: UploadPolicy): UploadPolicy;
+export declare function isUploadsDisabled(policy: UploadPolicy): boolean;
 /**
  * Returns `true` if `mediaType` is accepted under `policy`.
  */

package/dist/src/public/channels/upload-policy.js

@@ -13,16 +13,14 @@ export const DEFAULT_UPLOAD_POLICY = Object.freeze({
 });
 /**
  * Produces a final {@link UploadPolicy} by merging an optional partial
- * override on top of {@link DEFAULT_UPLOAD_POLICY} (or another base).
- *
- * Unset fields fall through to the base policy. Callers must validate
- * structural invariants (`maxBytes >= 0`) upstream — this helper only
- * does field-level merge.
+ * override on top of `base` (default: {@link DEFAULT_UPLOAD_POLICY}).
+ * Returns `"disabled"` unchanged when passed as the override.
  */
 export function mergeUploadPolicy(override, base = DEFAULT_UPLOAD_POLICY) {
-    if (override === undefined) {
+    if (override === "disabled")
+        return "disabled";
+    if (override === undefined)
         return base;
-    }
     const maxBytes = override.maxBytes ?? base.maxBytes;
     const allowedMediaTypes = override.allowedMediaTypes ?? base.allowedMediaTypes;
     if (maxBytes < 0 || !Number.isFinite(maxBytes)) {
@@ -30,10 +28,26 @@ export function mergeUploadPolicy(override, base = DEFAULT_UPLOAD_POLICY) {
     }
     return { allowedMediaTypes, maxBytes };
 }
+/**
+ * Returns `true` when `policy` rejects every attachment — the explicit
+ * `"disabled"` literal, `maxBytes: 0`, or an empty `allowedMediaTypes`
+ * array. Channels use this to skip attachment-discovery work.
+ */
+export function isUploadsDisabled(policy) {
+    if (policy === "disabled")
+        return true;
+    if (policy.maxBytes === 0)
+        return true;
+    if (Array.isArray(policy.allowedMediaTypes) && policy.allowedMediaTypes.length === 0)
+        return true;
+    return false;
+}
 /**
  * Returns `true` if `mediaType` is accepted under `policy`.
  */
 export function isMediaTypeAllowed(mediaType, policy) {
+    if (policy === "disabled")
+        return false;
     if (policy.allowedMediaTypes === "*") {
         return true;
     }
@@ -64,9 +78,12 @@ export function isMediaTypeAllowed(mediaType, policy) {
  * proxies enforce policy.
  */
 export function evaluateFilePart(part, policy) {
-    if (!isMediaTypeAllowed(part.mediaType, policy)) {
+    if (policy === "disabled" || !isMediaTypeAllowed(part.mediaType, policy)) {
+        const allowedMediaTypes = policy === "disabled" || policy.allowedMediaTypes === "*"
+            ? []
+            : [...policy.allowedMediaTypes];
         const violation = {
-            allowedMediaTypes: policy.allowedMediaTypes === "*" ? [] : [...policy.allowedMediaTypes],
+            allowedMediaTypes,
             kind: "disallowed-media-type",
             mediaType: part.mediaType,
         };

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,18 +1,5 @@
-declare const receiveArgsMarker: unique symbol;
-/**
- * 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.
- */
-export interface TypedReceiveRoute<TArgs = Record<string, unknown>> {
-    readonly [receiveArgsMarker]?: TArgs;
-}
-/**
- * Extracts the receive args type from a channel value.
- */
-type InferReceiveArgs<TChannel> = TChannel extends TypedReceiveRoute<infer TArgs> ? TArgs : Record<string, unknown>;
+import type { InferReceiveArgs, TypedReceiveRoute } from "#channel/receive-args.js";
+export type { InferReceiveArgs, TypedReceiveRoute } from "#channel/receive-args.js";
 /**
  * A channel reference with typed args, produced by {@link receive}.
  * Carries the route/channel object for identity resolution at compile time
@@ -80,4 +67,3 @@ export interface ScheduleDefinition {
  * ```
  */
 export declare function defineSchedule<TSchedule extends ScheduleDefinition>(definition: TSchedule): TSchedule;
-export {};

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/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/types.d.ts

@@ -187,6 +187,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>;
 }

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

@@ -1,14 +1,9 @@
 import type { SandboxSession } from "#shared/sandbox-session.js";
 import type { SandboxBackend } from "#shared/sandbox-backend.js";
-export interface SandboxBootstrapUseOptions {
-    readonly runtime?: string;
-    readonly ports?: number[];
-    readonly env?: Record<string, string>;
-}
-export type SandboxBootstrapUseFn = (options?: SandboxBootstrapUseOptions) => Promise<SandboxSession>;
+export type SandboxBootstrapUseFn<O = Record<string, never>> = (options?: O) => Promise<SandboxSession>;
 export type SandboxSessionUseFn<S extends SandboxSession = SandboxSession, O = Record<string, never>> = (options?: O) => Promise<S>;
-export interface SandboxBootstrapContext {
-    readonly use: SandboxBootstrapUseFn;
+export interface SandboxBootstrapContext<O = Record<string, never>> {
+    readonly use: SandboxBootstrapUseFn<O>;
 }
 export interface SandboxSessionContext<S extends SandboxSession = SandboxSession, O = Record<string, never>> {
     readonly use: SandboxSessionUseFn<S, O>;
@@ -26,7 +21,7 @@ export interface SandboxSessionContext<S extends SandboxSession = SandboxSession
  * `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
  * their parent's sandbox (skill seeds differ per agent).
  */
-export interface SandboxDefinition<S extends SandboxSession = SandboxSession, O = Record<string, never>> {
+export interface SandboxDefinition<S extends SandboxSession = SandboxSession, BO = Record<string, never>, SO = Record<string, never>> {
     /**
      * Backend that runs this sandbox.
      *
@@ -36,7 +31,7 @@ export interface SandboxDefinition<S extends SandboxSession = SandboxSession, O
      * everywhere else. Set `backend` explicitly to pin the sandbox to a
      * specific backend regardless of environment.
      */
-    backend: SandboxBackend<S, O>;
-    bootstrap?(input: SandboxBootstrapContext): Promise<void> | void;
-    onSession?(input: SandboxSessionContext<S, O>): Promise<void> | void;
+    backend: SandboxBackend<S, BO, SO>;
+    bootstrap?(input: SandboxBootstrapContext<BO>): Promise<void> | void;
+    onSession?(input: SandboxSessionContext<S, SO>): Promise<void> | void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"