experimental-ash 0.42.0 → 0.44.0

package/dist/src/public/channels/telegram/telegramChannel.js

@@ -1 +1 @@
-import{createLogger,logError}from"#internal/logging.js";import{isCompiledChannel}from"#channel/compiled-channel.js";import{parseJsonObject}from"#shared/json.js";import{defaultDeliverResult}from"#channel/adapter.js";import{mergeUploadPolicy}from"#public/channels/upload-policy.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{answerTelegramCallbackQuery,callTelegramApi,editTelegramMessageReplyMarkup,sendTelegramChatAction,sendTelegramMessage,splitTelegramMessageText,telegramContinuationToken}from"#public/channels/telegram/api.js";import{TELEGRAM_HITL_CALLBACK_PREFIX,isTelegramSyntheticResponse,resolveTelegramInputResponses,telegramCallbackInputResponse,telegramReplyInputResponse}from"#public/channels/telegram/hitl.js";import{parseTelegramUpdate,prependTelegramContext}from"#public/channels/telegram/inbound.js";import{buildTelegramTurnMessage,collectTelegramFileParts,createTelegramFetchFile}from"#public/channels/telegram/attachments.js";import{defaultEvents,defaultOnMessage}from"#public/channels/telegram/defaults.js";import{verifyTelegramRequest}from"#public/channels/telegram/verify.js";const log=createLogger(`telegram.channel`);function telegramChannel(e={}){let t=mergeUploadPolicy(e.uploadPolicy),n=e.onMessage??defaultOnMessage,i={...defaultEvents,...e.events},c=defineChannel({kindHint:`telegram`,state:initialTelegramState(e.botUsername),fetchFile:createTelegramFetchFile({api:e.api,credentials:e.credentials,policy:t}),context(t,n){return rebuildTelegramContext(t,n,e)},routes:[POST(e.route??`/ash/v1/telegram`,async(i,{send:a,waitUntil:o})=>{let s=await verifyInbound(i,e.credentials);if(s===null)return new Response(`unauthorized`,{status:401});let c;try{c=parseJsonObject(JSON.parse(s))}catch(e){return log.warn(`inbound Telegram body is not valid JSON`,{error:e}),new Response(`ok`)}let l=parseTelegramUpdate(c);return l===null?new Response(`ok`):l.kind===`message`?(o(dispatchMessage({config:e,message:l.message,onMessage:n,send:a,uploadPolicy:t})),new Response(`ok`)):(o(dispatchCallbackQuery({config:e,query:l.callbackQuery,send:a})),new Response(`ok`))})],async receive(t,{send:n}){let r=t.args,i=readChatId(r.chatId);if(i===void 0)throw Error(`telegramChannel().receive requires args.chatId.`);let a=typeof r.messageThreadId==`number`?r.messageThreadId:void 0,o=readOptionalString(r.conversationId),s=r.initialMessage;if(s!==void 0&&o!==void 0)throw Error("telegramChannel().receive: `conversationId` and `initialMessage` are mutually exclusive.");let c=o;return s!==void 0&&(c=(await buildTelegramHandle({config:e,state:{...initialTelegramState(e.botUsername),chatId:i,messageThreadId:a??null}}).sendMessage(s)).id||void 0),n(t.message,{auth:t.auth,continuationToken:telegramContinuationToken({chatId:i,conversationId:c,messageThreadId:a}),state:{...initialTelegramState(e.botUsername),chatId:i,conversationId:c??null,messageThreadId:a??null}})},events:i});return attachTelegramDeliver(c),c}function rebuildTelegramContext(e,t,n){return{state:e,telegram:buildTelegramHandle({config:n,session:t,state:e})}}function buildTelegramHandle(e){let n=e.config.api,r=e.state,i=e.config.credentials;function anchor(t){!t.id||r.chatType===`private`||(r.conversationId=t.id,r.chatId&&e.session?.setContinuationToken(telegramContinuationToken({chatId:r.chatId,conversationId:t.id,messageThreadId:r.messageThreadId??void 0})))}async function sendOne(e){let t=r.chatId??``;if(!t)throw Error(`telegramChannel: missing chat id for outbound message.`);let a=await sendTelegramMessage({apiBaseUrl:n?.apiBaseUrl,body:{...e,message_thread_id:e.message_thread_id??r.messageThreadId??void 0},credentials:i,fetch:n?.fetch,fileBaseUrl:n?.fileBaseUrl,chatId:t});return anchor(a),a}return{botUsername:r.botUsername??e.config.botUsername,chatId:r.chatId??``,chatType:r.chatType??void 0,conversationId:r.conversationId??void 0,messageThreadId:r.messageThreadId??void 0,answerCallbackQuery(e){return answerTelegramCallbackQuery({apiBaseUrl:n?.apiBaseUrl,callbackQueryId:e.callbackQueryId,credentials:i,fetch:n?.fetch,showAlert:e.showAlert,text:e.text})},editMessageReplyMarkup(e){let t=r.chatId??``;if(!t)throw Error(`telegramChannel: missing chat id for reply-markup edit.`);return editTelegramMessageReplyMarkup({apiBaseUrl:n?.apiBaseUrl,chatId:t,credentials:i,fetch:n?.fetch,messageId:e.messageId,replyMarkup:e.replyMarkup})},post(e){return postTelegramMessage(e,sendOne)},request(e,t){return callTelegramApi({apiBaseUrl:n?.apiBaseUrl,body:t,botToken:i?.botToken,fetch:n?.fetch,method:e})},sendMessage(e){return postTelegramMessage(e,sendOne)},async startTyping(e=`typing`){let a=r.chatId??``;if(a)try{await sendTelegramChatAction({action:e,apiBaseUrl:n?.apiBaseUrl,chatId:a,credentials:i,fetch:n?.fetch,messageThreadId:r.messageThreadId??void 0})}catch(e){logError(log,`Telegram typing indicator failed — swallowed`,e,{chatId:a})}}}}async function postTelegramMessage(e,t){let n=typeof e==`string`?{text:e}:e,r=splitTelegramMessageText(n.text),i;for(let[e,a]of r.entries()){let r=await t(e===0?{...n,text:a}:{text:a});i===void 0&&(i=r)}return i??{id:``,raw:null}}async function verifyInbound(e,t){try{return await verifyTelegramRequest(e,{secretToken:t?.webhookVerifier?void 0:t?.webhookSecretToken,webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`telegram inbound verification failed`,{error:e}),null}}async function dispatchMessage(e){if(e.message.from?.isBot===!0)return;let t=stateFromMessage(e.message,e.config),n={telegram:buildTelegramHandle({config:e.config,state:t})},r;try{r=await e.onMessage(n,e.message)}catch(e){log.error(`message handler failed`,{error:e});return}if(r==null)return;let i=collectTelegramFileParts(e.message.attachments,e.uploadPolicy),a=prependTelegramContext(buildTelegramTurnMessage(e.message,i),{botUsername:e.config.botUsername,chatId:e.message.chat.id,chatTitle:e.message.chat.title,chatType:e.message.chat.type,messageId:e.message.messageId,messageThreadId:e.message.messageThreadId,userId:e.message.from?.id,username:e.message.from?.username}),o=e.message.text||e.message.caption,s=e.message.replyToMessage?.from?.isBot===!0&&o.trim().length>0?[telegramReplyInputResponse({messageId:e.message.replyToMessage.messageId,text:o})]:void 0;try{await e.send({inputResponses:s,message:a,modelContext:r.modelContext},{auth:r.auth,continuationToken:continuationTokenFromState(t),state:t})}catch(e){log.error(`message delivery failed`,{error:e})}}async function dispatchCallbackQuery(e){let t=stateFromCallbackQuery(e.query,e.config),n={telegram:buildTelegramHandle({config:e.config,state:t})};if(e.query.data?.startsWith(TELEGRAM_HITL_CALLBACK_PREFIX)===!0){try{await n.telegram.answerCallbackQuery({callbackQueryId:e.query.id,text:`Answer received.`})}catch(e){log.warn(`Telegram callback-query acknowledgement failed`,{error:e})}if(!e.query.message||!t.chatId)return;try{await e.send({inputResponses:[telegramCallbackInputResponse(e.query.data)]},{auth:null,continuationToken:continuationTokenFromState(t),state:t})}catch(e){log.error(`callback query delivery failed`,{error:e})}return}if(e.config.onCallbackQuery!==void 0){try{await e.config.onCallbackQuery(n,e.query)}catch(e){log.error(`custom callback-query handler failed`,{error:e})}return}try{await n.telegram.answerCallbackQuery({callbackQueryId:e.query.id,text:`Unsupported action.`})}catch(e){log.warn(`Telegram unsupported callback-query acknowledgement failed`,{error:e})}}function attachTelegramDeliver(e){if(!isCompiledChannel(e))return;let t=e.adapter;t.deliver=(e,t)=>{let n=e.inputResponses??[];if(n.some(isTelegramSyntheticResponse)){let r=resolveTelegramInputResponses(t.state,n);return r.length>0?{inputResponses:r,modelContext:e.modelContext}:e.message===void 0?void 0:{message:e.message,modelContext:e.modelContext}}return defaultDeliverResult(e)}}function stateFromMessage(e,t){let n=e.chat.type===`private`;return{...initialTelegramState(t.botUsername),chatId:e.chat.id,chatType:e.chat.type,conversationId:n?null:conversationIdForMessage(e),messageThreadId:e.messageThreadId??null,triggeringUserId:e.from?.id??null}}function stateFromCallbackQuery(e,t){let n=e.message;if(!n)return{...initialTelegramState(t.botUsername),triggeringUserId:e.from.id};let r=n.chat.type===`private`;return{...initialTelegramState(t.botUsername),chatId:n.chat.id,chatType:n.chat.type,conversationId:r?null:n.messageId,messageThreadId:n.messageThreadId??null,triggeringUserId:e.from.id}}function conversationIdForMessage(e){return e.replyToMessage?.from?.isBot===!0?e.replyToMessage.messageId:e.messageId}function continuationTokenFromState(e){return telegramContinuationToken({chatId:e.chatId??``,conversationId:e.chatType===`private`?void 0:e.conversationId??void 0,messageThreadId:e.messageThreadId??void 0})}function initialTelegramState(e){return{botUsername:e??null,chatId:null,chatType:null,conversationId:null,hitlCallbacks:{},messageThreadId:null,nextHitlCallbackId:0,pendingFreeformReplies:{},triggeringUserId:null}}function readChatId(e){if(typeof e==`string`&&e.length>0)return e;if(typeof e==`number`&&Number.isFinite(e))return String(e)}function readOptionalString(e){if(typeof e==`string`&&e.length>0)return e;if(typeof e==`number`&&Number.isFinite(e))return String(e)}export{telegramChannel};
+import{createLogger,logError}from"#internal/logging.js";import{isCompiledChannel}from"#channel/compiled-channel.js";import{defaultDeliverResult}from"#channel/adapter.js";import{parseJsonObject}from"#shared/json.js";import{mergeUploadPolicy}from"#public/channels/upload-policy.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{answerTelegramCallbackQuery,callTelegramApi,editTelegramMessageReplyMarkup,sendTelegramChatAction,sendTelegramMessage,splitTelegramMessageText,telegramContinuationToken}from"#public/channels/telegram/api.js";import{TELEGRAM_HITL_CALLBACK_PREFIX,isTelegramSyntheticResponse,resolveTelegramInputResponses,telegramCallbackInputResponse,telegramReplyInputResponse}from"#public/channels/telegram/hitl.js";import{parseTelegramUpdate,prependTelegramContext}from"#public/channels/telegram/inbound.js";import{buildTelegramTurnMessage,collectTelegramFileParts,createTelegramFetchFile}from"#public/channels/telegram/attachments.js";import{defaultEvents,defaultOnMessage}from"#public/channels/telegram/defaults.js";import{verifyTelegramRequest}from"#public/channels/telegram/verify.js";const log=createLogger(`telegram.channel`);function telegramChannel(e={}){let t=mergeUploadPolicy(e.uploadPolicy),n=e.onMessage??defaultOnMessage,r={...defaultEvents,...e.events},c=defineChannel({kindHint:`telegram`,state:initialTelegramState(e.botUsername),fetchFile:createTelegramFetchFile({api:e.api,credentials:e.credentials,policy:t}),context(t,n){return rebuildTelegramContext(t,n,e)},routes:[POST(e.route??`/ash/v1/telegram`,async(r,{send:a,waitUntil:o})=>{let s=await verifyInbound(r,e.credentials);if(s===null)return new Response(`unauthorized`,{status:401});let c;try{c=parseJsonObject(JSON.parse(s))}catch(e){return log.warn(`inbound Telegram body is not valid JSON`,{error:e}),new Response(`ok`)}let l=parseTelegramUpdate(c);return l===null?new Response(`ok`):l.kind===`message`?(o(dispatchMessage({config:e,message:l.message,onMessage:n,send:a,uploadPolicy:t})),new Response(`ok`)):(o(dispatchCallbackQuery({config:e,query:l.callbackQuery,send:a})),new Response(`ok`))})],async receive(t,{send:n}){let r=t.args,i=readChatId(r.chatId);if(i===void 0)throw Error(`telegramChannel().receive requires args.chatId.`);let a=typeof r.messageThreadId==`number`?r.messageThreadId:void 0,o=readOptionalString(r.conversationId),s=r.initialMessage;if(s!==void 0&&o!==void 0)throw Error("telegramChannel().receive: `conversationId` and `initialMessage` are mutually exclusive.");let c=o;return s!==void 0&&(c=(await buildTelegramHandle({config:e,state:{...initialTelegramState(e.botUsername),chatId:i,messageThreadId:a??null}}).sendMessage(s)).id||void 0),n(t.message,{auth:t.auth,continuationToken:telegramContinuationToken({chatId:i,conversationId:c,messageThreadId:a}),state:{...initialTelegramState(e.botUsername),chatId:i,conversationId:c??null,messageThreadId:a??null}})},events:r});return attachTelegramDeliver(c),c}function rebuildTelegramContext(e,t,n){return{state:e,telegram:buildTelegramHandle({config:n,session:t,state:e})}}function buildTelegramHandle(e){let n=e.config.api,r=e.state,i=e.config.credentials;function anchor(t){!t.id||r.chatType===`private`||(r.conversationId=t.id,r.chatId&&e.session?.setContinuationToken(telegramContinuationToken({chatId:r.chatId,conversationId:t.id,messageThreadId:r.messageThreadId??void 0})))}async function sendOne(e){let t=r.chatId??``;if(!t)throw Error(`telegramChannel: missing chat id for outbound message.`);let a=await sendTelegramMessage({apiBaseUrl:n?.apiBaseUrl,body:{...e,message_thread_id:e.message_thread_id??r.messageThreadId??void 0},credentials:i,fetch:n?.fetch,fileBaseUrl:n?.fileBaseUrl,chatId:t});return anchor(a),a}return{botUsername:r.botUsername??e.config.botUsername,chatId:r.chatId??``,chatType:r.chatType??void 0,conversationId:r.conversationId??void 0,messageThreadId:r.messageThreadId??void 0,answerCallbackQuery(e){return answerTelegramCallbackQuery({apiBaseUrl:n?.apiBaseUrl,callbackQueryId:e.callbackQueryId,credentials:i,fetch:n?.fetch,showAlert:e.showAlert,text:e.text})},editMessageReplyMarkup(e){let t=r.chatId??``;if(!t)throw Error(`telegramChannel: missing chat id for reply-markup edit.`);return editTelegramMessageReplyMarkup({apiBaseUrl:n?.apiBaseUrl,chatId:t,credentials:i,fetch:n?.fetch,messageId:e.messageId,replyMarkup:e.replyMarkup})},post(e){return postTelegramMessage(e,sendOne)},request(e,t){return callTelegramApi({apiBaseUrl:n?.apiBaseUrl,body:t,botToken:i?.botToken,fetch:n?.fetch,method:e})},sendMessage(e){return postTelegramMessage(e,sendOne)},async startTyping(e=`typing`){let a=r.chatId??``;if(a)try{await sendTelegramChatAction({action:e,apiBaseUrl:n?.apiBaseUrl,chatId:a,credentials:i,fetch:n?.fetch,messageThreadId:r.messageThreadId??void 0})}catch(e){logError(log,`Telegram typing indicator failed — swallowed`,e,{chatId:a})}}}}async function postTelegramMessage(e,t){let n=typeof e==`string`?{text:e}:e,r=splitTelegramMessageText(n.text),i;for(let[e,a]of r.entries()){let r=await t(e===0?{...n,text:a}:{text:a});i===void 0&&(i=r)}return i??{id:``,raw:null}}async function verifyInbound(e,t){try{return await verifyTelegramRequest(e,{secretToken:t?.webhookVerifier?void 0:t?.webhookSecretToken,webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`telegram inbound verification failed`,{error:e}),null}}async function dispatchMessage(e){if(e.message.from?.isBot===!0)return;let t=stateFromMessage(e.message,e.config),n={telegram:buildTelegramHandle({config:e.config,state:t})},r;try{r=await e.onMessage(n,e.message)}catch(e){log.error(`message handler failed`,{error:e});return}if(r==null)return;let i=collectTelegramFileParts(e.message.attachments,e.uploadPolicy),a=prependTelegramContext(buildTelegramTurnMessage(e.message,i),{botUsername:e.config.botUsername,chatId:e.message.chat.id,chatTitle:e.message.chat.title,chatType:e.message.chat.type,messageId:e.message.messageId,messageThreadId:e.message.messageThreadId,userId:e.message.from?.id,username:e.message.from?.username}),o=e.message.text||e.message.caption,s=e.message.replyToMessage?.from?.isBot===!0&&o.trim().length>0?[telegramReplyInputResponse({messageId:e.message.replyToMessage.messageId,text:o})]:void 0;try{await e.send({inputResponses:s,message:a,modelContext:r.modelContext},{auth:r.auth,continuationToken:continuationTokenFromState(t),state:t})}catch(e){log.error(`message delivery failed`,{error:e})}}async function dispatchCallbackQuery(e){let t=stateFromCallbackQuery(e.query,e.config),n={telegram:buildTelegramHandle({config:e.config,state:t})};if(e.query.data?.startsWith(TELEGRAM_HITL_CALLBACK_PREFIX)===!0){try{await n.telegram.answerCallbackQuery({callbackQueryId:e.query.id,text:`Answer received.`})}catch(e){log.warn(`Telegram callback-query acknowledgement failed`,{error:e})}if(!e.query.message||!t.chatId)return;try{await e.send({inputResponses:[telegramCallbackInputResponse(e.query.data)]},{auth:null,continuationToken:continuationTokenFromState(t),state:t})}catch(e){log.error(`callback query delivery failed`,{error:e})}return}if(e.config.onCallbackQuery!==void 0){try{await e.config.onCallbackQuery(n,e.query)}catch(e){log.error(`custom callback-query handler failed`,{error:e})}return}try{await n.telegram.answerCallbackQuery({callbackQueryId:e.query.id,text:`Unsupported action.`})}catch(e){log.warn(`Telegram unsupported callback-query acknowledgement failed`,{error:e})}}function attachTelegramDeliver(e){if(!isCompiledChannel(e))return;let t=e.adapter;t.deliver=(e,t)=>{let n=e.inputResponses??[];if(n.some(isTelegramSyntheticResponse)){let r=resolveTelegramInputResponses(t.state,n);return r.length>0?{inputResponses:r,modelContext:e.modelContext}:e.message===void 0?void 0:{message:e.message,modelContext:e.modelContext}}return defaultDeliverResult(e)}}function stateFromMessage(e,t){let n=e.chat.type===`private`;return{...initialTelegramState(t.botUsername),chatId:e.chat.id,chatType:e.chat.type,conversationId:n?null:conversationIdForMessage(e),messageThreadId:e.messageThreadId??null,triggeringUserId:e.from?.id??null}}function stateFromCallbackQuery(e,t){let n=e.message;if(!n)return{...initialTelegramState(t.botUsername),triggeringUserId:e.from.id};let r=n.chat.type===`private`;return{...initialTelegramState(t.botUsername),chatId:n.chat.id,chatType:n.chat.type,conversationId:r?null:n.messageId,messageThreadId:n.messageThreadId??null,triggeringUserId:e.from.id}}function conversationIdForMessage(e){return e.replyToMessage?.from?.isBot===!0?e.replyToMessage.messageId:e.messageId}function continuationTokenFromState(e){return telegramContinuationToken({chatId:e.chatId??``,conversationId:e.chatType===`private`?void 0:e.conversationId??void 0,messageThreadId:e.messageThreadId??void 0})}function initialTelegramState(e){return{botUsername:e??null,chatId:null,chatType:null,conversationId:null,hitlCallbacks:{},messageThreadId:null,nextHitlCallbackId:0,pendingFreeformReplies:{},triggeringUserId:null}}function readChatId(e){if(typeof e==`string`&&e.length>0)return e;if(typeof e==`number`&&Number.isFinite(e))return String(e)}function readOptionalString(e){if(typeof e==`string`&&e.length>0)return e;if(typeof e==`number`&&Number.isFinite(e))return String(e)}export{telegramChannel};

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

