experimental-ash 0.50.0 → 0.52.0

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

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{verifyTwilioRequest}from"#public/channels/twilio/verify.js";import{callTwilioApi,sendTwilioMessage,twilioContinuationToken,updateTwilioCall}from"#public/channels/twilio/api.js";import{emptyTwilioResponse,gatherSpeechTwilioResponse,sayTwilioResponse}from"#public/channels/twilio/twiml.js";import{defaultEvents,defaultOnText,defaultOnVoice,defaultOnVoiceTranscription}from"#public/channels/twilio/defaults.js";import{formatTwilioContextBlock,parseTwilioTextMessage,parseTwilioVoiceCall,parseTwilioVoiceTranscription}from"#public/channels/twilio/inbound.js";const log=createLogger(`twilio.channel`);function twilioChannel(e){assertAllowFromConfigured(e);let r=buildRoutes(e.route??`/ash/v1/twilio`),i=e.onText??defaultOnText,a=e.onVoice??defaultOnVoice,s=e.onVoiceTranscription??defaultOnVoiceTranscription,l={...defaultEvents,...e.events};return defineChannel({kindHint:`twilio`,state:{from:null,to:null,lastCallSid:null,lastMessageSid:null},metadata(e){return{from:e.from,lastCallSid:e.lastCallSid??null,lastMessageSid:e.lastMessageSid??null,to:e.to}},context(t,n){return rebuildTwilioContext(t,n,e)},routes:[POST(r.messages,async(t,{send:n,waitUntil:r})=>{let a=await verifyInbound(t,e);if(a===null)return new Response(`unauthorized`,{status:401});let o=parseTwilioTextMessage(a.params);return o?await isAllowed(o.from,e.allowFrom)?(r(dispatchText({config:e,message:o,onText:i,send:n})),emptyTwilioResponse()):new Response(`forbidden`,{status:403}):emptyTwilioResponse()}),POST(r.voice,async t=>{let n=await verifyInbound(t,e);if(n===null)return new Response(`unauthorized`,{status:401});let i=parseTwilioVoiceCall(n.params);if(!i)return sayTwilioResponse(`Missing caller information.`);if(!await isAllowed(i.from,e.allowFrom))return new Response(`forbidden`,{status:403});let o=await acceptVoiceCall({call:i,config:e,onVoice:a});if(o===null)return new Response(`forbidden`,{status:403});let s=o??{};return gatherSpeechTwilioResponse({actionUrl:await buildActionUrl(t,e,r.transcription),hints:s.hints??e.voice?.hints,language:s.language??e.voice?.language,profanityFilter:s.profanityFilter??e.voice?.profanityFilter,prompt:s.prompt??e.voice?.prompt??`Please say your message after the tone.`,speechModel:s.speechModel??e.voice?.speechModel,speechTimeout:s.speechTimeout??e.voice?.speechTimeout??`auto`,timeoutSeconds:s.timeoutSeconds??e.voice?.timeoutSeconds,voice:s.voice??e.voice?.voice})}),POST(r.transcription,async(t,{send:n,waitUntil:i})=>{let a=await verifyInbound(t,e);if(a===null)return new Response(`unauthorized`,{status:401});let o=parseTwilioVoiceTranscription(a.params);return o?await isAllowed(o.from,e.allowFrom)?(i(dispatchVoiceTranscription({config:e,onVoiceTranscription:s,send:n,transcription:o})),sayTwilioResponse(e.voice?.acknowledgement??`Thanks. I'll follow up by text.`)):new Response(`forbidden`,{status:403}):gatherSpeechTwilioResponse({actionUrl:await buildActionUrl(t,e,r.transcription),language:e.voice?.language,prompt:e.voice?.prompt??`Please say your message after the tone.`,speechTimeout:e.voice?.speechTimeout??`auto`,timeoutSeconds:e.voice?.timeoutSeconds})})],async receive(t,{send:n}){let r=readString(t.args.phoneNumber);if(!r)throw Error(`twilioChannel().receive requires args.phoneNumber.`);let i=readString(t.args.from)??e.messaging?.from??null;return n(t.message,{auth:t.auth,continuationToken:twilioContinuationToken(r,i??void 0),state:{from:r,lastCallSid:null,lastMessageSid:null,to:i}})},events:l})}function rebuildTwilioContext(e,t,n){return{state:e,twilio:buildTwilioHandle({callSid:e.lastCallSid??void 0,config:n,from:e.from??``,to:e.to??void 0})}}function buildTwilioHandle(e){let t=e.config.api,n=e.config.credentials,r=e.config.messaging?.from??e.to,o=e.config.messaging?.messagingServiceSid,c=e.config.messaging?.statusCallbackUrl;return{callSid:e.callSid,from:e.from,to:e.to,request(e,r){return callTwilioApi({apiBaseUrl:t?.apiBaseUrl,body:r,credentials:n,fetch:t?.fetch,path:e})},sendMessage(i,s){return sendTwilioMessage({apiBaseUrl:t?.apiBaseUrl,body:i,credentials:n,fetch:t?.fetch,from:s?.from??r,messagingServiceSid:s?.messagingServiceSid??o,statusCallbackUrl:s?.statusCallbackUrl??c,to:s?.to??e.from})},updateCall(e,r){return updateTwilioCall({apiBaseUrl:t?.apiBaseUrl,callSid:e,credentials:n,fetch:t?.fetch,twiml:r})}}}function buildRoutes(e){let t=e.endsWith(`/`)?e.slice(0,-1):e;return{messages:`${t}/messages`,transcription:`${t}/voice/transcription`,voice:`${t}/voice`}}function assertAllowFromConfigured(e){if(e?.allowFrom===void 0)throw Error(`twilioChannel requires allowFrom. Use allowFrom: "*" to allow all numbers.`)}async function verifyInbound(e,t){try{return await verifyTwilioRequest(e,{authToken:t.credentials?.authToken,webhookUrl:t.webhookUrl})}catch(e){return log.warn(`twilio inbound verification failed`,{error:e}),null}}async function dispatchText(e){let{message:t}=e,n={twilio:buildTwilioHandle({callSid:void 0,config:e.config,from:t.from,to:t.to})},r;try{r=await e.onText(n,t)}catch(e){log.error(`text handler failed`,{error:e});return}if(r==null)return;let i=formatTwilioContextBlock({channel:`text`,from:t.from,messageSid:t.messageSid,to:t.to});try{await e.send({message:t.body,context:[i]},{auth:r.auth,continuationToken:twilioContinuationToken(t.from,t.to),state:{from:t.from,lastCallSid:null,lastMessageSid:t.messageSid??null,to:t.to??null}})}catch(e){log.error(`text delivery failed`,{error:e})}}async function acceptVoiceCall(e){let{call:t}=e,n={twilio:buildTwilioHandle({callSid:t.callSid,config:e.config,from:t.from,to:t.to})};try{return await e.onVoice(n,t)}catch(e){return log.error(`voice handler failed`,{error:e}),null}}async function dispatchVoiceTranscription(e){let{transcription:t}=e,n={twilio:buildTwilioHandle({callSid:t.callSid,config:e.config,from:t.from,to:t.to})},r;try{r=await e.onVoiceTranscription(n,t)}catch(e){log.error(`voice transcription handler failed`,{error:e});return}if(r==null)return;let i=formatTwilioContextBlock({callSid:t.callSid,channel:`voice`,from:t.from,to:t.to});try{await e.send({message:t.text,context:[i]},{auth:r.auth,continuationToken:twilioContinuationToken(t.from,t.to),state:{from:t.from,lastCallSid:t.callSid??null,lastMessageSid:null,to:t.to??null}})}catch(e){log.error(`voice transcription delivery failed`,{error:e})}}async function isAllowed(e,t){let n=typeof t==`function`?await t():t;return n===`*`?!0:typeof n==`string`?n===e:n.includes(e)}async function buildActionUrl(e,t,n){let r=typeof t.publicBaseUrl==`function`?await t.publicBaseUrl(e):t.publicBaseUrl;if(r)return new URL(n,ensureTrailingSlash(r)).toString();let i=new URL(e.url);return i.pathname=n,i.search=``,i.toString()}function ensureTrailingSlash(e){return e.endsWith(`/`)?e:`${e}/`}function readString(e){return typeof e==`string`&&e.length>0?e:void 0}export{twilioChannel};
+import{createLogger}from"#internal/logging.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{verifyTwilioRequest}from"#public/channels/twilio/verify.js";import{callTwilioApi,sendTwilioMessage,twilioContinuationToken,updateTwilioCall}from"#public/channels/twilio/api.js";import{emptyTwilioResponse,gatherSpeechTwilioResponse,sayTwilioResponse}from"#public/channels/twilio/twiml.js";import{defaultEvents,defaultOnText,defaultOnVoice,defaultOnVoiceTranscription}from"#public/channels/twilio/defaults.js";import{formatTwilioContextBlock,parseTwilioTextMessage,parseTwilioVoiceCall,parseTwilioVoiceTranscription}from"#public/channels/twilio/inbound.js";const log=createLogger(`twilio.channel`);function twilioChannel(e){assertAllowFromConfigured(e);let r=buildRoutes(e.route??`/ash/v1/twilio`),i=e.onText??defaultOnText,a=e.onVoice??defaultOnVoice,s=e.onVoiceTranscription??defaultOnVoiceTranscription,l={...defaultEvents,...e.events};return defineChannel({kindHint:`twilio`,state:{from:null,to:null,lastCallSid:null,lastMessageSid:null},metadata(e){return{from:e.from,lastCallSid:e.lastCallSid??null,lastMessageSid:e.lastMessageSid??null,to:e.to}},context(t,n){return rebuildTwilioContext(t,n,e)},routes:[POST(r.messages,async(t,{send:n,waitUntil:r})=>{let a=await verifyInbound(t,e);if(a===null)return new Response(`unauthorized`,{status:401});let o=parseTwilioTextMessage(a.params);return o?await isAllowed(o.from,e.allowFrom)?(r(dispatchText({config:e,message:o,onText:i,send:n})),emptyTwilioResponse()):new Response(`forbidden`,{status:403}):emptyTwilioResponse()}),POST(r.voice,async t=>{let n=await verifyInbound(t,e);if(n===null)return new Response(`unauthorized`,{status:401});let i=parseTwilioVoiceCall(n.params);if(!i)return sayTwilioResponse(`Missing caller information.`);if(!await isAllowed(i.from,e.allowFrom))return new Response(`forbidden`,{status:403});let o=await acceptVoiceCall({call:i,config:e,onVoice:a});if(o===null)return new Response(`forbidden`,{status:403});let s=o??{};return gatherSpeechTwilioResponse({actionUrl:await buildActionUrl(t,e,r.transcription),hints:s.hints??e.voice?.hints,language:s.language??e.voice?.language,profanityFilter:s.profanityFilter??e.voice?.profanityFilter,prompt:s.prompt??e.voice?.prompt??`Please say your message after the tone.`,speechModel:s.speechModel??e.voice?.speechModel,speechTimeout:s.speechTimeout??e.voice?.speechTimeout??`auto`,timeoutSeconds:s.timeoutSeconds??e.voice?.timeoutSeconds,voice:s.voice??e.voice?.voice})}),POST(r.transcription,async(t,{send:n,waitUntil:i})=>{let a=await verifyInbound(t,e);if(a===null)return new Response(`unauthorized`,{status:401});let o=parseTwilioVoiceTranscription(a.params);return o?await isAllowed(o.from,e.allowFrom)?(i(dispatchVoiceTranscription({config:e,onVoiceTranscription:s,send:n,transcription:o})),sayTwilioResponse(e.voice?.acknowledgement??`Thanks. I'll follow up by text.`)):new Response(`forbidden`,{status:403}):gatherSpeechTwilioResponse({actionUrl:await buildActionUrl(t,e,r.transcription),language:e.voice?.language,prompt:e.voice?.prompt??`Please say your message after the tone.`,speechTimeout:e.voice?.speechTimeout??`auto`,timeoutSeconds:e.voice?.timeoutSeconds})})],async receive(t,{send:n}){let r=readString(t.target.phoneNumber);if(!r)throw Error(`twilioChannel().receive requires target.phoneNumber.`);let i=readString(t.target.from)??e.messaging?.from??null;return n(t.message,{auth:t.auth,continuationToken:twilioContinuationToken(r,i??void 0),state:{from:r,lastCallSid:null,lastMessageSid:null,to:i}})},events:l})}function rebuildTwilioContext(e,t,n){return{state:e,twilio:buildTwilioHandle({callSid:e.lastCallSid??void 0,config:n,from:e.from??``,to:e.to??void 0})}}function buildTwilioHandle(e){let t=e.config.api,n=e.config.credentials,r=e.config.messaging?.from??e.to,o=e.config.messaging?.messagingServiceSid,c=e.config.messaging?.statusCallbackUrl;return{callSid:e.callSid,from:e.from,to:e.to,request(e,r){return callTwilioApi({apiBaseUrl:t?.apiBaseUrl,body:r,credentials:n,fetch:t?.fetch,path:e})},sendMessage(i,s){return sendTwilioMessage({apiBaseUrl:t?.apiBaseUrl,body:i,credentials:n,fetch:t?.fetch,from:s?.from??r,messagingServiceSid:s?.messagingServiceSid??o,statusCallbackUrl:s?.statusCallbackUrl??c,to:s?.to??e.from})},updateCall(e,r){return updateTwilioCall({apiBaseUrl:t?.apiBaseUrl,callSid:e,credentials:n,fetch:t?.fetch,twiml:r})}}}function buildRoutes(e){let t=e.endsWith(`/`)?e.slice(0,-1):e;return{messages:`${t}/messages`,transcription:`${t}/voice/transcription`,voice:`${t}/voice`}}function assertAllowFromConfigured(e){if(e?.allowFrom===void 0)throw Error(`twilioChannel requires allowFrom. Use allowFrom: "*" to allow all numbers.`)}async function verifyInbound(e,t){try{return await verifyTwilioRequest(e,{authToken:t.credentials?.authToken,webhookUrl:t.webhookUrl})}catch(e){return log.warn(`twilio inbound verification failed`,{error:e}),null}}async function dispatchText(e){let{message:t}=e,n={twilio:buildTwilioHandle({callSid:void 0,config:e.config,from:t.from,to:t.to})},r;try{r=await e.onText(n,t)}catch(e){log.error(`text handler failed`,{error:e});return}if(r==null)return;let i=formatTwilioContextBlock({channel:`text`,from:t.from,messageSid:t.messageSid,to:t.to});try{await e.send({message:t.body,context:[i]},{auth:r.auth,continuationToken:twilioContinuationToken(t.from,t.to),state:{from:t.from,lastCallSid:null,lastMessageSid:t.messageSid??null,to:t.to??null}})}catch(e){log.error(`text delivery failed`,{error:e})}}async function acceptVoiceCall(e){let{call:t}=e,n={twilio:buildTwilioHandle({callSid:t.callSid,config:e.config,from:t.from,to:t.to})};try{return await e.onVoice(n,t)}catch(e){return log.error(`voice handler failed`,{error:e}),null}}async function dispatchVoiceTranscription(e){let{transcription:t}=e,n={twilio:buildTwilioHandle({callSid:t.callSid,config:e.config,from:t.from,to:t.to})},r;try{r=await e.onVoiceTranscription(n,t)}catch(e){log.error(`voice transcription handler failed`,{error:e});return}if(r==null)return;let i=formatTwilioContextBlock({callSid:t.callSid,channel:`voice`,from:t.from,to:t.to});try{await e.send({message:t.text,context:[i]},{auth:r.auth,continuationToken:twilioContinuationToken(t.from,t.to),state:{from:t.from,lastCallSid:t.callSid??null,lastMessageSid:null,to:t.to??null}})}catch(e){log.error(`voice transcription delivery failed`,{error:e})}}async function isAllowed(e,t){let n=typeof t==`function`?await t():t;return n===`*`?!0:typeof n==`string`?n===e:n.includes(e)}async function buildActionUrl(e,t,n){let r=typeof t.publicBaseUrl==`function`?await t.publicBaseUrl(e):t.publicBaseUrl;if(r)return new URL(n,ensureTrailingSlash(r)).toString();let i=new URL(e.url);return i.pathname=n,i.search=``,i.toString()}function ensureTrailingSlash(e){return e.endsWith(`/`)?e:`${e}/`}function readString(e){return typeof e==`string`&&e.length>0?e:void 0}export{twilioChannel};

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

