experimental-ash 0.18.0 → 0.18.2

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

@@ -6,6 +6,15 @@
  * required or exposed through Ash public APIs.
  */
 import { type TwilioAuthToken } from "#public/channels/twilio/verify.js";
+/**
+ * Builds the Twilio channel-local continuation token
+ * (`<from>:<to>`). Route `send()` namespaces this with the channel
+ * name before handing it to the runtime (`twilio:<from>:<to>`), so
+ * Twilio routes should pass the raw channel-local form returned
+ * here. `to` may be empty for proactive sessions that don't yet know
+ * the Twilio sender number.
+ */
+export declare function twilioContinuationToken(from: string, to: string | undefined): string;
 /** Twilio Account SID, materialized directly or from an async secret provider. */
 export type TwilioAccountSid = string | (() => string | Promise<string>);
 /** Fetch implementation override used by tests or non-standard runtimes. */

package/dist/src/public/channels/twilio/api.js

@@ -6,6 +6,17 @@
  * required or exposed through Ash public APIs.
  */
 import { resolveTwilioAuthToken } from "#public/channels/twilio/verify.js";
+/**
+ * Builds the Twilio channel-local continuation token
+ * (`<from>:<to>`). Route `send()` namespaces this with the channel
+ * name before handing it to the runtime (`twilio:<from>:<to>`), so
+ * Twilio routes should pass the raw channel-local form returned
+ * here. `to` may be empty for proactive sessions that don't yet know
+ * the Twilio sender number.
+ */
+export function twilioContinuationToken(from, to) {
+    return `${from}:${to ?? ""}`;
+}
 /** Resolves a Twilio Account SID, falling back to `TWILIO_ACCOUNT_SID`. */
 export async function resolveTwilioAccountSid(accountSid) {
     const source = accountSid ?? process.env.TWILIO_ACCOUNT_SID;

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

@@ -1,5 +1,5 @@
 export { twilioChannel, type TwilioAllowFrom, type TwilioChannel, type TwilioChannelConfig, type TwilioChannelCredentials, type TwilioChannelEvents, type TwilioChannelState, type TwilioContext, type TwilioEventContext, type TwilioHandle, type TwilioInboundResult, type TwilioInboundResultOrPromise, type TwilioMessagingConfig, type TwilioReceiveArgs, type TwilioSendMessageOptions, type TwilioVoiceConfig, type TwilioVoiceResult, type TwilioVoiceResultOrPromise, } from "#public/channels/twilio/twilioChannel.js";
-export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, type TwilioAccountSid, type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials, type TwilioFetch, type TwilioSendMessageInput, type TwilioUpdateCallInput, } from "#public/channels/twilio/api.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, twilioContinuationToken, updateTwilioCall, type TwilioAccountSid, type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials, type TwilioFetch, type TwilioSendMessageInput, type TwilioUpdateCallInput, } from "#public/channels/twilio/api.js";
 export type { TwilioInboundContext, TwilioTextMessage, TwilioVoiceCall, TwilioVoiceTranscription, } from "#public/channels/twilio/inbound.js";
 export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, type TwilioGatherTwimlOptions, } from "#public/channels/twilio/twiml.js";
 export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, type TwilioAuthToken, type TwilioVerifiedRequest, type TwilioVerifyOptions, type TwilioWebhookUrl, } from "#public/channels/twilio/verify.js";

package/dist/src/public/channels/twilio/index.js

@@ -1,4 +1,4 @@
 export { twilioChannel, } from "#public/channels/twilio/twilioChannel.js";
-export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, } from "#public/channels/twilio/api.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, twilioContinuationToken, updateTwilioCall, } from "#public/channels/twilio/api.js";
 export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, } from "#public/channels/twilio/twiml.js";
 export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, } from "#public/channels/twilio/verify.js";

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

@@ -1,4 +1,5 @@
 import type { TypedReceiveRoute } from "#channel/receive-args.js";
+import type { SessionHandle } from "#channel/session.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";
@@ -16,6 +17,7 @@ export interface TwilioContext {
 }
 /** Event-handler Twilio context, including mutable per-phone channel state. */
 export interface TwilioEventContext extends TwilioContext {
+    readonly session: SessionHandle;
     state: TwilioChannelState;
 }
 /** JSON-serializable state for the phone-number conversation. */