@@ -1,4 +1,4 @@
-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 { twilioChannel, type TwilioAllowFrom, type TwilioChannel, type TwilioChannelConfig, type TwilioChannelCredentials, type TwilioChannelEvents, type TwilioChannelState, type TwilioContext, type TwilioEventContext, type TwilioHandle, type TwilioInboundResult, type TwilioInboundResultOrPromise, type TwilioInstrumentationMetadata, type TwilioMessagingConfig, type TwilioReceiveArgs, type TwilioSendMessageOptions, type TwilioVoiceConfig, type TwilioVoiceResult, type TwilioVoiceResultOrPromise, } from "#public/channels/twilio/twilioChannel.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";

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

@@ -15,10 +15,13 @@ type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessa
 export interface TwilioContext {
     readonly twilio: TwilioHandle;
 }
-/** Event-handler Twilio context, including mutable per-phone channel state. */
-export interface TwilioEventContext extends TwilioContext, ChannelSessionOps {
+/** Channel-owned Twilio context returned by `context()`. */
+export interface TwilioChannelContext extends TwilioContext {
     state: TwilioChannelState;
 }
+/** Event-handler Twilio context, including session operations. */
+export interface TwilioEventContext extends TwilioChannelContext, ChannelSessionOps {
+}
 /** JSON-serializable state for the phone-number conversation. */
 export interface TwilioChannelState {
     /** Caller / sender phone number. */
@@ -30,6 +33,12 @@ export interface TwilioChannelState {
     /** Most recent inbound Call SID when this session was started by voice. */
     lastCallSid?: string | null;
 }
+export interface TwilioInstrumentationMetadata extends Record<string, unknown> {
+    readonly from: string | null;
+    readonly lastCallSid: string | null;
+    readonly lastMessageSid: string | null;
+    readonly to: string | null;
+}
 /** Twilio channel credentials. `authToken` also verifies inbound webhook signatures. */
 export interface TwilioChannelCredentials extends TwilioCredentials {
     readonly authToken?: TwilioAuthToken;
@@ -174,7 +183,7 @@ export interface TwilioSendMessageOptions {
     readonly statusCallbackUrl?: string;
 }
 /** Concrete return type of {@link twilioChannel}. */
-export interface TwilioChannel extends Channel<TwilioChannelState, TwilioReceiveArgs> {
+export interface TwilioChannel extends Channel<TwilioChannelState, TwilioReceiveArgs, TwilioInstrumentationMetadata> {
 }
 /** Twilio channel factory for SMS and speech-transcribed inbound calls. */
 export declare function twilioChannel(config: TwilioChannelConfig): TwilioChannel;

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{parseTwilioTextMessage,parseTwilioVoiceCall,parseTwilioVoiceTranscription,prependTwilioContext}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},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=prependTwilioContext(t.body,{channel:`text`,from:t.from,messageSid:t.messageSid,to:t.to});try{await e.send(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=prependTwilioContext(t.text,{callSid:t.callSid,channel:`voice`,from:t.from,to:t.to});try{await e.send(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{parseTwilioTextMessage,parseTwilioVoiceCall,parseTwilioVoiceTranscription,prependTwilioContext}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=prependTwilioContext(t.body,{channel:`text`,from:t.from,messageSid:t.messageSid,to:t.to});try{await e.send(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=prependTwilioContext(t.text,{callSid:t.callSid,channel:`voice`,from:t.from,to:t.to});try{await e.send(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

@@ -6,6 +6,7 @@ import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { RouteDefinition, SendFn } from "#channel/routes.js";
 import type { Session, SessionHandle } from "#channel/session.js";
+declare const CHANNEL_METADATA_TYPE: unique symbol;
 export type { Session, SessionHandle } from "#channel/session.js";
 export { GET, POST, PUT, PATCH, DELETE } from "#channel/routes.js";
 export type { RouteDefinition, RouteHandlerArgs, SendFn, SendOptions, SendPayload, GetSessionFn, } from "#channel/routes.js";
@@ -53,7 +54,7 @@ export interface ReceiveInput<TReceiveArgs = Record<string, unknown>> {
     readonly args: Readonly<TReceiveArgs>;
     readonly auth: SessionAuthContext | null;
 }
-export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs = Record<string, unknown>> {
+export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
     readonly state?: TState;
     /**
      * Builds the per-step channel context handed to `events` and
@@ -68,7 +69,7 @@ export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs
      * (with {@link ChannelSessionOps} injected) and passes
      * {@link SessionContext} as a separate `ctx` argument.
      */
-    context?(state: NonNullable<TState>, session: SessionHandle): Omit<TCtx, keyof ChannelSessionOps>;
+    context?(state: NonNullable<TState>, session: SessionHandle): TCtx;
     readonly routes: readonly RouteDefinition<TState>[];
     receive?(input: ReceiveInput<TReceiveArgs>, args: {
         send: SendFn<TState>;
@@ -84,6 +85,16 @@ export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs
      * stage the file to the sandbox.
      */
     readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
+    /**
+     * Channel-owned metadata exposed to instrumentation callbacks.
+     *
+     * Keep this projection intentionally small. It is the channel's public
+     * observability surface, not a dump of durable adapter state. Return an
+     * object composed of JSON primitives, arrays, and plain objects. Ash omits
+     * `undefined` object properties and drops projections containing values such
+     * as `Date` or `Map`.
+     */
+    readonly metadata?: (state: NonNullable<TState>) => TMetadata;
     /**
      * Identifier of the adapter family this channel belongs to. Set by
      * higher-level wrappers (e.g. `slackChannel` passes `"slack"`) so
@@ -97,8 +108,9 @@ export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveArgs
      */
     readonly kindHint?: string;
 }
-export interface Channel<TState = undefined, TReceiveArgs = Record<string, unknown>> extends TypedReceiveRoute<TReceiveArgs> {
+export interface Channel<TState = undefined, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends TypedReceiveRoute<TReceiveArgs> {
     readonly __kind: typeof CHANNEL_SENTINEL;
+    readonly [CHANNEL_METADATA_TYPE]?: TMetadata;
     readonly routes: readonly {
         method: string;
         path: string;
@@ -107,4 +119,5 @@ export interface Channel<TState = undefined, TReceiveArgs = Record<string, unkno
         send: SendFn<TState>;
     }) => Promise<Session>;
 }
-export declare function defineChannel<TState = undefined, TCtx = void, TReceiveArgs = Record<string, unknown>>(definition: ChannelDefinition<TState, TCtx, TReceiveArgs>): Channel<TState, TReceiveArgs>;
+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>;

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

@@ -1 +1 @@
-import{CHANNEL_SENTINEL}from"#channel/compiled-channel.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{defaultDeliverResult}from"#channel/adapter.js";import{HTTP_ADAPTER_KIND}from"#channel/http.js";import{DELETE,GET,PATCH,POST,PUT}from"#channel/routes.js";function defineChannel(t){let n=buildAdapter(t);return{__kind:CHANNEL_SENTINEL,routes:t.routes,adapter:n,receive:t.receive}}function buildAdapter(e){let i=e.state!=null,a=e.context!=null,o=e.fetchFile!==void 0,s=i||a,c={},l=!1,u=[`turn.started`,`actions.requested`,`action.result`,`message.completed`,`message.appended`,`input.requested`,`turn.failed`,`turn.completed`,`session.failed`,`session.completed`,`session.waiting`,`authorization.required`,`authorization.completed`],d=e.events;for(let e of u){let n=d?.[e];n&&(l=!0,c[e]=(r,i)=>{let a={...i,continuationToken:i.session?.continuationToken??``,setContinuationToken:e=>i.session?.setContinuationToken(e)};return e===`session.failed`?n(r,a):n(r,a,buildCallbackContext())})}return!s&&!l&&!o?{kind:e.kindHint??HTTP_ADAPTER_KIND}:{kind:e.kindHint??`defineChannel`,state:i?{...e.state}:{},fetchFile:e.fetchFile,createAdapterContext(t){let n=t.state,r=t.session;return{...a?e.context(n,r):{},state:n,ctx:t.ctx,session:r}},deliver(e){return defaultDeliverResult(e)},...c}}export{DELETE,GET,PATCH,POST,PUT,defineChannel};
+import{CHANNEL_SENTINEL}from"#channel/compiled-channel.js";import{defaultDeliverResult}from"#channel/adapter.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{HTTP_ADAPTER_KIND}from"#channel/http.js";import{DELETE,GET,PATCH,POST,PUT}from"#channel/routes.js";function defineChannel(t){let n=buildAdapter(t);return{__kind:CHANNEL_SENTINEL,routes:t.routes,adapter:n,receive:t.receive}}function buildAdapter(e){let i=e.state!=null,a=e.context!=null,o=e.fetchFile!==void 0,s=e.metadata,c=i||a||s!==void 0,l={},u=!1,d=[`turn.started`,`actions.requested`,`action.result`,`message.completed`,`message.appended`,`input.requested`,`turn.failed`,`turn.completed`,`session.failed`,`session.completed`,`session.waiting`,`authorization.required`,`authorization.completed`],f=e.events;for(let e of d){let t=f?.[e];t&&(u=!0,l[e]=(r,i)=>{let a={...i,continuationToken:i.session?.continuationToken??``,setContinuationToken:e=>i.session?.setContinuationToken(e)};return e===`session.failed`?t(r,a):t(r,a,buildCallbackContext())})}return!c&&!u&&!o?{kind:e.kindHint??HTTP_ADAPTER_KIND}:{kind:e.kindHint??`defineChannel`,state:i?{...e.state}:{},fetchFile:e.fetchFile,instrumentation:s===void 0?void 0:{metadata(e){return s(e)}},createAdapterContext(t){let n=t.state,r=t.session;return{...a?e.context(n,r):{},state:n,ctx:t.ctx,session:r}},deliver(e){return defaultDeliverResult(e)},...l}}export{DELETE,GET,PATCH,POST,PUT,defineChannel};

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

@@ -2,7 +2,6 @@ import type { ModelMessage } from "ai";
 import type { HandleMessageStreamEvent } from "../../protocol/message.js";
 import type { SessionContext } from "./callback-context.js";
 import type { ExactDefinition } from "./exact.js";
-import type { NamedSkillDefinition } from "./skill.js";
 /**
  * Context passed to every hook handler.
  *
@@ -24,22 +23,15 @@ export interface HookContext extends SessionContext {
  * `lifecycle.turn`).
  *
  * `modelContext` messages are appended to the next model call's message
- * list and never written to durable session history. `skills` are
- * materialized into the live sandbox and announced through durable
- * system history. Each lifecycle key runs in registry order;
- * contributions are concatenated session-then-turn before the harness's
- * first model call.
+ * list and never written to durable session history. Each lifecycle key
+ * runs in registry order; contributions are concatenated session-then-turn
+ * before the harness's first model call.
  *
  * Returning `void` (or `undefined`) means "no opinion" — the turn
  * proceeds with no additional model context from this hook.
  */
 export interface LifecycleHookResult {
     readonly modelContext?: readonly ModelMessage[];
-    /**
-     * Skill packages to materialize into the live durable sandbox before the
-     * next model call. Authored skill names cannot be overwritten.
-     */
-    readonly skills?: readonly NamedSkillDefinition[];
 }
 /**
  * Lifecycle hook signature shared by `lifecycle.session` and

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

@@ -1,66 +1 @@
-import type { ExactDefinition } from "#public/definitions/exact.js";
-/**
- * Context passed to the {@link InstrumentationDefinition.setup} callback.
- */
-export interface InstrumentationSetupContext {
-    /**
-     * The agent name declared by `defineAgent`.
-     *
-     * Use this as the `serviceName` for `registerOTel` instead of
-     * hard-coding a string — it prevents copy-paste drift across agents.
-     */
-    readonly agentName: string;
-}
-/**
- * Authored instrumentation settings accepted by `defineInstrumentation`.
- *
- * The presence of a `defineInstrumentation` export implicitly enables
- * telemetry — there is no separate `isEnabled` toggle.
- */
-export interface InstrumentationDefinition {
-    /**
-     * Override the default function identifier attached to telemetry spans.
-     *
-     * When omitted, Ash derives the identifier from the agent name.
-     */
-    readonly functionId?: string;
-    /**
-     * Additional metadata merged into every AI SDK telemetry span.
-     */
-    readonly metadata?: Record<string, string>;
-    /**
-     * Whether to record full model inputs in telemetry spans.
-     *
-     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
-     * to disable recording inputs, which may be useful if inputs contain
-     * sensitive content or you want to reduce span payload size.
-     */
-    readonly recordInputs?: boolean;
-    /**
-     * Whether to record full model outputs in telemetry spans.
-     *
-     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
-     * to disable recording outputs.
-     */
-    readonly recordOutputs?: boolean;
-    /**
-     * Optional setup callback invoked at server startup with the resolved
-     * agent name.
-     *
-     * Use this to call `registerOTel` or any other OTel provider setup.
-     * The `context.agentName` value comes from `defineAgent`, so you never
-     * need to hard-code a service name.
-     */
-    readonly setup?: (context: InstrumentationSetupContext) => void;
-}
-/**
- * Defines instrumentation settings for the agent application.
- *
- * Export the result as the default export of `agent/instrumentation.ts`.
- * Ash picks up these settings at server startup and applies them to every
- * AI SDK model call.
- *
- * The `setup` callback is invoked later by the framework with the resolved
- * agent name — it is not called during `defineInstrumentation` itself.
- */
-export declare function defineInstrumentation<T extends InstrumentationDefinition>(definition: ExactDefinition<T, InstrumentationDefinition>): T;
+export * from "#public/instrumentation/index.js";

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

@@ -1 +1 @@
-function defineInstrumentation(e){return e}export{defineInstrumentation};
+export*from"#public/instrumentation/index.js";export{};

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

@@ -12,5 +12,10 @@ export type SkillDefinition = SkillPackageDefinition;
 /**
  * Defines a skill in TypeScript using the same shape discovery produces from
  * markdown, with optional package-relative sibling files.
+ *
+ * When used as the default export of a file in `agent/skills/`, this
+ * produces a static skill. When used inside a `defineDynamic` handler,
+ * the brand stamp lets the lifecycle code detect single-entry vs
+ * map-of-entries return shapes.
  */
 export declare function defineSkill<TSkill extends SkillDefinition>(definition: ExactDefinition<TSkill, SkillDefinition>): TSkill;

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

@@ -1,9 +1,9 @@
 import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { ModelMessage } from "ai";
-import type { PublicToolDefinition } from "#shared/tool-definition.js";
+import type { PublicToolDefinition, ToolModelOutput } from "#shared/tool-definition.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { JsonObject } from "#shared/json.js";
-import { type DynamicSingleToolEvents, type DynamicToolEntry, type DynamicToolEvents, type DynamicToolSentinel, type DynamicToolsSentinel } from "#shared/dynamic-tool-definition.js";
+import { type DynamicEvents, type DynamicSentinel } from "#shared/dynamic-tool-definition.js";
 /**
  * Domain input passed to a tool's {@link ToolDefinition.onCompact} hook.
  */
@@ -39,19 +39,7 @@ export interface NeedsApprovalContext<TInput = Record<string, unknown>> {
     readonly toolInput?: ApprovalToolInput<TInput>;
     readonly toolName: string;
 }
-/**
- * Ash-owned shape for the model-facing tool result produced by
- * {@link ToolDefinition.toModelOutput}. Structurally compatible with the
- * AI SDK's `ToolResultOutput` so the harness can forward it without
- * conversion.
- */
-export type ToolModelOutput = {
-    readonly type: "text";
-    readonly value: string;
-} | {
-    readonly type: "json";
-    readonly value: unknown;
-};
+export type { ToolModelOutput } from "#shared/tool-definition.js";
 /**
  * Result returned from a {@link ToolRetentionPolicy} function.
  *
@@ -140,6 +128,13 @@ export type ToolDefinition<TInput = unknown, TOutput = unknown> = PublicToolDefi
 };
 /**
  * Defines a tool configuration.
+ *
+ * Used for both static tools (default export from `agent/tools/*.ts`)
+ * and as the entry wrapper inside `defineDynamic` resolvers.
+ *
+ * For static tools, the runtime tool name is the filename slug.
+ * For dynamic entries, `defineTool` stamps a brand that the
+ * lifecycle code validates — raw object literals are rejected.
  */
 export declare function defineTool<TSchema extends StandardJSONSchemaV1<unknown, unknown>, TOutput>(definition: {
     description: ToolDefinition<unknown, unknown>["description"];
@@ -160,72 +155,37 @@ export declare function defineTool<TOutput>(definition: {
     onCompact?: ToolDefinition<unknown, unknown>["onCompact"];
 }): ToolDefinition<Record<string, unknown>, TOutput>;
 export declare function defineTool<TInput = unknown, TOutput = unknown>(definition: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
-export declare function defineTool<TInput = unknown, TOutput = unknown>(definition: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
-export declare function defineTool(definition: {
-    readonly events: DynamicSingleToolEvents;
-}): DynamicToolSentinel;
 /**
  * Defines a dynamic tool set resolved at runtime. The file's
- * path-derived slug becomes the tool name prefix; entry keys become
- * suffixes joined by `__`. When the resolver returns exactly one
- * entry, the tool takes the file's name directly.
- *
- * Uses the same `events` object shape as {@link defineHook}:
+ * path-derived slug becomes the tool name; the handler's return
+ * shape determines naming:
  *
- * ```ts
- * export default defineTools({
- *   events: {
- *     "session.started": async (event, ctx) => ({
- *       export: { description: "...", inputSchema: {...}, execute: ... },
- *       query:  { description: "...", inputSchema: {...}, execute: ... },
- *     }),
- *   },
- * });
- * ```
- */
-export declare function defineTools(definition: {
-    readonly events: DynamicToolEvents;
-}): DynamicToolsSentinel;
-/**
- * Typed wrapper for a single entry inside a `defineTools` resolver.
- * Mirrors the AI SDK's `tool()` pattern — an identity function at
- * runtime that captures `TSchema` at the type level so `execute(input)`
- * is inferred from the schema.
+ * - Return a single `defineTool(...)` → tool named after the file slug.
+ * - Return a `Record<string, defineTool(...)>` → tools named `slug__key`.
+ * - Return `null` → no tools for this event.
  *
  * ```ts
- * import { defineTools, tool } from "experimental-ash/tools";
+ * import { defineDynamic, defineTool } from "experimental-ash/tools";
  * import { z } from "zod";
  *
- * export default defineTools({
+ * export default defineDynamic({
  *   events: {
- *     "session.started": async () => ({
- *       weather: tool({
- *         description: "Get weather",
- *         inputSchema: z.object({ city: z.string() }),
+ *     "session.started": async (event, ctx) => ({
+ *       export: defineTool({
+ *         description: "Export data",
+ *         inputSchema: z.object({ format: z.string() }),
  *         async execute(input) {
- *           // input.city is typed as string
- *           return fetchWeather(input.city);
+ *           return doExport(input.format);
  *         },
  *       }),
  *     }),
  *   },
  * });
  * ```
- *
- * Without `tool()`, `execute(input)` defaults to
- * `Record<string, unknown>`. Use `tool()` when you want schema-
- * inferred types.
  */
-export declare function tool<TSchema extends StandardJSONSchemaV1<unknown, unknown>, TOutput>(entry: {
-    description: string;
-    inputSchema: TSchema;
-    execute(input: StandardJSONSchemaV1.InferOutput<TSchema>, ctx: ToolContext): TOutput | Promise<TOutput>;
-}): DynamicToolEntry<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>;
-export declare function tool<TOutput>(entry: {
-    description: string;
-    inputSchema: JsonObject;
-    execute(input: Record<string, unknown>, ctx: ToolContext): TOutput | Promise<TOutput>;
-}): DynamicToolEntry<Record<string, unknown>, TOutput>;
+export declare function defineDynamic(definition: {
+    readonly events: DynamicEvents;
+}): DynamicSentinel;
 /**
  * Marker discriminator written into every {@link DisabledToolSentinel}.
  */
@@ -248,4 +208,3 @@ export declare function disableTool(): DisabledToolSentinel;
  * produced by {@link disableTool}.
  */
 export declare function isDisabledToolSentinel(value: unknown): value is DisabledToolSentinel;
-export {};

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

@@ -1 +1 @@
-import{DYNAMIC_TOOLS_SENTINEL_KIND,DYNAMIC_TOOL_SENTINEL_KIND}from"#shared/dynamic-tool-definition.js";import{stampDefinitionKey}from"#public/tool-result-narrowing.js";function defineTool(e){if(`events`in e){let n={kind:DYNAMIC_TOOL_SENTINEL_KIND,events:e.events};return stampDefinitionKey(n,`dynamic-tool:${Object.keys(e.events).join(`,`)}`),n}return stampDefinitionKey(e,`tool:${e.description}`),e}function defineTools(t){let n={kind:DYNAMIC_TOOLS_SENTINEL_KIND,events:t.events};return stampDefinitionKey(n,`dynamic-tools:${Object.keys(t.events).join(`,`)}`),n}function tool(e){return Object.assign(e,{__brand:`ash:tool`})}const DISABLED_TOOL_SENTINEL_KIND=`ash:disabled-tool`;function disableTool(){return{kind:DISABLED_TOOL_SENTINEL_KIND}}function isDisabledToolSentinel(e){return typeof e==`object`&&!!e&&e.kind===DISABLED_TOOL_SENTINEL_KIND}export{defineTool,defineTools,disableTool,isDisabledToolSentinel,tool};
+import{DYNAMIC_SENTINEL_KIND,TOOL_BRAND}from"#shared/dynamic-tool-definition.js";import{stampDefinitionKey}from"#public/tool-result-narrowing.js";function defineTool(e){return Object.assign(e,{[TOOL_BRAND]:!0}),stampDefinitionKey(e,`tool:${e.description}`),e}function defineDynamic(t){let n={kind:DYNAMIC_SENTINEL_KIND,events:t.events};return stampDefinitionKey(n,`dynamic:${Object.keys(t.events).join(`,`)}`),n}const DISABLED_TOOL_SENTINEL_KIND=`ash:disabled-tool`;function disableTool(){return{kind:DISABLED_TOOL_SENTINEL_KIND}}function isDisabledToolSentinel(e){return typeof e==`object`&&!!e&&e.kind===DISABLED_TOOL_SENTINEL_KIND}export{defineDynamic,defineTool,disableTool,isDisabledToolSentinel};

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

@@ -1,4 +1,178 @@
+import type { ExactDefinition } from "#public/definitions/exact.js";
 /**
  * Instrumentation authoring helpers for `agent/instrumentation.ts`.
  */
-export { defineInstrumentation, type InstrumentationDefinition, type InstrumentationSetupContext, } from "#public/definitions/instrumentation.js";
+import type { ModelMessage, SystemModelMessage } from "ai";
+import type { SessionAuthContext, SessionParent } from "#channel/types.js";
+import type { Channel } from "#public/definitions/defineChannel.js";
+/**
+ * Context passed to the {@link InstrumentationDefinition.setup} callback.
+ */
+export interface InstrumentationSetupContext {
+    /**
+     * The agent name declared by `defineAgent`.
+     *
+     * Use this as the `serviceName` for `registerOTel` instead of
+     * hard-coding a string — it prevents copy-paste drift across agents.
+     */
+    readonly agentName: string;
+}
+/**
+ * User-authored metadata attached to AI SDK telemetry spans.
+ *
+ * Keys beginning with `ash.` are reserved for framework-owned metadata
+ * and are ignored when returned from authored instrumentation.
+ */
+export type InstrumentationMetadata = Readonly<Record<string, string>>;
+/**
+ * Base channel metadata shape used by framework channel kinds.
+ */
+export type InstrumentationChannelMetadata = Readonly<Record<string, unknown>>;
+/**
+ * Channel metadata projections keyed by instrumentation channel kind.
+ *
+ * Channel packages and user-authored channels declaration-merge additional
+ * `channel:<registered-name>` entries into this map so `input.channel.metadata`
+ * narrows after checking `input.channel.kind`.
+ */
+export interface ChannelMetadataMap {
+    readonly http: InstrumentationChannelMetadata;
+    readonly schedule: InstrumentationChannelMetadata;
+    readonly subagent: InstrumentationChannelMetadata;
+    readonly unknown: InstrumentationChannelMetadata;
+}
+export type InstrumentationChannelKind = keyof ChannelMetadataMap;
+/**
+ * Authored channel values keyed by path-derived instrumentation channel kind.
+ *
+ * Ash generates declaration-merged entries for authored channel files. Use
+ * this map through {@link isChannel}; authored code should not merge it by
+ * hand except for unusual setups outside the compiler-owned path.
+ */
+export interface ChannelReferenceMap {
+}
+/**
+ * Channel projection exposed to instrumentation callbacks.
+ *
+ * `kind` is the channel identity Ash has for the current turn (`"http"`,
+ * `"schedule"`, `"subagent"`, or `channel:<name>` for authored channels,
+ * where `<name>` is the channel's filename under `agent/channels/`).
+ */
+export interface InstrumentationChannelForKind<K extends InstrumentationChannelKind> {
+    readonly kind: K;
+    readonly metadata: ChannelMetadataMap[K];
+}
+export type InstrumentationChannel = {
+    readonly [K in InstrumentationChannelKind]: InstrumentationChannelForKind<K>;
+}[InstrumentationChannelKind];
+type ChannelReferenceKind<TChannel> = {
+    readonly [K in keyof ChannelReferenceMap]: [TChannel] extends [ChannelReferenceMap[K]] ? [ChannelReferenceMap[K]] extends [TChannel] ? K : never : never;
+}[keyof ChannelReferenceMap];
+export type InstrumentationChannelForChannel<TChannel> = Extract<InstrumentationChannel, {
+    readonly kind: Extract<ChannelReferenceKind<TChannel>, InstrumentationChannelKind>;
+}>;
+export interface InstrumentationSession {
+    readonly auth: {
+        readonly current: SessionAuthContext | null;
+        readonly initiator: SessionAuthContext | null;
+    };
+    readonly id: string;
+    readonly parent?: SessionParent;
+}
+export interface InstrumentationTurn {
+    readonly id: string;
+    readonly sequence: number;
+}
+export interface InstrumentationStep {
+    readonly index: number;
+}
+export interface InstrumentationModelInput {
+    readonly instructions: string | readonly SystemModelMessage[] | undefined;
+    readonly messages: readonly ModelMessage[];
+}
+/**
+ * Input passed to `metadata["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 {
+    readonly channel: InstrumentationChannel;
+    readonly modelInput: InstrumentationModelInput;
+    readonly session: InstrumentationSession;
+    readonly step: InstrumentationStep;
+    readonly turn: InstrumentationTurn;
+}
+/**
+ * Metadata hooks accepted by {@link defineInstrumentation}.
+ */
+export interface InstrumentationMetadataConfig {
+    /**
+     * Per-attempt metadata resolved before the model call so child spans
+     * created by the AI SDK inherit the returned values.
+     */
+    readonly "step.started"?: (input: InstrumentationStepStartedMetadataInput) => InstrumentationMetadata;
+}
+/**
+ * Authored instrumentation settings accepted by `defineInstrumentation`.
+ *
+ * The presence of a `defineInstrumentation` export implicitly enables
+ * telemetry — there is no separate `isEnabled` toggle.
+ */
+export interface InstrumentationDefinition {
+    /**
+     * Override the default function identifier attached to telemetry spans.
+     *
+     * When omitted, Ash derives the identifier from the agent name.
+     */
+    readonly functionId?: string;
+    /**
+     * Additional metadata merged into AI SDK telemetry spans.
+     */
+    readonly metadata?: InstrumentationMetadataConfig;
+    /**
+     * Whether to record full model inputs in telemetry spans.
+     *
+     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
+     * to disable recording inputs, which may be useful if inputs contain
+     * sensitive content or you want to reduce span payload size.
+     */
+    readonly recordInputs?: boolean;
+    /**
+     * Whether to record full model outputs in telemetry spans.
+     *
+     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
+     * to disable recording outputs.
+     */
+    readonly recordOutputs?: boolean;
+    /**
+     * Optional setup callback invoked at server startup with the resolved
+     * agent name.
+     *
+     * Use this to call `registerOTel` or any other OTel provider setup.
+     * The `context.agentName` value comes from `defineAgent`, so you never
+     * need to hard-code a service name.
+     */
+    readonly setup?: (context: InstrumentationSetupContext) => void;
+}
+/**
+ * Defines instrumentation settings for the agent application.
+ *
+ * Export the result as the default export of `agent/instrumentation.ts`.
+ * Ash picks up these settings at server startup and applies them to every
+ * AI SDK model call.
+ *
+ * The `setup` callback is invoked later by the framework with the resolved
+ * agent name — it is not called during `defineInstrumentation` itself.
+ */
+export declare function defineInstrumentation<T extends InstrumentationDefinition>(definition: ExactDefinition<T, InstrumentationDefinition>): T;
+/**
+ * Narrows an instrumentation channel by comparing it to an app-owned channel
+ * value imported from `agent/channels/*`.
+ *
+ * The comparison uses the compiler's path-derived `channel:<slug>` identity.
+ * It does not read durable channel state; metadata remains the explicit
+ * projection returned by the channel's `metadata(state)` function.
+ */
+export declare function isChannel<TChannel extends Channel<any, any, any>>(channel: InstrumentationChannel, target: TChannel): channel is InstrumentationChannelForChannel<TChannel>;
+export {};