@@ -1,6 +1,6 @@
 import type { FetchFileResult } from "#channel/adapter.js";
 import { CHANNEL_SENTINEL } from "#channel/compiled-channel.js";
-import type { TypedReceiveRoute } from "#channel/receive-args.js";
+import type { TypedReceiveTarget } from "#channel/receive-target.js";
 import type { SessionAuthContext } from "#channel/types.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
@@ -49,12 +49,12 @@ export interface ChannelEvents<TCtx = void> {
  * Input passed to a channel's `receive` callback when another channel or
  * schedule proactively routes a message to it.
  */
-export interface ReceiveInput<TReceiveArgs = Record<string, unknown>> {
+export interface ReceiveInput<TReceiveTarget = Record<string, unknown>> {
     readonly message: string;
-    readonly args: Readonly<TReceiveArgs>;
+    readonly target: Readonly<TReceiveTarget>;
     readonly auth: SessionAuthContext | null;
 }
-export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
     readonly state?: TState;
     /**
      * Builds the per-step channel context handed to `events` and
@@ -71,7 +71,7 @@ export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs
      */
     context?(state: NonNullable<TState>, session: SessionHandle): TCtx;
     readonly routes: readonly RouteDefinition<TState>[];
-    receive?(input: ReceiveInput<TReceiveArgs>, args: {
+    receive?(input: ReceiveInput<TReceiveTarget>, args: {
         send: SendFn<TState>;
     }): Promise<Session>;
     readonly events?: ChannelEvents<TCtx>;
@@ -108,16 +108,16 @@ export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs
      */
     readonly kindHint?: string;
 }
-export interface Channel<TState = undefined, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends TypedReceiveRoute<TReceiveArgs> {
+export interface Channel<TState = undefined, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends TypedReceiveTarget<TReceiveTarget> {
     readonly __kind: typeof CHANNEL_SENTINEL;
     readonly [CHANNEL_METADATA_TYPE]?: TMetadata;
     readonly routes: readonly {
         method: string;
         path: string;
     }[];
-    readonly receive?: (input: ReceiveInput<TReceiveArgs>, args: {
+    readonly receive?: (input: ReceiveInput<TReceiveTarget>, args: {
         send: SendFn<TState>;
     }) => Promise<Session>;
 }
 export type InferChannelMetadata<TChannel> = TChannel extends Channel<any, any, infer TMetadata> ? TMetadata : Record<string, unknown>;
-export declare function defineChannel<TState = undefined, TCtx = void, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>>(definition: ChannelDefinition<TState, TCtx, TReceiveArgs, TMetadata>): Channel<TState, TReceiveArgs, TMetadata>;
+export declare function defineChannel<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>>(definition: ChannelDefinition<TState, TCtx, TReceiveTarget, TMetadata>): Channel<TState, TReceiveTarget, TMetadata>;

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

@@ -1,7 +1,7 @@
 import type { CrossChannelReceiveFn } from "#channel/cross-channel-receive.js";
 import type { SessionAuthContext } from "#channel/types.js";
 import type { ExactDefinition } from "#public/definitions/exact.js";
-export type { InferReceiveArgs, TypedReceiveRoute } from "#channel/receive-args.js";
+export type { InferReceiveTarget, TypedReceiveTarget } from "#channel/receive-target.js";
 /**
  * Arguments handed to {@link ScheduleDefinition.run}. Tight subset of
  * `RouteHandlerArgs` — schedules can hand work off to a channel via
@@ -72,7 +72,7 @@ export type ScheduleDefinition = {
  *   async run({ receive, waitUntil, appAuth }) {
  *     waitUntil(receive(slack, {
  *       message: "Post the daily standup summary.",
- *       args: { channelId: "C0123ABC" },
+ *       target: { channelId: "C0123ABC" },
  *       auth: appAuth,
  *     }));
  *   },

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

@@ -40,36 +40,6 @@ export interface NeedsApprovalContext<TInput = Record<string, unknown>> {
     readonly toolName: string;
 }
 export type { ToolModelOutput } from "#shared/tool-definition.js";
-/**
- * Result returned from a {@link ToolRetentionPolicy} function.
- *
- * Always a named object — the field name carries the intent so the
- * pruner and readers of the policy can't confuse it with a raw output
- * replacement. Room exists to grow the object (token hints, placeholder
- * overrides) without breaking existing policies.
- */
-export interface RetentionSummary {
-    /**
-     * Compact text that replaces the original tool-result output in
-     * conversation history. Should be short and information-dense; the
-     * model reads it as prose, not as structured data.
-     */
-    readonly summary: string;
-}
-/**
- * Between-step retention policy for a tool's results.
- *
- * - `"auto"` (default): the pruning system replaces old results with
- *   a fixed placeholder describing that the result was dropped.
- * - `"keep"`: the pruning system never replaces results from this tool.
- * - `(output) => RetentionSummary`: the pruning system calls this
- *   function with the original tool output and substitutes the
- *   returned `summary` text in place of the full result.
- *
- * The function runs synchronously during reactive pruning and must be
- * pure — no external I/O.
- */
-export type ToolRetentionPolicy<TOutput = unknown> = "auto" | "keep" | ((output: TOutput) => RetentionSummary);
 /**
  * Authored tool context. Passed as the last argument to
  * {@link ToolDefinition.execute}.
@@ -97,14 +67,6 @@ export type ToolDefinition<TInput = unknown, TOutput = unknown> = PublicToolDefi
      * - {@link once} — require approval only the first time per session
      */
     needsApproval?: (ctx: NeedsApprovalContext<ApprovalContextInput<TInput>>) => boolean;
-    /**
-     * Optional between-step retention policy for this tool's results.
-     *
-     * The function form receives the awaited return value of
-     * {@link execute} — strongly typed as `TOutput`. See
-     * {@link ToolRetentionPolicy}.
-     */
-    retentionPolicy?: ToolRetentionPolicy<TOutput>;
     /**
      * Optional projection that controls what the model sees as the tool
      * result. Receives the full `TOutput` from {@link execute} and returns
@@ -141,7 +103,6 @@ export declare function defineTool<TSchema extends StandardJSONSchemaV1<unknown,
     inputSchema: TSchema;
     execute(input: StandardJSONSchemaV1.InferOutput<TSchema>, ctx: ToolContext): Promise<TOutput> | TOutput;
     needsApproval?: ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, unknown>["needsApproval"];
-    retentionPolicy?: ToolDefinition<unknown, TOutput>["retentionPolicy"];
     toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
     onCompact?: ToolDefinition<unknown, unknown>["onCompact"];
 }): ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>;
@@ -150,7 +111,6 @@ export declare function defineTool<TOutput>(definition: {
     inputSchema: JsonObject;
     execute(input: Record<string, unknown>, ctx: ToolContext): Promise<TOutput> | TOutput;
     needsApproval?: ToolDefinition<Record<string, unknown>, unknown>["needsApproval"];
-    retentionPolicy?: ToolDefinition<unknown, TOutput>["retentionPolicy"];
     toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
     onCompact?: ToolDefinition<unknown, unknown>["onCompact"];
 }): ToolDefinition<Record<string, unknown>, TOutput>;

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

@@ -5,6 +5,7 @@ import type { ExactDefinition } from "#public/definitions/exact.js";
 import type { ModelMessage, SystemModelMessage } from "ai";
 import type { SessionAuthContext, SessionParent } from "#channel/types.js";
 import type { Channel } from "#public/definitions/defineChannel.js";
+import type { JsonObject } from "#shared/json.js";
 /**
  * Context passed to the {@link InstrumentationDefinition.setup} callback.
  */
@@ -18,12 +19,12 @@ export interface InstrumentationSetupContext {
     readonly agentName: string;
 }
 /**
- * User-authored metadata attached to AI SDK telemetry spans.
+ * User-authored runtime context values attached to AI SDK telemetry spans.
  *
- * Keys beginning with `ash.` are reserved for framework-owned metadata
+ * Keys beginning with `ash.` are reserved for framework-owned context
  * and are ignored when returned from authored instrumentation.
  */
-export type InstrumentationMetadata = Readonly<Record<string, string>>;
+export type InstrumentationRuntimeContext = JsonObject;
 /**
  * Base channel metadata shape used by framework channel kinds.
  */
@@ -91,12 +92,12 @@ export interface InstrumentationModelInput {
     readonly messages: readonly ModelMessage[];
 }
 /**
- * Input passed to `metadata["step.started"]`.
+ * Input passed to `events["step.started"]`.
  *
  * The callback runs after Ash has built the final model input for this
  * model-call attempt and before the AI SDK model call is constructed.
  */
-export interface InstrumentationStepStartedMetadataInput {
+export interface InstrumentationStepStartedEventInput {
     readonly channel: InstrumentationChannel;
     readonly modelInput: InstrumentationModelInput;
     readonly session: InstrumentationSession;
@@ -104,14 +105,23 @@ export interface InstrumentationStepStartedMetadataInput {
     readonly turn: InstrumentationTurn;
 }
 /**
- * Metadata hooks accepted by {@link defineInstrumentation}.
+ * Result returned by `events["step.started"]`.
  */
-export interface InstrumentationMetadataConfig {
+export interface InstrumentationStepStartedEventResult {
     /**
-     * Per-attempt metadata resolved before the model call so child spans
+     * Additional runtime context merged into AI SDK telemetry spans.
+     */
+    readonly runtimeContext: InstrumentationRuntimeContext;
+}
+/**
+ * Event hooks accepted by {@link defineInstrumentation}.
+ */
+export interface InstrumentationEvents {
+    /**
+     * Per-attempt runtime context resolved before the model call so child spans
      * created by the AI SDK inherit the returned values.
      */
-    readonly "step.started"?: (input: InstrumentationStepStartedMetadataInput) => InstrumentationMetadata;
+    readonly "step.started"?: (input: InstrumentationStepStartedEventInput) => InstrumentationStepStartedEventResult | undefined;
 }
 /**
  * Authored instrumentation settings accepted by `defineInstrumentation`.
@@ -127,9 +137,9 @@ export interface InstrumentationDefinition {
      */
     readonly functionId?: string;
     /**
-     * Additional metadata merged into AI SDK telemetry spans.
+     * Instrumentation event hooks.
      */
-    readonly metadata?: InstrumentationMetadataConfig;
+    readonly events?: InstrumentationEvents;
     /**
      * Whether to record full model inputs in telemetry spans.
      *

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

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

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

@@ -1,7 +1,7 @@
 /**
  * Tool authoring helpers for `agent/tools/*.ts` files.
  */
-export { type CompactionInput, type CompactionHookResult, type DisabledToolSentinel, defineDynamic, defineTool, disableTool, isDisabledToolSentinel, type NeedsApprovalContext, type RetentionSummary, type ToolDefinition, type ToolContext, type ToolModelOutput, type ToolRetentionPolicy, } from "#public/definitions/tool.js";
+export { type CompactionInput, type CompactionHookResult, type DisabledToolSentinel, defineDynamic, defineTool, disableTool, isDisabledToolSentinel, type NeedsApprovalContext, type ToolDefinition, type ToolContext, type ToolModelOutput, } from "#public/definitions/tool.js";
 export type { DynamicToolEntry, DynamicEvents, DynamicToolEvents, DynamicResolveContext, DynamicSentinel, DynamicToolSet, DynamicToolResult, } from "#shared/dynamic-tool-definition.js";
 export { type SessionContext } from "#public/definitions/callback-context.js";
 export { toolResultFrom, type MatchedConnectionResult, type MatchedToolResult, type ToolResultFromFn, } from "#public/tool-result-narrowing.js";

package/dist/src/runtime/framework-tools/skill.js

@@ -1 +1 @@
-import{SandboxKey}from"#context/keys.js";import{loadContext}from"#context/container.js";import{loadSkillFromSandbox}from"#runtime/skills/sandbox-access.js";async function executeLoadSkillTool(t){let n=loadContext().get(SandboxKey);if(n===void 0)throw Error(`The load_skill tool requires sandbox access on the runtime context. Ensure the step is running inside a managed runtime context with sandbox support.`);let{skill:r}=t;return await loadSkillFromSandbox(n,r)}const SKILL_TOOL_DEFINITION={description:[`Load the full instructions for one available skill by name or id.`,`Use this tool when the request clearly matches a listed skill description or when the user explicitly asks for that skill.`,`Loading adds the skill instructions to the current turn.`,`Choose the "skill" value from the Available skills block.`].join(` `),execute:e=>executeLoadSkillTool(e),inputSchema:{additionalProperties:!1,properties:{skill:{description:`Available skill name or id.`,type:`string`}},required:[`skill`],type:`object`},logicalPath:`ash:framework/load-skill`,name:`load_skill`,retentionPolicy:`keep`,sourceId:`ash:load-skill-tool`,sourceKind:`module`};export{SKILL_TOOL_DEFINITION};
+import{SandboxKey}from"#context/keys.js";import{loadContext}from"#context/container.js";import{loadSkillFromSandbox}from"#runtime/skills/sandbox-access.js";async function executeLoadSkillTool(t){let n=loadContext().get(SandboxKey);if(n===void 0)throw Error(`The load_skill tool requires sandbox access on the runtime context. Ensure the step is running inside a managed runtime context with sandbox support.`);let{skill:r}=t;return await loadSkillFromSandbox(n,r)}const SKILL_TOOL_DEFINITION={description:[`Load the full instructions for one available skill by name or id.`,`Use this tool when the request clearly matches a listed skill description or when the user explicitly asks for that skill.`,`Loading adds the skill instructions to the current turn.`,`Choose the "skill" value from the Available skills block.`].join(` `),execute:e=>executeLoadSkillTool(e),inputSchema:{additionalProperties:!1,properties:{skill:{description:`Available skill name or id.`,type:`string`}},required:[`skill`],type:`object`},logicalPath:`ash:framework/load-skill`,name:`load_skill`,sourceId:`ash:load-skill-tool`,sourceKind:`module`};export{SKILL_TOOL_DEFINITION};

package/dist/src/runtime/resolve-tool.d.ts

@@ -5,7 +5,7 @@ import type { ResolvedToolDefinition } from "#runtime/types.js";
  * Resolves one compiled authored tool into a runtime-owned definition
  * with live callbacks reattached from the authored module.
  *
- * Optional hooks (`onCompact`, `needsApproval`, `retentionPolicy`,
+ * Optional hooks (`onCompact`, `needsApproval`,
  * plus an optional Standard Schema `inputSchema`) are extracted when
  * declared and validated to have the expected shape; any type mismatch
  * raises a {@link ResolveAgentError} so typos surface at resolve time

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

@@ -1 +1 @@
-import{expectFunction,expectObjectRecord}from"#internal/authored-module.js";import{toErrorMessage}from"#shared/errors.js";import{ResolveAgentError,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{registerDefinitionSource,stampDefinitionKey}from"#public/tool-result-narrowing.js";async function resolveToolDefinition(a,o,s){try{let n=expectObjectRecord(await loadResolvedModuleExport({definition:a,kindLabel:`tool`,moduleMap:o,nodeId:s}),describe(a,`to return an object`)),r={kind:`tool`,logicalPath:a.logicalPath,name:a.name},c=`tool-source:${a.sourceId}`;stampDefinitionKey(n,c),registerDefinitionSource(c,r),registerDefinitionSource(`tool:${n.description}`,r);let l=expectFunction(n.execute,describe(a,`to provide an execute function`));return{description:a.description,execute:l,exportName:a.exportName,inputSchema:a.inputSchema,logicalPath:a.logicalPath,name:a.name,sourceId:a.sourceId,sourceKind:`module`,...extractOptionalHooks(n,a)}}catch(e){throw e instanceof ResolveAgentError?e:new ResolveAgentError(`Failed to attach the tool execute function from "${a.logicalPath}": ${toErrorMessage(e)}`,{logicalPath:a.logicalPath,sourceId:a.sourceId})}}function extractOptionalHooks(t,n){let r={};t.onCompact!==void 0&&(r.onCompact=expectFunction(t.onCompact,describe(n,`to provide an onCompact function`))),t.needsApproval!==void 0&&(r.needsApproval=expectFunction(t.needsApproval,describe(n,`to provide a needsApproval function`)));let i=extractRetentionPolicy(t,n);return i!==void 0&&(r.retentionPolicy=i),t.toModelOutput!==void 0&&(r.toModelOutput=expectFunction(t.toModelOutput,describe(n,`to provide a toModelOutput function`))),t.inputSchema!==void 0&&isFlexibleSchema(t.inputSchema)&&(r.inputStandardSchema=t.inputSchema),r}function extractRetentionPolicy(e,t){let n=e.retentionPolicy;if(n!==void 0){if(n===`auto`||n===`keep`||typeof n==`function`)return n;throw new ResolveAgentError(describe(t,`to set retentionPolicy to "auto", "keep", or a function`),{logicalPath:t.logicalPath,sourceId:t.sourceId})}}function describe(e,t){return`Expected the tool export "${e.exportName??`default`}" from "${e.logicalPath}" ${t}.`}function isFlexibleSchema(e){return typeof e==`object`&&!!e&&`~standard`in e&&typeof e[`~standard`]==`object`}export{resolveToolDefinition};
+import{expectFunction,expectObjectRecord}from"#internal/authored-module.js";import{toErrorMessage}from"#shared/errors.js";import{ResolveAgentError,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{registerDefinitionSource,stampDefinitionKey}from"#public/tool-result-narrowing.js";async function resolveToolDefinition(i,a,o){try{let n=expectObjectRecord(await loadResolvedModuleExport({definition:i,kindLabel:`tool`,moduleMap:a,nodeId:o}),describe(i,`to return an object`)),r={kind:`tool`,logicalPath:i.logicalPath,name:i.name},s=`tool-source:${i.sourceId}`;stampDefinitionKey(n,s),registerDefinitionSource(s,r),registerDefinitionSource(`tool:${n.description}`,r);let c=expectFunction(n.execute,describe(i,`to provide an execute function`));return{description:i.description,execute:c,exportName:i.exportName,inputSchema:i.inputSchema,logicalPath:i.logicalPath,name:i.name,sourceId:i.sourceId,sourceKind:`module`,...extractOptionalHooks(n,i)}}catch(e){throw e instanceof ResolveAgentError?e:new ResolveAgentError(`Failed to attach the tool execute function from "${i.logicalPath}": ${toErrorMessage(e)}`,{logicalPath:i.logicalPath,sourceId:i.sourceId})}}function extractOptionalHooks(t,n){let r={};return t.onCompact!==void 0&&(r.onCompact=expectFunction(t.onCompact,describe(n,`to provide an onCompact function`))),t.needsApproval!==void 0&&(r.needsApproval=expectFunction(t.needsApproval,describe(n,`to provide a needsApproval function`))),t.toModelOutput!==void 0&&(r.toModelOutput=expectFunction(t.toModelOutput,describe(n,`to provide a toModelOutput function`))),t.inputSchema!==void 0&&isFlexibleSchema(t.inputSchema)&&(r.inputStandardSchema=t.inputSchema),r}function describe(e,t){return`Expected the tool export "${e.exportName??`default`}" from "${e.logicalPath}" ${t}.`}function isFlexibleSchema(e){return typeof e==`object`&&!!e&&`~standard`in e&&typeof e[`~standard`]==`object`}export{resolveToolDefinition};

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

@@ -7,7 +7,7 @@ import type { ChannelMethod, RouteContext } from "#public/definitions/channel.js
 import type { RouteHandler } from "#channel/routes.js";
 import type { OutboundAuthFn } from "#public/agents/auth.js";
 import type { StreamEventHook } from "#public/definitions/hook.js";
-import type { CompactionInput, CompactionHookResult, NeedsApprovalContext, ToolModelOutput, ToolRetentionPolicy } from "#public/definitions/tool.js";
+import type { CompactionInput, CompactionHookResult, NeedsApprovalContext, ToolModelOutput } from "#public/definitions/tool.js";
 import type { AuthorizationDefinition, HeadersDefinition, ToolFilterDefinition } from "#runtime/connections/types.js";
 import type { CompiledWorkspaceResourceRoot } from "#compiler/manifest.js";
 import type { WorkspaceRuntimeSpec } from "#runtime/workspace/types.js";
@@ -125,14 +125,6 @@ export type ResolvedToolDefinition = Readonly<Optional<InternalToolDefinitionWit
      * than blanket.
      */
     readonly approvalKey?: (toolInput: Readonly<Record<string, unknown>>) => string;
-    /**
-     * Optional retention policy for old results of this tool. Controls the
-     * behavior of the reactive pruning system when this tool's results age
-     * outside the protection window. See {@link ToolRetentionPolicy}.
-     *
-     * When omitted, the default `"auto"` policy applies.
-     */
-    readonly retentionPolicy?: ToolRetentionPolicy;
     /**
      * Optional compaction hook. The execution layer invokes this for every
      * resolved tool that declares it after the harness compacts message

package/package.json

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

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

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

package/dist/src/harness/instrumentation-metadata.js

@@ -1 +0,0 @@
-import{createLogger,formatError}from"#internal/logging.js";import{normalizeInstrumentationChannelKind,resolveInstrumentationProjection}from"#internal/instrumentation.js";import{AuthKey,ChannelInstrumentationKey,InitiatorAuthKey,ParentSessionKey}from"#context/keys.js";import{parseJsonValue}from"#shared/json.js";import{contextStorage}from"#context/container.js";const log=createLogger(`harness.instrumentation-metadata`);function buildTelemetryRuntimeContext(e){if(e.authored===void 0)return;let t=resolveStepStartedMetadata(e),r=contextStorage.getStore()?.get(ChannelInstrumentationKey);return{...t,"ash.channel.kind":normalizeInstrumentationChannelKind(r?.kind),"ash.environment":e.environment,"ash.session.id":e.session.sessionId,"ash.step.index":String(e.emissionState.stepIndex),"ash.turn.id":e.emissionState.turnId,"ash.turn.sequence":String(e.emissionState.sequence),"ash.version":e.ashVersion}}function buildInstrumentationStepStartedInput(e){let t=contextStorage.getStore(),r=t?.get(ChannelInstrumentationKey);return{channel:{kind:normalizeInstrumentationChannelKind(r?.kind),metadata:snapshotForInstrumentation(r?.metadata,`channel.metadata`)??{}},modelInput:snapshotForInstrumentation(e.modelInput,`modelInput`)??{instructions:void 0,messages:[]},session:{auth:projectSessionAuth(t),id:e.session.sessionId,parent:snapshotForInstrumentation(t?.get(ParentSessionKey),`session.parent`)},step:{index:e.emissionState.stepIndex},turn:{id:e.emissionState.turnId,sequence:e.emissionState.sequence}}}function filterAuthoredMetadata(e,t){let n={};for(let[r,i]of Object.entries(e)){if(r.startsWith(`ash.`)){log.warn(`ignoring reserved instrumentation metadata key`,{key:r,source:t});continue}if(typeof i!=`string`){log.warn(`ignoring non-string instrumentation metadata value`,{key:r,source:t,valueType:typeof i});continue}n[r]=i}return Object.keys(n).length>0?n:void 0}function resolveStepStartedMetadata(e){let t=e.authored?.metadata?.[`step.started`];if(t===void 0)return;let n=`metadata["step.started"]`,i=resolveInstrumentationProjection({invoke:()=>t(buildInstrumentationStepStartedInput(e)),log,source:n});return i===void 0?void 0:filterAuthoredMetadata(i,n)}function projectSessionAuth(e){let t=e?.get(AuthKey)??null,n=e?.get(InitiatorAuthKey)??t;return{current:snapshotForInstrumentation(t,`session.auth.current`)??null,initiator:snapshotForInstrumentation(n,`session.auth.initiator`)??null}}function snapshotForInstrumentation(e,n){if(e!==void 0)try{return parseJsonValue(e)}catch(e){log.warn(`dropping non-serializable instrumentation snapshot`,{error:formatError(e),source:n});return}}export{buildTelemetryRuntimeContext};