package/dist/src/public/channels/twilio/twilioChannel.js

@@ -1,5 +1,5 @@
 import { createLogger } from "#internal/logging.js";
-import { callTwilioApi, sendTwilioMessage, updateTwilioCall, } from "#public/channels/twilio/api.js";
+import { callTwilioApi, sendTwilioMessage, twilioContinuationToken, updateTwilioCall, } from "#public/channels/twilio/api.js";
 import { defaultEvents, defaultOnText, defaultOnVoice, defaultOnVoiceTranscription, } from "#public/channels/twilio/defaults.js";
 import { parseTwilioTextMessage, parseTwilioVoiceCall, parseTwilioVoiceTranscription, prependTwilioContext, } from "#public/channels/twilio/inbound.js";
 import { emptyTwilioResponse, gatherSpeechTwilioResponse, sayTwilioResponse, } from "#public/channels/twilio/twiml.js";
@@ -22,8 +22,8 @@ export function twilioChannel(config) {
             lastCallSid: null,
             lastMessageSid: null,
         },
-        context(state) {
-            return rebuildTwilioContext(state, config);
+        context(state, session) {
+            return rebuildTwilioContext(state, session, config);
         },
         routes: [
             POST(routes.messages, async (req, { send, waitUntil }) => {
@@ -96,10 +96,9 @@ export function twilioChannel(config) {
                 throw new Error("twilioChannel().receive requires args.phoneNumber.");
             }
             const from = readString(input.args.from) ?? config.messaging?.from ?? null;
-            const continuationToken = encodeTwilioContinuationToken(phoneNumber, from);
             return send(input.message, {
                 auth: input.auth,
-                continuationToken,
+                continuationToken: twilioContinuationToken(phoneNumber, from ?? undefined),
                 state: {
                     from: phoneNumber,
                     lastCallSid: null,
@@ -111,8 +110,9 @@ export function twilioChannel(config) {
         events: mergedEvents,
     });
 }
-function rebuildTwilioContext(state, config) {
+function rebuildTwilioContext(state, session, config) {
     return {
+        session,
         state,
         twilio: buildTwilioHandle({
             callSid: state.lastCallSid ?? undefined,
@@ -218,7 +218,7 @@ async function dispatchText(input) {
     try {
         await input.send(turnMessage, {
             auth: result.auth,
-            continuationToken: encodeTwilioContinuationToken(message.from, message.to),
+            continuationToken: twilioContinuationToken(message.from, message.to),
             state: {
                 from: message.from,
                 lastCallSid: null,
@@ -278,7 +278,7 @@ async function dispatchVoiceTranscription(input) {
     try {
         await input.send(turnMessage, {
             auth: result.auth,
-            continuationToken: encodeTwilioContinuationToken(transcription.from, transcription.to),
+            continuationToken: twilioContinuationToken(transcription.from, transcription.to),
             state: {
                 from: transcription.from,
                 lastCallSid: transcription.callSid ?? null,
@@ -297,9 +297,6 @@ async function isAllowed(from, allowFrom) {
         return true;
     return typeof resolved === "string" ? resolved === from : resolved.includes(from);
 }
-function encodeTwilioContinuationToken(from, to) {
-    return `${from}:${to ?? ""}`;
-}
 async function buildActionUrl(request, config, route) {
     const base = typeof config.publicBaseUrl === "function"
         ? await config.publicBaseUrl(request)

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

@@ -33,7 +33,15 @@ export interface ChannelEvents<TCtx = void> {
 }
 export interface ChannelConfig<TState = undefined, TCtx = void> {
     readonly state?: TState;
-    context?(state: NonNullable<TState>): TCtx;
+    /**
+     * Builds the per-step channel context handed to `events` and
+     * `deliver`. Receives the live {@link SessionHandle} so factories
+     * that need to wire late-bound callbacks (e.g. Slack's auto-anchor
+     * `onAnchor` calling `session.setContinuationToken(...)`) can close
+     * over it. State mutations made inside the returned context flow
+     * back through `adapter.state` automatically.
+     */
+    context?(state: NonNullable<TState>, session: SessionHandle): TCtx;
     readonly routes: readonly RouteDefinition<TState>[];
     receive?(input: {
         readonly message: string;

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

@@ -48,26 +48,21 @@ function buildAdapter(config) {
     if (!hasBehavior && !hasEventHandlers && !hasFetchFile) {
         return { kind: config.kindHint ?? HTTP_ADAPTER_KIND };
     }
-    return {
+    const adapter = {
         kind: config.kindHint ?? "defineChannel",
         state: hasState ? { ...config.state } : {},
         fetchFile: config.fetchFile,
         createAdapterContext(base) {
             const state = base.state;
-            const channelCtx = hasContext ? config.context(state) : {};
+            const session = base.session;
+            const channelCtx = hasContext
+                ? config.context(state, session)
+                : {};
             return {
                 ...channelCtx,
                 state,
                 ctx: base.ctx,
-                session: {
-                    id: "",
-                    continuationToken: "",
-                    auth: null,
-                    initiatorAuth: null,
-                    setContinuationToken(_token) {
-                        // TODO: wire to runtime
-                    },
-                },
+                session,
             };
         },
         deliver(payload) {
@@ -75,4 +70,5 @@ function buildAdapter(config) {
         },
         ...eventHandlers,
     };
+    return adapter;
 }

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

@@ -1,10 +1,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 { 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">;
+export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinition<BO, SO>, "backend">;
 /**
  * Defines a sandbox configuration.
  */
-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>;
+export declare function defineSandbox<BO = Record<string, never>, SO = Record<string, never>>(definition: SandboxDefinition<BO, SO>): SandboxDefinition<BO, SO>;

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, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+import type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
  * `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()`.
+ * `onSession({ use })` applies its options to the live session via the
+ * SDK's `update` under the hood.
  */
-export declare function vercelBackend(): SandboxBackend<VercelSandbox, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;
+export declare function vercelBackend(): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;

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

@@ -4,8 +4,8 @@ import { createVercelSandboxBackend } from "#execution/sandbox/bindings/vercel.j
  *
  * `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()`.
+ * `onSession({ use })` applies its options to the live session via the
+ * SDK's `update` under the hood.
  */
 export function vercelBackend() {
     return createVercelSandboxBackend();

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

@@ -9,4 +9,4 @@ export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-
 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, VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";
+export type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";

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

@@ -1,5 +1,4 @@
 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
@@ -14,32 +13,8 @@ import type { SandboxSession } from "#public/definitions/sandbox.js";
  */
 export type VercelSandboxBootstrapUseOptions = SandboxUpdateParams;
 /**
- * Options accepted by the Vercel backend's `onSession({ use })` hook
- * and `VercelSandbox.update()`. Aliases the Vercel SDK's
- * `SandboxUpdateParams` so the full live-session configuration surface
- * is available to authors.
+ * Options accepted by the Vercel backend's `onSession({ use })` hook.
+ * Aliases the Vercel SDK's `SandboxUpdateParams`; passed values are
+ * applied to the live session via the SDK's `update` under the hood.
  */
 export type VercelSandboxSessionUseOptions = SandboxUpdateParams;
-/**
- * Ash-owned session type returned by the Vercel backend's
- * `onSession({ use })` hook. Extends the narrow
- * {@link SandboxSession} with Vercel-specific capabilities that only
- * make sense on a live session sandbox (not a bootstrap template).
- */
-export interface VercelSandbox extends SandboxSession {
-    readonly name: string;
-    readonly persistent: boolean;
-    readonly status: string;
-    readonly networkPolicy: SandboxUpdateParams["networkPolicy"];
-    readonly tags: Record<string, string> | undefined;
-    update(params: VercelSandboxSessionUseOptions): Promise<void>;
-    stop(opts?: {
-        blocking?: boolean;
-    }): Promise<void>;
-    snapshot(opts?: {
-        expiration?: number;
-    }): Promise<{
-        snapshotId: string;
-    }>;
-    domain(port: number): string;
-}

package/dist/src/react/index.d.ts

@@ -0,0 +1,3 @@
+export { useAshAgent, type UseAshAgentHelpers, type UseAshAgentOptions, type UseAshAgentSnapshot, type UseAshAgentStatus, } from "#react/use-ash-agent.js";
+export { type AshAgentReducer, type AshAgentReducerEvent, type ClientInputRespondedEvent, type ClientMessageFailedEvent, type ClientMessageSubmittedEvent, } from "#client/reducer.js";
+export { defaultMessageReducer, type AshMessageData, type AshDynamicToolPart, type AshMessageInputRequest, type AshMessage, type AshMessageMetadata, type AshMessagePart, type AshMessageToolMetadata, } from "#client/message-reducer.js";

package/dist/src/react/index.js

@@ -0,0 +1,3 @@
+export { useAshAgent, } from "#react/use-ash-agent.js";
+export {} from "#client/reducer.js";
+export { defaultMessageReducer, } from "#client/message-reducer.js";

package/dist/src/react/use-ash-agent.d.ts

@@ -0,0 +1,79 @@
+import type { AshAgentReducer } from "#client/reducer.js";
+import type { ClientSession } from "#client/session.js";
+import { type AshMessageData } from "#client/message-reducer.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { ClientAuth, HeadersValue, SendMessageOptions, SendTurnInput, SessionState } from "#client/types.js";
+export type UseAshAgentStatus = "error" | "ready" | "streaming" | "submitted";
+/**
+ * Current projected state for an Ash agent session.
+ */
+export interface UseAshAgentSnapshot<TData> {
+    readonly data: TData;
+    readonly error: Error | undefined;
+    readonly events: readonly HandleMessageStreamEvent[];
+    readonly session: SessionState;
+    readonly status: UseAshAgentStatus;
+}
+/**
+ * Lifecycle callbacks invoked while `useAshAgent` processes a turn.
+ */
+export interface UseAshAgentCallbacks<TData> {
+    readonly onError?: (error: Error) => void;
+    readonly onEvent?: (event: HandleMessageStreamEvent) => void;
+    readonly onFinish?: (snapshot: UseAshAgentSnapshot<TData>) => void;
+    readonly onSessionChange?: (session: SessionState) => void;
+}
+/**
+ * Snapshot plus commands returned by `useAshAgent`.
+ */
+export interface UseAshAgentHelpers<TData> extends UseAshAgentSnapshot<TData> {
+    readonly reset: () => void;
+    readonly send: (input: SendTurnInput, options?: SendMessageOptions) => Promise<void>;
+    readonly sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
+    readonly stop: () => void;
+}
+/**
+ * Configuration for creating or binding a React Ash agent session.
+ *
+ * Session configuration is read when the hook creates its internal store. To
+ * point the hook at a different host, reducer, or session, remount the
+ * component that calls the hook. Lifecycle callbacks are updated on every
+ * render.
+ *
+ * For credentials or headers that must change without remounting, pass function
+ * values to `auth` or `headers`; the underlying client resolves those before
+ * each HTTP request.
+ */
+export interface UseAshAgentOptions<TData> extends UseAshAgentCallbacks<TData> {
+    readonly auth?: ClientAuth;
+    readonly headers?: HeadersValue;
+    /**
+     * Base URL used for Ash client requests.
+     *
+     * By default, requests target same-origin Ash routes such as `/ash/v1/...`.
+     * Pass a same-origin prefix such as `/api` to use an app-owned proxy, or an
+     * absolute origin to talk to an Ash server directly.
+     *
+     * @default ""
+     */
+    readonly host?: string;
+    readonly initialEvents?: readonly HandleMessageStreamEvent[];
+    readonly initialSession?: SessionState;
+    readonly maxReconnectAttempts?: number;
+    /**
+     * Project submitted user messages before Ash confirms them with a
+     * `message.received` stream event.
+     *
+     * Optimistic events are reducer-facing projection events only. They are not
+     * exposed through `events`, which remains the authoritative Ash stream.
+     *
+     * @default true
+     */
+    readonly optimistic?: boolean;
+    readonly reducer?: AshAgentReducer<TData>;
+    readonly session?: ClientSession;
+}
+export declare function useAshAgent(options?: UseAshAgentOptions<AshMessageData>): UseAshAgentHelpers<AshMessageData>;
+export declare function useAshAgent<TData>(options: UseAshAgentOptions<TData> & {
+    readonly reducer: AshAgentReducer<TData>;
+}): UseAshAgentHelpers<TData>;