experimental-ash 0.26.0 → 0.28.0

package/dist/src/public/channels/teams/inbound.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Inbound Microsoft Teams activity parsing and prompt shaping.
+ *
+ * The channel owns small, documented data shapes instead of exposing the
+ * full Bot Framework SDK Activity model as the primary public API.
+ */
+import type { UserContent } from "ai";
+import type { TeamsAttachment, TeamsChannelAccount, TeamsMention } from "#public/channels/teams/api.js";
+/** Teams conversation scopes handled by the native channel. */
+export type TeamsConversationScope = "channel" | "groupChat" | "personal" | "unknown";
+/** Bot Framework conversation account fields used by the Teams channel. */
+export interface TeamsConversationAccount {
+    readonly conversationType?: string;
+    readonly id: string;
+    readonly isGroup?: boolean;
+    readonly name?: string;
+    readonly tenantId?: string;
+}
+/** Common fields shared by parsed Teams activities. */
+export interface TeamsActivityBase {
+    readonly channelData: Record<string, unknown>;
+    readonly conversation: TeamsConversationAccount;
+    readonly conversationType?: string;
+    readonly from: TeamsChannelAccount;
+    readonly id: string;
+    readonly raw: Record<string, unknown>;
+    readonly recipient: TeamsChannelAccount;
+    readonly serviceUrl: string;
+    readonly tenantId?: string;
+    readonly teamId?: string;
+    readonly teamsChannelId?: string;
+}
+/** Parsed Teams message activity. */
+export interface TeamsMessageActivity extends TeamsActivityBase {
+    readonly attachments: readonly TeamsAttachment[];
+    readonly isBotMentioned: boolean;
+    readonly mentions: readonly TeamsMention[];
+    readonly replyToId?: string;
+    readonly scope: TeamsConversationScope;
+    readonly text: string;
+    readonly textFormat?: string;
+    readonly type: "message";
+    readonly value?: Record<string, unknown>;
+}
+/** Parsed Teams invoke activity. */
+export interface TeamsInvokeActivity extends TeamsActivityBase {
+    readonly name: string;
+    readonly replyToId?: string;
+    readonly scope: TeamsConversationScope;
+    readonly type: "invoke";
+    readonly value?: Record<string, unknown>;
+}
+/** Parsed Teams conversation-update activity. */
+export interface TeamsConversationUpdateActivity extends TeamsActivityBase {
+    readonly type: "conversationUpdate";
+}
+/** Parsed Teams activity variants handled by the native channel. */
+export type TeamsActivity = TeamsConversationUpdateActivity | TeamsInvokeActivity | TeamsMessageActivity;
+/** Inbound context rendered into the model-visible `<teams_context>` block. */
+export interface TeamsInboundContext {
+    readonly activityId: string;
+    readonly channelId?: string;
+    readonly conversationId: string;
+    readonly conversationType?: string;
+    readonly scope: TeamsConversationScope;
+    readonly teamId?: string;
+    readonly tenantId?: string;
+    readonly userId: string;
+    readonly userName?: string;
+}
+/** Parses one JSON-decoded Teams activity payload. */
+export declare function parseTeamsActivity(value: unknown): TeamsActivity | null;
+/** Returns whether the message's scope behaves like a Teams personal chat. */
+export declare function isTeamsPersonalMessage(activity: TeamsMessageActivity): boolean;
+/** Returns the root activity id that should anchor a Teams thread, when any. */
+export declare function teamsThreadRootActivityId(activity: TeamsMessageActivity | TeamsInvokeActivity): string | null;
+/** Renders one {@link TeamsInboundContext} as a deterministic context block. */
+export declare function formatTeamsContextBlock(context: TeamsInboundContext): string;
+/** Prepends a `<teams_context>` block to the inbound turn message. */
+export declare function prependTeamsContext(message: string | UserContent, context: TeamsInboundContext): string | UserContent;

package/dist/src/public/channels/teams/inbound.js

@@ -0,0 +1,3 @@
+import{isNonEmptyString,isObject}from"#shared/guards.js";import{parseJsonObject}from"#shared/json.js";import TurndownService from"#compiled/turndown/index.js";var TEAMS_RESPONSE_INSTRUCTIONS=`Reply for Microsoft Teams in concise Markdown. Avoid broad mentions, large tables, and messages that need more than a few short posts.`,HTML_ENTITY_MAP={"&amp;":`&`,"&gt;":`>`,"&lt;":`<`,"&nbsp;":` `,"&quot;":`"`,"&#39;":`'`,"&#x27;":`'`},HTML_ENTITY_PATTERN=new RegExp(Object.keys(HTML_ENTITY_MAP).join(`|`),`gi`),turndownService=null;function parseTeamsActivity(e){return isObject(e)?e.type===`message`?parseMessageActivity(e):e.type===`invoke`?parseInvokeActivity(e):e.type===`conversationUpdate`?parseConversationUpdateActivity(e):null:null}function isTeamsPersonalMessage(e){return e.scope===`personal`}function teamsThreadRootActivityId(e){return e.scope===`personal`?null:e.replyToId??e.id}function formatTeamsContextBlock(e){return[`<teams_context>`,`response_medium: microsoft_teams`,`response_instructions: ${TEAMS_RESPONSE_INSTRUCTIONS}`,`user_id: ${e.userId}`,...e.userName?[`user_name: ${e.userName}`]:[],`conversation_id: ${e.conversationId}`,`scope: ${e.scope}`,...e.conversationType?[`conversation_type: ${e.conversationType}`]:[],...e.tenantId?[`tenant_id: ${e.tenantId}`]:[],...e.teamId?[`team_id: ${e.teamId}`]:[],...e.channelId?[`channel_id: ${e.channelId}`]:[],`activity_id: ${e.activityId}`,`</teams_context>`].join(`
+`)}function prependTeamsContext(e,t){let n=formatTeamsContextBlock(t);return typeof e==`string`?e.length>0?`${n}\n\n${e}`:n:[{type:`text`,text:n},...e]}function parseMessageActivity(n){let r=parseActivityBase(n);if(!r)return null;let i=parseMentions(n.entities),a=normalizeTeamsText(stripBotMention(readText(n),i,r.recipient.id));return{...r,attachments:parseAttachments(n.attachments),isBotMentioned:i.some(e=>e.mentioned.id===r.recipient.id),mentions:i,replyToId:isNonEmptyString(n.replyToId)?n.replyToId:void 0,scope:inferScope(r.conversation),text:a,textFormat:isNonEmptyString(n.textFormat)?n.textFormat:void 0,type:`message`,value:isObject(n.value)?n.value:void 0}}function parseInvokeActivity(n){let r=parseActivityBase(n);return!r||!isNonEmptyString(n.name)?null:{...r,name:n.name,replyToId:isNonEmptyString(n.replyToId)?n.replyToId:void 0,scope:inferScope(r.conversation),type:`invoke`,value:isObject(n.value)?n.value:void 0}}function parseConversationUpdateActivity(e){let t=parseActivityBase(e);return t?{...t,type:`conversationUpdate`}:null}function parseActivityBase(n){if(!isNonEmptyString(n.serviceUrl))return null;let r=parseConversation(n.conversation),i=parseChannelAccount(n.from),a=parseChannelAccount(n.recipient);if(!r||!i||!a)return null;let o=isObject(n.channelData)?n.channelData:{},s=readNestedString(o,[`tenant`,`id`])??r.tenantId,c=readNestedString(o,[`team`,`id`]),l=readNestedString(o,[`channel`,`id`]);return{channelData:o,conversation:r,conversationType:r.conversationType,from:i,id:isNonEmptyString(n.id)?n.id:``,raw:n,recipient:a,serviceUrl:n.serviceUrl,tenantId:s,teamId:c,teamsChannelId:l}}function parseConversation(n){return!isObject(n)||!isNonEmptyString(n.id)?null:{conversationType:isNonEmptyString(n.conversationType)?n.conversationType:void 0,id:n.id,isGroup:typeof n.isGroup==`boolean`?n.isGroup:void 0,name:isNonEmptyString(n.name)?n.name:void 0,tenantId:isNonEmptyString(n.tenantId)?n.tenantId:void 0}}function parseChannelAccount(n){return!isObject(n)||!isNonEmptyString(n.id)?null:{aadObjectId:isNonEmptyString(n.aadObjectId)?n.aadObjectId:void 0,id:n.id,name:isNonEmptyString(n.name)?n.name:void 0,role:isNonEmptyString(n.role)?n.role:void 0}}function parseMentions(n){if(!Array.isArray(n))return[];let r=[];for(let i of n){if(!isObject(i)||i.type!==`mention`||!isNonEmptyString(i.text))continue;let n=parseChannelAccount(i.mentioned);n&&r.push({mentioned:n,text:i.text,type:`mention`})}return r}function parseAttachments(r){if(!Array.isArray(r))return[];let i=[];for(let a of r){if(!isObject(a)||!isNonEmptyString(a.contentType))continue;let r={content:isObject(a.content)?parseJsonObject(a.content):void 0,contentType:a.contentType,contentUrl:isNonEmptyString(a.contentUrl)?a.contentUrl:void 0,name:isNonEmptyString(a.name)?a.name:void 0};i.push(r)}return i}function inferScope(e){let t=e.conversationType;return t===`personal`||t===`groupChat`||t===`channel`?t:e.isGroup===!0?`groupChat`:e.isGroup===!1?`personal`:`unknown`}function readText(e){return typeof e.text==`string`?e.text:``}function stripBotMention(e,t,n){let r=e;for(let e of t)e.mentioned.id===n&&(r=r.replace(e.text,``));return r.trim()}function normalizeTeamsText(e){let t=e.trim();return looksLikeHtml(t)?getTurndownService().turndown(t.replace(/<at>(.*?)<\/at>/gi,`@$1`)).replace(/ {2}\n/g,`
+`).trim():decodeHtmlEntities(t)}function readNestedString(n,r){let i=n;for(let e of r){if(!isObject(i))return;i=i[e]}return isNonEmptyString(i)?i:void 0}function looksLikeHtml(e){return/<\/?[a-z][\s\S]*>/i.test(e)}function decodeHtmlEntities(e){return e.replace(HTML_ENTITY_PATTERN,e=>HTML_ENTITY_MAP[e.toLowerCase()]??e)}function getTurndownService(){return turndownService??=new TurndownService({bulletListMarker:`-`,codeBlockStyle:`fenced`,emDelimiter:`*`,headingStyle:`atx`,hr:`---`}),turndownService}export{formatTeamsContextBlock,isTeamsPersonalMessage,parseTeamsActivity,prependTeamsContext,teamsThreadRootActivityId};

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

@@ -0,0 +1,8 @@
+export type { ModelMessage } from "ai";
+export { teamsChannel, type TeamsChannel, type TeamsChannelConfig, type TeamsChannelCredentials, type TeamsChannelEvents, type TeamsChannelState, type TeamsContext, type TeamsEventContext, type TeamsHandle, type TeamsInboundResult, type TeamsInboundResultOrPromise, type TeamsInvokeResult, type TeamsInvokeResultOrPromise, type TeamsReceiveArgs, type TeamsRequestOptions, type TeamsThread, } from "#public/channels/teams/teamsChannel.js";
+export { callTeamsConnectorApi, normalizeTeamsPostInput, replyToTeamsActivity, resolveTeamsAccessToken, resolveTeamsAppId, resolveTeamsAppPassword, resolveTeamsTenantId, sendTeamsActivity, splitTeamsMessageText, teamsContinuationToken, triggerTeamsTypingIndicator, updateTeamsActivity, TEAMS_MESSAGE_TEXT_MAX_LENGTH, type TeamsAccessTokenResult, type TeamsApiOptions, type TeamsApiResponse, type TeamsAppId, type TeamsAppPassword, type TeamsAttachment, type TeamsChannelAccount, type TeamsCredentials, type TeamsFetch, type TeamsMention, type TeamsMessageBody, type TeamsOutboundActivity, type TeamsPostedActivity, type TeamsTenantId, type TeamsTokenProvider, } from "#public/channels/teams/api.js";
+export { formatTeamsContextBlock, isTeamsPersonalMessage, parseTeamsActivity, prependTeamsContext, teamsThreadRootActivityId, type TeamsActivity, type TeamsActivityBase, type TeamsConversationAccount, type TeamsConversationScope, type TeamsConversationUpdateActivity, type TeamsInboundContext, type TeamsInvokeActivity, type TeamsMessageActivity, } from "#public/channels/teams/inbound.js";
+export { deriveTeamsInputResponses, isTeamsInputResponseActivity, renderAnsweredInputRequestMessage, renderInputRequestAttachment, renderInputRequestMessage, teamsInvokeResponse, TEAMS_ADAPTIVE_CARD_CONTENT_TYPE, TEAMS_HITL_CHOICE_INPUT_ID, TEAMS_HITL_DATA_KEY, TEAMS_HITL_FREEFORM_INPUT_ID, } from "#public/channels/teams/hitl.js";
+export { collectTeamsFileParts, buildTeamsTurnMessage, createTeamsFetchFile, normalizeTeamsFilesPolicy, type TeamsFilesConfig, type TeamsFilesPolicy, } from "#public/channels/teams/attachments.js";
+export { buildAuthCompletedText, defaultTeamsAuth, formatConnectionDisplayName, teamsMentionUser, } from "#public/channels/teams/defaults.js";
+export { verifyTeamsJwt, verifyTeamsRequest, type TeamsJwtVerifyOptions, type TeamsVerifyOptions, type TeamsWebhookVerifier, } from "#public/channels/teams/verify.js";

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

@@ -0,0 +1 @@
+import{TEAMS_MESSAGE_TEXT_MAX_LENGTH,callTeamsConnectorApi,normalizeTeamsPostInput,replyToTeamsActivity,resolveTeamsAccessToken,resolveTeamsAppId,resolveTeamsAppPassword,resolveTeamsTenantId,sendTeamsActivity,splitTeamsMessageText,teamsContinuationToken,triggerTeamsTypingIndicator,updateTeamsActivity}from"#public/channels/teams/api.js";import{TEAMS_ADAPTIVE_CARD_CONTENT_TYPE,TEAMS_HITL_CHOICE_INPUT_ID,TEAMS_HITL_DATA_KEY,TEAMS_HITL_FREEFORM_INPUT_ID,deriveTeamsInputResponses,isTeamsInputResponseActivity,renderAnsweredInputRequestMessage,renderInputRequestAttachment,renderInputRequestMessage,teamsInvokeResponse}from"#public/channels/teams/hitl.js";import{teamsChannel}from"#public/channels/teams/teamsChannel.js";import{formatTeamsContextBlock,isTeamsPersonalMessage,parseTeamsActivity,prependTeamsContext,teamsThreadRootActivityId}from"#public/channels/teams/inbound.js";import{buildTeamsTurnMessage,collectTeamsFileParts,createTeamsFetchFile,normalizeTeamsFilesPolicy}from"#public/channels/teams/attachments.js";import{buildAuthCompletedText,defaultTeamsAuth,formatConnectionDisplayName,teamsMentionUser}from"#public/channels/teams/defaults.js";import{verifyTeamsJwt,verifyTeamsRequest}from"#public/channels/teams/verify.js";export{TEAMS_ADAPTIVE_CARD_CONTENT_TYPE,TEAMS_HITL_CHOICE_INPUT_ID,TEAMS_HITL_DATA_KEY,TEAMS_HITL_FREEFORM_INPUT_ID,TEAMS_MESSAGE_TEXT_MAX_LENGTH,buildAuthCompletedText,buildTeamsTurnMessage,callTeamsConnectorApi,collectTeamsFileParts,createTeamsFetchFile,defaultTeamsAuth,deriveTeamsInputResponses,formatConnectionDisplayName,formatTeamsContextBlock,isTeamsInputResponseActivity,isTeamsPersonalMessage,normalizeTeamsFilesPolicy,normalizeTeamsPostInput,parseTeamsActivity,prependTeamsContext,renderAnsweredInputRequestMessage,renderInputRequestAttachment,renderInputRequestMessage,replyToTeamsActivity,resolveTeamsAccessToken,resolveTeamsAppId,resolveTeamsAppPassword,resolveTeamsTenantId,sendTeamsActivity,splitTeamsMessageText,teamsChannel,teamsContinuationToken,teamsInvokeResponse,teamsMentionUser,teamsThreadRootActivityId,triggerTeamsTypingIndicator,updateTeamsActivity,verifyTeamsJwt,verifyTeamsRequest};

package/dist/src/public/channels/teams/limits.d.ts

@@ -0,0 +1,8 @@
+/** Maximum Teams Adaptive Card text block length used by Ash renderers. */
+export declare const TEAMS_ADAPTIVE_CARD_TEXT_MAX_LENGTH = 4000;
+/** Maximum Teams Adaptive Card button title length used by Ash renderers. */
+export declare const TEAMS_ADAPTIVE_CARD_ACTION_TITLE_MAX_LENGTH = 80;
+/** Maximum Teams Adaptive Card choice title length used by Ash renderers. */
+export declare const TEAMS_ADAPTIVE_CARD_CHOICE_TITLE_MAX_LENGTH = 100;
+/** Maximum number of direct Adaptive Card actions rendered for one request. */
+export declare const TEAMS_ADAPTIVE_CARD_ACTION_LIMIT = 6;

package/dist/src/public/channels/teams/limits.js

@@ -0,0 +1 @@
+var TEAMS_ADAPTIVE_CARD_TEXT_MAX_LENGTH=4e3,TEAMS_ADAPTIVE_CARD_ACTION_TITLE_MAX_LENGTH=80,TEAMS_ADAPTIVE_CARD_CHOICE_TITLE_MAX_LENGTH=100,TEAMS_ADAPTIVE_CARD_ACTION_LIMIT=6;export{TEAMS_ADAPTIVE_CARD_ACTION_LIMIT,TEAMS_ADAPTIVE_CARD_ACTION_TITLE_MAX_LENGTH,TEAMS_ADAPTIVE_CARD_CHOICE_TITLE_MAX_LENGTH,TEAMS_ADAPTIVE_CARD_TEXT_MAX_LENGTH};

package/dist/src/public/channels/teams/teamsChannel.d.ts

@@ -0,0 +1,162 @@
+import type { ModelMessage } from "ai";
+import type { TypedReceiveRoute } from "#channel/receive-args.js";
+import type { SessionHandle } from "#channel/session.js";
+import type { SessionAuthContext } from "#channel/types.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { type TeamsFilesConfig } from "#public/channels/teams/attachments.js";
+import { type TeamsApiOptions, type TeamsApiResponse, type TeamsChannelAccount, type TeamsCredentials, type TeamsMention, type TeamsMessageBody, type TeamsOutboundActivity, type TeamsPostedActivity } from "#public/channels/teams/api.js";
+import { type TeamsInvokeActivity, type TeamsMessageActivity } from "#public/channels/teams/inbound.js";
+import { type TeamsWebhookVerifier } from "#public/channels/teams/verify.js";
+import { type JsonObject } from "#shared/json.js";
+import { type Channel } from "#public/definitions/defineChannel.js";
+type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
+    type: T;
+}> extends {
+    data: infer D;
+} ? D : undefined;
+/** Pre-dispatch Teams context passed to inbound message and invoke hooks. */
+export interface TeamsContext {
+    readonly teams: TeamsHandle;
+    readonly thread: TeamsThread;
+}
+/** Event-handler Teams context, including mutable per-conversation state. */
+export interface TeamsEventContext extends TeamsContext {
+    readonly adaptiveCardVersion: string;
+    readonly session: SessionHandle;
+    state: TeamsChannelState;
+}
+/** JSON-serializable Teams channel state. */
+export interface TeamsChannelState {
+    /** Bot account captured from the inbound activity recipient. */
+    bot: TeamsChannelAccount | null;
+    /** Teams team/channel id for channel conversations, when present. */
+    channelId: string | null;
+    /** Bot Framework conversation id. */
+    conversationId: string | null;
+    /** Teams conversation type (`personal`, `groupChat`, `channel`, or platform value). */
+    conversationType: string | null;
+    /** Activity id used for thread replies in channel/group contexts. */
+    replyToActivityId: string | null;
+    /** Bot Framework serviceUrl for outbound Connector calls. */
+    serviceUrl: string | null;
+    /** Teams team id, when present. */
+    teamId: string | null;
+    /** Teams tenant id, when present. */
+    tenantId: string | null;
+    /** User account that triggered the latest turn/session. */
+    triggeringUser: TeamsChannelAccount | null;
+    /** Activity id for the default connection-auth card, when posted. */
+    pendingAuthActivityId?: string | null;
+}
+/** Teams channel credentials. */
+export interface TeamsChannelCredentials extends TeamsCredentials {
+    /**
+     * Custom inbound webhook verifier. When supplied, Ash delegates
+     * verification to this function instead of validating Bot Connector JWTs.
+     */
+    readonly webhookVerifier?: TeamsWebhookVerifier;
+}
+/** Arguments accepted by `receive(teams, args)` for proactive sessions. */
+export interface TeamsReceiveArgs {
+    readonly channelId?: string;
+    readonly conversationId: string;
+    readonly conversationType?: string;
+    readonly initialMessage?: string | TeamsMessageBody;
+    readonly replyToActivityId?: string;
+    readonly serviceUrl: string;
+    readonly teamId?: string;
+    readonly tenantId?: string;
+}
+/** Result of an inbound Teams message hook. Return `null` to acknowledge without dispatching. */
+export type TeamsInboundResult = {
+    readonly auth: SessionAuthContext | null;
+    readonly modelContext?: readonly ModelMessage[];
+} | null;
+/** Sync or async {@link TeamsInboundResult}. */
+export type TeamsInboundResultOrPromise = TeamsInboundResult | Promise<TeamsInboundResult>;
+/** Result of an inbound non-HITL Teams invoke hook. */
+export type TeamsInvokeResult = Record<string, unknown> | Response | null | undefined;
+/** Sync or async {@link TeamsInvokeResult}. */
+export type TeamsInvokeResultOrPromise = TeamsInvokeResult | Promise<TeamsInvokeResult>;
+type TeamsEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, ctx: TeamsEventContext) => void | Promise<void>;
+/** Event handlers supported by `teamsChannel({ events })`. */
+export interface TeamsChannelEvents {
+    readonly "turn.started"?: TeamsEventHandler<"turn.started">;
+    readonly "actions.requested"?: TeamsEventHandler<"actions.requested">;
+    readonly "action.result"?: TeamsEventHandler<"action.result">;
+    readonly "message.completed"?: TeamsEventHandler<"message.completed">;
+    readonly "message.appended"?: TeamsEventHandler<"message.appended">;
+    readonly "input.requested"?: TeamsEventHandler<"input.requested">;
+    readonly "turn.failed"?: TeamsEventHandler<"turn.failed">;
+    readonly "turn.completed"?: TeamsEventHandler<"turn.completed">;
+    readonly "session.failed"?: TeamsEventHandler<"session.failed">;
+    readonly "session.completed"?: TeamsEventHandler<"session.completed">;
+    readonly "session.waiting"?: TeamsEventHandler<"session.waiting">;
+    readonly "connection.authorization_required"?: TeamsEventHandler<"connection.authorization_required">;
+    readonly "connection.authorization_pending"?: TeamsEventHandler<"connection.authorization_pending">;
+    readonly "connection.authorization_completed"?: TeamsEventHandler<"connection.authorization_completed">;
+}
+/** Configuration for {@link teamsChannel}. */
+export interface TeamsChannelConfig {
+    readonly adaptiveCardVersion?: string;
+    readonly api?: Omit<TeamsApiOptions, "credentials">;
+    readonly credentials?: TeamsChannelCredentials;
+    readonly events?: TeamsChannelEvents;
+    readonly files?: TeamsFilesConfig;
+    /** Override the default webhook route path (`/ash/v1/teams`). */
+    readonly route?: string;
+    /**
+     * Inbound message hook. Defaults to user-scoped Teams auth and
+     * mention-gated dispatch outside personal chats.
+     */
+    onMessage?(ctx: TeamsContext, message: TeamsMessageActivity): TeamsInboundResultOrPromise;
+    /**
+     * Handler for non-HITL Teams invoke activities. Return a response body,
+     * a full Response, or `null`/`undefined` for a generic 200 OK.
+     */
+    onInvoke?(ctx: TeamsContext, activity: TeamsInvokeActivity): TeamsInvokeResultOrPromise;
+}
+/** Low-level Teams handle exposed to hooks and event handlers. */
+export interface TeamsHandle {
+    readonly channelId: string | undefined;
+    readonly conversationId: string;
+    readonly conversationType: string | undefined;
+    readonly replyToActivityId: string | undefined;
+    readonly serviceUrl: string;
+    readonly teamId: string | undefined;
+    readonly tenantId: string | undefined;
+    /** Raw Bot Connector API escape hatch. */
+    request(path: string, body: TeamsOutboundActivity | JsonObject, options?: TeamsRequestOptions): Promise<TeamsApiResponse>;
+    /** Sends a Bot Framework activity to the current conversation. */
+    sendActivity(activity: TeamsMessageBody | TeamsOutboundActivity | string): Promise<TeamsPostedActivity>;
+    /** Sends a Bot Framework reply to the current thread anchor. */
+    replyToActivity(activity: TeamsMessageBody | TeamsOutboundActivity | string): Promise<TeamsPostedActivity>;
+    /** Updates a previously sent bot activity. */
+    updateActivity(activityId: string, activity: TeamsMessageBody | TeamsOutboundActivity | string): Promise<TeamsPostedActivity>;
+    /** Triggers Teams' typing indicator. Failures are swallowed by the thread helper. */
+    startTyping(): Promise<void>;
+}
+/** Conversation-scoped Teams operations. */
+export interface TeamsThread {
+    /** Builds a Teams mention entity and matching text for one user. */
+    mentionUser(user: {
+        readonly id: string;
+        readonly name?: string;
+    }): TeamsMention;
+    /** Posts a message in the current Teams conversation/thread. */
+    post(message: string | TeamsMessageBody): Promise<TeamsPostedActivity>;
+    /** Starts Teams' typing indicator. Failures are swallowed. */
+    startTyping(): Promise<void>;
+    /** Updates a previously sent bot activity. */
+    update(activityId: string, message: string | TeamsMessageBody): Promise<TeamsPostedActivity>;
+}
+/** Options for {@link TeamsHandle.request}. */
+export interface TeamsRequestOptions {
+    readonly method?: "DELETE" | "GET" | "POST" | "PUT";
+}
+/** Concrete return type of {@link teamsChannel}. */
+export interface TeamsChannel extends Channel<TeamsChannelState>, TypedReceiveRoute<TeamsReceiveArgs> {
+}
+/** Teams channel factory for Bot Framework Activities and proactive messages. */
+export declare function teamsChannel(config?: TeamsChannelConfig): TeamsChannel;
+export {};

package/dist/src/public/channels/teams/teamsChannel.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{parseJsonObject}from"#shared/json.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{callTeamsConnectorApi,normalizeTeamsPostInput,replyToTeamsActivity,sendTeamsActivity,teamsContinuationToken,triggerTeamsTypingIndicator,updateTeamsActivity}from"#public/channels/teams/api.js";import{deriveTeamsInputResponses,isTeamsInputResponseActivity,teamsInvokeResponse}from"#public/channels/teams/hitl.js";import{parseTeamsActivity,prependTeamsContext,teamsThreadRootActivityId}from"#public/channels/teams/inbound.js";import{buildTeamsTurnMessage,collectTeamsFileParts,createTeamsFetchFile,normalizeTeamsFilesPolicy}from"#public/channels/teams/attachments.js";import{defaultEvents,defaultOnMessage,teamsMentionUser}from"#public/channels/teams/defaults.js";import{verifyTeamsRequest}from"#public/channels/teams/verify.js";var log=createLogger(`teams.channel`);function teamsChannel(e={}){let i=normalizeTeamsFilesPolicy(e.files),a=e.onMessage??defaultOnMessage,o={...defaultEvents,...e.events};return defineChannel({kindHint:`teams`,state:initialTeamsState(),fetchFile:createTeamsFetchFile(i),context(t,n){return rebuildTeamsContext(t,n,e)},routes:[POST(e.route??`/ash/v1/teams`,async(n,{send:r,waitUntil:o})=>{let s=await verifyInbound(n,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 Teams body is not valid JSON`,{error:e}),teamsOk()}let l=parseTeamsActivity(c);return l===null?teamsOk():l.type===`message`?(o(dispatchMessage({activity:l,config:e,filesPolicy:i,onMessage:a,send:r})),teamsOk()):l.type===`invoke`?handleInvoke({activity:l,config:e,send:r,waitUntil:o}):teamsOk()})],async receive(t,{send:n}){let r=t.args,i=readString(r.serviceUrl),a=readString(r.conversationId);if(!i||!a)throw Error(`teamsChannel().receive requires args.serviceUrl and args.conversationId.`);let o=readString(r.conversationType)??null,s=readString(r.replyToActivityId)??null,l=r.initialMessage;if(l!==void 0&&s!==null)throw Error("teamsChannel().receive: `replyToActivityId` and `initialMessage` are mutually exclusive.");let u={...initialTeamsState(),channelId:readString(r.channelId)??null,conversationId:a,conversationType:o,replyToActivityId:s,serviceUrl:i,teamId:readString(r.teamId)??null,tenantId:readString(r.tenantId)??null};if(l!==void 0){let t=await buildTeamsBinding({config:e,state:u}).thread.post(l);o!==`personal`&&t.id&&(s=t.id,u.replyToActivityId=t.id)}return n(t.message,{auth:t.auth,continuationToken:teamsContinuationToken({conversationId:a,replyToActivityId:s,tenantId:u.tenantId}),state:u})},events:o})}function rebuildTeamsContext(e,t,n){return{...buildTeamsBinding({config:n,session:t,state:e}),adaptiveCardVersion:n.adaptiveCardVersion??`1.5`,session:t,state:e}}function buildTeamsBinding(e){let t=buildTeamsHandle(e);return{teams:t,thread:{mentionUser:teamsMentionUser,post(e){return t.sendActivity(e)},async startTyping(){try{await t.startTyping()}catch(e){log.debug(`Teams typing indicator failed — swallowed`,{error:e})}},update(e,n){return t.updateActivity(e,n)}}}}function buildTeamsHandle(e){let t=e.state,n=e.config.api,r=e.config.credentials;function requireAddress(){let e=t.conversationId??``,n=t.serviceUrl??``;if(!e||!n)throw Error(`teamsChannel: missing serviceUrl or conversationId for outbound message.`);return{conversationId:e,serviceUrl:n}}function anchor(n){if(!n.id||t.replyToActivityId||t.conversationType===`personal`)return;t.replyToActivityId=n.id;let r=t.conversationId;r&&e.session?.setContinuationToken(teamsContinuationToken({conversationId:r,replyToActivityId:n.id,tenantId:t.tenantId}))}async function send(e){let i=requireAddress(),a=buildOutboundActivity(t,e),c=t.replyToActivityId===null?await sendTeamsActivity({...n,body:a,credentials:r,conversationId:i.conversationId,serviceUrl:i.serviceUrl}):await replyToTeamsActivity({...n,body:a,credentials:r,activityId:t.replyToActivityId,conversationId:i.conversationId,serviceUrl:i.serviceUrl});return anchor(c),c}return{channelId:t.channelId??void 0,conversationId:t.conversationId??``,conversationType:t.conversationType??void 0,replyToActivityId:t.replyToActivityId??void 0,serviceUrl:t.serviceUrl??``,teamId:t.teamId??void 0,tenantId:t.tenantId??void 0,request(e,t,a){let o=requireAddress();return callTeamsConnectorApi({...n,body:t,credentials:r,method:a?.method,path:e,serviceUrl:o.serviceUrl})},sendActivity:send,replyToActivity(e){let i=requireAddress(),a=t.replyToActivityId??``;if(!a)throw Error(`teamsChannel: missing reply activity id.`);return replyToTeamsActivity({...n,body:buildOutboundActivity(t,e),credentials:r,activityId:a,conversationId:i.conversationId,serviceUrl:i.serviceUrl})},updateActivity(e,i){let a=requireAddress();return updateTeamsActivity({...n,body:buildOutboundActivity(t,i),credentials:r,activityId:e,conversationId:a.conversationId,serviceUrl:a.serviceUrl})},async startTyping(){let e=requireAddress();await triggerTeamsTypingIndicator({...n,credentials:r,conversationId:e.conversationId,serviceUrl:e.serviceUrl})}}}async function verifyInbound(e,t){try{return await verifyTeamsRequest(e,{appId:t?.webhookVerifier?void 0:t?.appId,webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`teams inbound verification failed`,{error:e}),null}}async function dispatchMessage(e){let t=stateFromActivity(e.activity),n=buildTeamsBinding({config:e.config,state:t}),r;try{r=await e.onMessage(n,e.activity)}catch(e){log.error(`Teams message handler failed`,{error:e});return}if(r==null)return;let i=collectTeamsFileParts(e.activity.attachments,e.filesPolicy),a=prependTeamsContext(buildTeamsTurnMessage(e.activity.text,i),{activityId:e.activity.id,channelId:e.activity.teamsChannelId,conversationId:e.activity.conversation.id,conversationType:e.activity.conversationType,scope:e.activity.scope,teamId:e.activity.teamId,tenantId:e.activity.tenantId,userId:e.activity.from.id,userName:e.activity.from.name});try{await e.send({message:a,modelContext:r.modelContext},{auth:r.auth,continuationToken:stateToken(t),state:t})}catch(e){log.error(`Teams message delivery failed`,{error:e})}}async function handleInvoke(e){if(isTeamsInputResponseActivity(e.activity))return e.waitUntil(dispatchInputResponses({activity:e.activity,send:e.send})),Response.json(teamsInvokeResponse());if(e.config.onInvoke===void 0)return teamsOk();let t=buildTeamsBinding({config:e.config,state:stateFromActivity(e.activity)}),n=await e.config.onInvoke(t,e.activity);return n instanceof Response?n:n&&typeof n==`object`?Response.json(n):teamsOk()}async function dispatchInputResponses(e){let t=deriveTeamsInputResponses(e.activity);if(t.length===0)return;let n=stateFromActivity(e.activity);try{await e.send({inputResponses:t},{auth:null,continuationToken:stateToken(n),state:n})}catch(e){log.error(`Teams input response delivery failed`,{error:e})}}function stateFromActivity(e){return{bot:e.recipient,channelId:e.teamsChannelId??null,conversationId:e.conversation.id,conversationType:e.conversationType??e.scope,pendingAuthActivityId:null,replyToActivityId:teamsThreadRootActivityId(e),serviceUrl:e.serviceUrl,teamId:e.teamId??null,tenantId:e.tenantId??null,triggeringUser:e.from}}function initialTeamsState(){return{bot:null,channelId:null,conversationId:null,conversationType:null,pendingAuthActivityId:null,replyToActivityId:null,serviceUrl:null,teamId:null,tenantId:null,triggeringUser:null}}function stateToken(e){let t=e.conversationId??``;if(!t)throw Error(`teamsChannel: missing conversation id.`);return teamsContinuationToken({conversationId:t,replyToActivityId:e.replyToActivityId,tenantId:e.tenantId})}function buildOutboundActivity(e,t){if(typeof t!=`string`&&`type`in t&&t.type===`typing`)return t;let n=normalizeTeamsPostInput(t),r=mergeChannelData(e,n.channelData);return{...n,channelData:r,conversation:e.conversationId?{id:e.conversationId}:void 0,from:e.bot??void 0,replyToId:e.replyToActivityId??void 0,type:`message`}}function mergeChannelData(e,n){let r={...n};return e.tenantId&&(r.tenant={id:e.tenantId}),e.teamId&&(r.team={id:e.teamId}),e.channelId&&(r.channel={id:e.channelId}),Object.keys(r).length>0?parseJsonObject(r):void 0}function teamsOk(){return new Response(`ok`,{status:200})}function readString(e){return typeof e==`string`&&e.length>0?e:void 0}export{teamsChannel};

package/dist/src/public/channels/teams/verify.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Microsoft Teams inbound Bot Framework request verification.
+ *
+ * Teams sends bot activities through the Bot Connector service. Ash verifies
+ * the bearer JWT against Bot Connector OpenID keys and the bot's Microsoft
+ * app id before dispatching any activity to the runtime.
+ */
+import type { JWTPayload } from "#compiled/jose/index.js";
+import { type TeamsAppId, type TeamsFetch } from "#public/channels/teams/api.js";
+/**
+ * Caller-supplied inbound webhook verifier. Used as an alternative to
+ * Bot Connector JWT verification when a trusted integration authenticates
+ * forwarded requests before they reach Ash.
+ */
+export type TeamsWebhookVerifier = (request: Request, body: string) => unknown | Promise<unknown>;
+/** Options for {@link verifyTeamsRequest}. */
+export interface TeamsVerifyOptions {
+    readonly appId?: TeamsAppId;
+    readonly fetch?: TeamsFetch;
+    readonly jwksUrl?: string;
+    /** Max allowed clock skew, in seconds. Defaults to 5 minutes. */
+    readonly maxSkewSeconds?: number;
+    readonly openIdMetadataUrl?: string;
+    readonly webhookVerifier?: TeamsWebhookVerifier;
+}
+/** Options for {@link verifyTeamsJwt}. */
+export interface TeamsJwtVerifyOptions {
+    readonly appId?: TeamsAppId;
+    readonly fetch?: TeamsFetch;
+    readonly jwksUrl?: string;
+    /** Max allowed clock skew, in seconds. Defaults to 5 minutes. */
+    readonly maxSkewSeconds?: number;
+    readonly openIdMetadataUrl?: string;
+}
+/**
+ * Verifies an inbound Teams request and returns the raw body.
+ *
+ * Throws when no verifier/app id is configured, the bearer token is missing,
+ * metadata or keys cannot be loaded, or JWT verification fails.
+ */
+export declare function verifyTeamsRequest(request: Request, options: TeamsVerifyOptions): Promise<string>;
+/** Verifies one Bot Connector JWT and returns its payload. */
+export declare function verifyTeamsJwt(token: string, options: TeamsJwtVerifyOptions): Promise<JWTPayload>;

package/dist/src/public/channels/teams/verify.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{isObject}from"#shared/guards.js";import{importJWK,jwtVerify}from"#compiled/jose/index.js";import{resolveTeamsAppId}from"#public/channels/teams/api.js";var log=createLogger(`teams.verify`),DEFAULT_BOT_CONNECTOR_OPENID_METADATA_URL=`https://login.botframework.com/v1/.well-known/openidconfiguration`,BOT_CONNECTOR_ISSUER=`https://api.botframework.com`;async function verifyTeamsRequest(e,t){let n=await e.text();if(t.webhookVerifier!==void 0){let r=await t.webhookVerifier(e,n);if(!r)throw Error(`teamsChannel: inbound webhook verifier rejected the request.`);return typeof r==`string`?r:n}let r=readBearerToken(e.headers.get(`authorization`)??``);if(!r)throw Error(`teamsChannel: inbound request missing bearer token.`);return await verifyTeamsJwt(r,t),n}async function verifyTeamsJwt(e,t){let a=await resolveTeamsAppId(t.appId),o=await loadJwks(t);return(await jwtVerify(e,async e=>importJWK(selectJwk(o,e),typeof e.alg==`string`?e.alg:void 0),{audience:a,clockTolerance:t.maxSkewSeconds??300,issuer:BOT_CONNECTOR_ISSUER})).payload}function readBearerToken(e){let[t,n]=e.split(/\s+/,2);return t?.toLowerCase()!==`bearer`||!n?null:n}async function loadJwks(e){let n=e.fetch??fetch,r=await n(e.jwksUrl??await loadJwksUrl(e,n),{headers:{accept:`application/json`}});if(!r.ok)throw Error(`Teams JWKS route returned HTTP ${r.status}.`);let i=await r.json();if(!isObject(i)||!Array.isArray(i.keys))throw Error(`Teams JWKS response is malformed.`);return i.keys.filter(isObject)}async function loadJwksUrl(e,n){let r=await n(e.openIdMetadataUrl??DEFAULT_BOT_CONNECTOR_OPENID_METADATA_URL,{headers:{accept:`application/json`}});if(!r.ok)throw Error(`Teams OpenID metadata route returned HTTP ${r.status}.`);let i=await r.json();if(!isObject(i)||typeof i.jwks_uri!=`string`)throw Error(`Teams OpenID metadata response is missing jwks_uri.`);return i.jwks_uri}function selectJwk(e,t){let n=typeof t.kid==`string`?t.kid:void 0,r=typeof t.x5t==`string`?t.x5t:void 0,i=e.find(e=>n!==void 0&&e.kid===n||r!==void 0&&e.x5t===r)??(e.length===1?e[0]:void 0);if(i===void 0)throw log.debug(`Teams JWT key not found`,{kid:n,x5t:r}),Error(`teamsChannel: inbound JWT key was not found in JWKS.`);return i}export{verifyTeamsJwt,verifyTeamsRequest};

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

@@ -0,0 +1,107 @@
+/**
+ * Minimal Telegram Bot API wrapper used by the Telegram channel.
+ *
+ * The channel talks directly to Telegram's JSON HTTP API instead of
+ * exposing a third-party SDK through Ash public surfaces.
+ */
+import { type JsonObject } from "#shared/json.js";
+/** Telegram bot token, materialized directly or from an async secret provider. */
+export type TelegramBotToken = string | (() => string | Promise<string>);
+/** Fetch implementation override used by tests or non-standard runtimes. */
+export type TelegramFetch = typeof fetch;
+/** Credentials used by the native Telegram channel. */
+export interface TelegramCredentials {
+    readonly botToken?: TelegramBotToken;
+}
+/** Shared Telegram API options. */
+export interface TelegramApiOptions {
+    readonly apiBaseUrl?: string;
+    readonly credentials?: TelegramCredentials;
+    readonly fetch?: TelegramFetch;
+    readonly fileBaseUrl?: string;
+}
+/** Raw Telegram API response body. */
+export interface TelegramApiResponse {
+    readonly body: unknown;
+    readonly ok: boolean;
+    readonly status: number;
+}
+/** Minimal Telegram message object returned by channel write operations. */
+export interface TelegramMessageResult {
+    /** Telegram message id, when Telegram returned one. */
+    readonly id: string;
+    /** Telegram chat id associated with the message, when Telegram returned one. */
+    readonly chatId?: string;
+    /** Telegram's raw JSON response. */
+    readonly raw: unknown;
+}
+/** JSON body supported by Telegram sendMessage endpoints used by Ash. */
+export interface TelegramMessageBody {
+    readonly disable_notification?: boolean;
+    readonly link_preview_options?: Readonly<Record<string, unknown>>;
+    readonly message_thread_id?: number;
+    readonly protect_content?: boolean;
+    readonly reply_markup?: Readonly<Record<string, unknown>>;
+    readonly reply_parameters?: Readonly<Record<string, unknown>>;
+    readonly text: string;
+}
+/** Telegram's documented text-message cap. */
+export declare const TELEGRAM_MESSAGE_TEXT_MAX_LENGTH = 4096;
+/**
+ * Builds the channel-local continuation token.
+ *
+ * Private chats normally use only `chatId`; group and forum-topic
+ * sessions include `messageThreadId` and `conversationId` so multiple
+ * bot conversations in the same chat do not collapse into one session.
+ */
+export declare function telegramContinuationToken(input: {
+    readonly chatId: number | string;
+    readonly conversationId?: number | string;
+    readonly messageThreadId?: number;
+}): string;
+/** Resolves a Telegram bot token, falling back to `TELEGRAM_BOT_TOKEN`. */
+export declare function resolveTelegramBotToken(token?: TelegramBotToken): Promise<string>;
+/** Low-level Telegram JSON API call. */
+export declare function callTelegramApi(input: {
+    readonly apiBaseUrl?: string;
+    readonly body?: JsonObject;
+    readonly botToken?: TelegramBotToken;
+    readonly fetch?: TelegramFetch;
+    readonly method: string;
+}): Promise<TelegramApiResponse>;
+/** Sends a text message through Telegram's sendMessage method. */
+export declare function sendTelegramMessage(input: TelegramApiOptions & {
+    readonly body: TelegramMessageBody;
+    readonly chatId: number | string;
+}): Promise<TelegramMessageResult>;
+/** Triggers Telegram's chat action indicator, usually `typing`. */
+export declare function sendTelegramChatAction(input: TelegramApiOptions & {
+    readonly action: string;
+    readonly chatId: number | string;
+    readonly messageThreadId?: number;
+}): Promise<TelegramApiResponse>;
+/** Answers a Telegram callback query so the user's client clears the spinner. */
+export declare function answerTelegramCallbackQuery(input: TelegramApiOptions & {
+    readonly callbackQueryId: string;
+    readonly showAlert?: boolean;
+    readonly text?: string;
+}): Promise<TelegramApiResponse>;
+/** Edits only the reply markup for one Telegram message. */
+export declare function editTelegramMessageReplyMarkup(input: TelegramApiOptions & {
+    readonly chatId: number | string;
+    readonly messageId: number | string;
+    readonly replyMarkup?: Readonly<Record<string, unknown>>;
+}): Promise<TelegramApiResponse>;
+/** Resolves Telegram file metadata through `getFile`. */
+export declare function getTelegramFile(input: TelegramApiOptions & {
+    readonly fileId: string;
+}): Promise<{
+    readonly filePath: string;
+    readonly raw: unknown;
+}>;
+/** Downloads file bytes from Telegram's file endpoint. */
+export declare function downloadTelegramFile(input: TelegramApiOptions & {
+    readonly filePath: string;
+}): Promise<Response>;
+/** Splits text into chunks Telegram will accept as individual sendMessage calls. */
+export declare function splitTelegramMessageText(text: string): readonly string[];

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

@@ -0,0 +1,2 @@
+import{isObject}from"#shared/guards.js";import{parseJsonObject}from"#shared/json.js";var TELEGRAM_MESSAGE_TEXT_MAX_LENGTH=4096;function telegramContinuationToken(e){let t=e.messageThreadId===void 0?``:String(e.messageThreadId),n=e.conversationId===void 0?``:String(e.conversationId);return`${String(e.chatId)}:${t}:${n}`}async function resolveTelegramBotToken(e){let t=e??process.env.TELEGRAM_BOT_TOKEN;if(!t)throw Error(`TELEGRAM_BOT_TOKEN is required.`);return typeof t==`function`?await t():t}async function callTelegramApi(e){let n=e.fetch??fetch,r=await resolveTelegramBotToken(e.botToken),i={headers:{"content-type":`application/json; charset=utf-8`},method:`POST`};e.body!==void 0&&(i.body=JSON.stringify(parseJsonObject(e.body)));let a=await n(`${e.apiBaseUrl??`https://api.telegram.org`}/bot${r}/${encodeURIComponent(e.method)}`,i);return{body:await parseResponseBody(a),ok:a.ok,status:a.status}}async function sendTelegramMessage(e){let t=await callTelegramApi({apiBaseUrl:e.apiBaseUrl,body:normalizeTelegramMessageBody(e.body,e.chatId),botToken:e.credentials?.botToken,fetch:e.fetch,method:`sendMessage`});if(!t.ok)throw Error(`Telegram sendMessage failed with HTTP ${t.status}.`);return toTelegramMessageResult(t.body)}async function sendTelegramChatAction(e){return callTelegramApi({apiBaseUrl:e.apiBaseUrl,body:parseJsonObject({action:e.action,chat_id:e.chatId,message_thread_id:e.messageThreadId}),botToken:e.credentials?.botToken,fetch:e.fetch,method:`sendChatAction`})}async function answerTelegramCallbackQuery(e){return callTelegramApi({apiBaseUrl:e.apiBaseUrl,body:parseJsonObject({callback_query_id:e.callbackQueryId,show_alert:e.showAlert,text:e.text}),botToken:e.credentials?.botToken,fetch:e.fetch,method:`answerCallbackQuery`})}async function editTelegramMessageReplyMarkup(e){return callTelegramApi({apiBaseUrl:e.apiBaseUrl,body:parseJsonObject({chat_id:e.chatId,message_id:Number(e.messageId),reply_markup:e.replyMarkup}),botToken:e.credentials?.botToken,fetch:e.fetch,method:`editMessageReplyMarkup`})}async function getTelegramFile(t){let n=await callTelegramApi({apiBaseUrl:t.apiBaseUrl,body:{file_id:t.fileId},botToken:t.credentials?.botToken,fetch:t.fetch,method:`getFile`});if(!n.ok)throw Error(`Telegram getFile failed with HTTP ${n.status}.`);let r=isObject(n.body)?n.body:{},i=isObject(r.result)?r.result:{};if(typeof i.file_path!=`string`||i.file_path.length===0)throw Error(`Telegram getFile response did not include result.file_path.`);return{filePath:i.file_path,raw:n.body}}async function downloadTelegramFile(e){let t=e.fetch??fetch,n=await resolveTelegramBotToken(e.credentials?.botToken);return t(`${e.fileBaseUrl??e.apiBaseUrl??`https://api.telegram.org`}/file/bot${n}/${e.filePath}`)}function splitTelegramMessageText(e){if(e.length<=4096)return[e];let t=[],r=e;for(;r.length>TELEGRAM_MESSAGE_TEXT_MAX_LENGTH;){let e=r.lastIndexOf(`
+`,TELEGRAM_MESSAGE_TEXT_MAX_LENGTH);e<=0&&(e=r.lastIndexOf(` `,TELEGRAM_MESSAGE_TEXT_MAX_LENGTH)),e<=0&&(e=TELEGRAM_MESSAGE_TEXT_MAX_LENGTH),t.push(r.slice(0,e).trimEnd()),r=r.slice(e).trimStart()}return t.push(r),t}function normalizeTelegramMessageBody(e,n){return parseJsonObject({...e,chat_id:n})}function toTelegramMessageResult(t){let n=isObject(t)?t:{},r=isObject(n.result)?n.result:{},i=isObject(r.chat)?r.chat:{};return{chatId:typeof i.id==`number`||typeof i.id==`string`?String(i.id):void 0,id:typeof r.message_id==`number`||typeof r.message_id==`string`?String(r.message_id):``,raw:t}}async function parseResponseBody(e){let t=await e.text();if(!t)return null;try{return JSON.parse(t)}catch{return t}}export{TELEGRAM_MESSAGE_TEXT_MAX_LENGTH,answerTelegramCallbackQuery,callTelegramApi,downloadTelegramFile,editTelegramMessageReplyMarkup,getTelegramFile,resolveTelegramBotToken,sendTelegramChatAction,sendTelegramMessage,splitTelegramMessageText,telegramContinuationToken};

package/dist/src/public/channels/telegram/attachments.d.ts

@@ -0,0 +1,23 @@
+import type { FilePart, UserContent } from "ai";
+import type { FetchFileResult } from "#channel/adapter.js";
+import { type TelegramApiOptions } from "#public/channels/telegram/api.js";
+import type { TelegramAttachment, TelegramMessage } from "#public/channels/telegram/inbound.js";
+import { type UploadPolicy } from "#public/channels/upload-policy.js";
+/** URL protocol used by the channel to defer Telegram file downloads to `fetchFile`. */
+export declare const TELEGRAM_FILE_URL_PROTOCOL = "telegram-file:";
+/** Emits one {@link FilePart} per supported Telegram attachment. */
+export declare function collectTelegramFileParts(attachments: readonly TelegramAttachment[], policy: UploadPolicy): FilePart[];
+/** Combines text/caption + file parts into the {@link UserContent} shape the harness expects. */
+export declare function buildTelegramTurnMessage(message: Pick<TelegramMessage, "caption" | "text">, fileParts: readonly FilePart[]): string | UserContent;
+/** Creates a `fetchFile` function for Telegram-owned file URLs. */
+export declare function createTelegramFetchFile(input: {
+    readonly api?: Omit<TelegramApiOptions, "credentials">;
+    readonly credentials?: TelegramApiOptions["credentials"];
+    readonly policy: UploadPolicy;
+}): (url: string) => Promise<FetchFileResult | null>;
+/** Builds the internal URL used to defer a Telegram file download. */
+export declare function createTelegramFileUrl(input: {
+    readonly fileId: string;
+    readonly filename?: string;
+    readonly mediaType?: string;
+}): URL;

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

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{evaluateFilePart,formatUploadPolicyViolation,isMediaTypeAllowed,isUploadsDisabled}from"#public/channels/upload-policy.js";import{downloadTelegramFile,getTelegramFile}from"#public/channels/telegram/api.js";var log=createLogger(`telegram.attachments`),TELEGRAM_FILE_URL_PROTOCOL=`telegram-file:`;function collectTelegramFileParts(e,t){if(isUploadsDisabled(t))return[];let r=[];for(let i of e){let e=toTelegramFilePart(i,r.length);if(e===null)continue;let a=evaluateTelegramFilePart(e,i.size,t);if(a!==null){log.warn(`dropped attachment — ${formatUploadPolicyViolation(a)}`,{fileId:i.fileId,name:i.fileName});continue}r.push(e)}return r}function buildTelegramTurnMessage(e,t){let n=e.text||e.caption;return t.length===0?n:n.trim().length===0?[...t]:[{type:`text`,text:n},...t]}function createTelegramFetchFile(e){return async r=>{let i=parseTelegramFileUrl(r);if(i===null)return null;let o=await getTelegramFile({apiBaseUrl:e.api?.apiBaseUrl,credentials:e.credentials,fetch:e.api?.fetch,fileId:i.fileId}),s=await downloadTelegramFile({apiBaseUrl:e.api?.apiBaseUrl,credentials:e.credentials,fetch:e.api?.fetch,fileBaseUrl:e.api?.fileBaseUrl,filePath:o.filePath});if(!s.ok)throw Error(`Telegram file fetch returned HTTP ${s.status} for ${r}.`);let c=Buffer.from(await s.arrayBuffer()),l=s.headers.get(`content-type`)??i.mediaType??`application/octet-stream`,u={bytes:c,filename:i.filename,mediaType:l},d=evaluateFilePart({data:u.bytes,filename:u.filename,mediaType:l,type:`file`},e.policy);if(d!==null)throw Error(`Telegram file rejected — ${formatUploadPolicyViolation(d)}`);return u}}function createTelegramFileUrl(e){let t=new URLSearchParams;e.filename!==void 0&&t.set(`filename`,e.filename),e.mediaType!==void 0&&t.set(`mediaType`,e.mediaType);let n=t.size>0?`?${t.toString()}`:``;return new URL(`${TELEGRAM_FILE_URL_PROTOCOL}${encodeURIComponent(e.fileId)}${n}`)}function toTelegramFilePart(e,t){let n=e.mediaType??(e.kind===`photo`?`image/jpeg`:`application/octet-stream`),r=e.fileName??(e.kind===`photo`?`photo-${t}.jpg`:`file-${t}`);return{data:createTelegramFileUrl({fileId:e.fileId,filename:r,mediaType:n}),filename:r,mediaType:n,type:`file`}}function parseTelegramFileUrl(e){let t;try{t=new URL(e)}catch{return null}if(t.protocol!==`telegram-file:`)return null;let n=decodeURIComponent(t.pathname);return n?{fileId:n,filename:t.searchParams.get(`filename`)??void 0,mediaType:t.searchParams.get(`mediaType`)??void 0}:null}function evaluateTelegramFilePart(e,n,i){return i===`disabled`||!isMediaTypeAllowed(e.mediaType,i)?evaluateFilePart(e,i):n!==void 0&&n>i.maxBytes?{byteLength:n,filename:e.filename,kind:`too-large`,limit:i.maxBytes,mediaType:e.mediaType}:null}export{TELEGRAM_FILE_URL_PROTOCOL,buildTelegramTurnMessage,collectTelegramFileParts,createTelegramFetchFile,createTelegramFileUrl};

package/dist/src/public/channels/telegram/defaults.d.ts

@@ -0,0 +1,9 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { TelegramMessage } from "#public/channels/telegram/inbound.js";
+import type { TelegramChannelEvents, TelegramContext, TelegramInboundResult } from "#public/channels/telegram/telegramChannel.js";
+/** Default auth projection for Telegram webhook actors. */
+export declare function defaultTelegramAuth(message: TelegramMessage): SessionAuthContext | null;
+/** Default inbound message hook: dispatch allowed messages with Telegram user auth. */
+export declare function defaultOnMessage(ctx: TelegramContext, message: TelegramMessage): Promise<TelegramInboundResult>;
+/** Built-in Telegram event handlers for typing, replies, HITL, and terminal errors. */
+export declare const defaultEvents: TelegramChannelEvents;

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

@@ -0,0 +1,3 @@
+import{extractErrorId,formatErrorHint}from"#internal/logging.js";import{registerTelegramFreeformPrompt,renderTelegramInputRequest}from"#public/channels/telegram/hitl.js";function defaultTelegramAuth(e){let t=e.from;if(!t)return null;let n={chat_id:e.chat.id,chat_type:e.chat.type,message_id:e.messageId,user_id:t.id};e.chat.title!==void 0&&(n.chat_title=e.chat.title),e.messageThreadId!==void 0&&(n.message_thread_id=String(e.messageThreadId)),t.username!==void 0&&(n.username=t.username);let r=e.chat.type===`group`||e.chat.type===`supergroup`,i=r?`telegram:${e.chat.id}:${t.id}`:`telegram:${t.id}`;return{attributes:n,authenticator:`telegram-webhook`,issuer:r?`telegram:${e.chat.id}`:`telegram`,principalId:i,principalType:t.isBot?`service`:`user`}}async function defaultOnMessage(e,t){return shouldDispatchTelegramMessage(t,e.telegram.botUsername)?(await e.telegram.startTyping(),{auth:defaultTelegramAuth(t)}):null}var defaultEvents={async"turn.started"(e,t){await t.telegram.startTyping()},async"actions.requested"(e,t){await t.telegram.startTyping()},async"input.requested"(e,t){for(let i of e.requests){let e=renderTelegramInputRequest(i,t.state),a=await t.telegram.post({reply_markup:e.replyMarkup,text:e.text});e.freeformRequestId!==void 0&&a.id&&registerTelegramFreeformPrompt(t.state,{messageId:a.id,requestId:e.freeformRequestId})}},async"message.completed"(e,t){e.finishReason===`tool-calls`||!e.message||await t.telegram.post(e.message)},async"turn.failed"(n,r){let i=formatErrorHint(n),a=extractErrorId(n.details);await r.telegram.post([`I hit an error while handling your request${i}.`,``,`Please try again, rephrase, or reach out if it keeps failing.`,...a?[``,`Error id: ${a}`]:[]].join(`
+`))},async"session.failed"(n,r){let i=formatErrorHint(n),a=extractErrorId(n.details);await r.telegram.post([`This session could not recover from an error${i}.`,``,`Start a new message to continue.`,...a?[``,`Error id: ${a}`]:[]].join(`
+`))}};function shouldDispatchTelegramMessage(e,t){if(e.from?.isBot===!0||e.chat.type===`channel`)return!1;let n=e.text||e.caption;return n.trim().length>0||e.attachments.length>0?!!(e.chat.type===`private`||e.replyToMessage?.from?.isBot===!0||isBotCommand(n,t)||t!==void 0&&mentionsBot(n,t)):!1}function isBotCommand(e,t){let n=/^\/(?<command>[A-Za-z0-9_]+)(?:@(?<target>[A-Za-z0-9_]+))?(?:\s|$)/u.exec(e);if(!n)return!1;let r=n.groups?.target;return r===void 0?!0:t!==void 0&&r.toLowerCase()===t.toLowerCase()}function mentionsBot(e,t){return e.toLowerCase().includes(`@${t.toLowerCase()}`)}export{defaultEvents,defaultOnMessage,defaultTelegramAuth};

package/dist/src/public/channels/telegram/hitl.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Telegram HITL inline keyboard rendering + compact callback decode helpers.
+ *
+ * Telegram limits `InlineKeyboardButton.callback_data` to 64 bytes, so
+ * Ash stores compact callback ids in durable channel state and remaps
+ * them back to full input responses inside the channel deliver hook.
+ */
+import type { InputRequest, InputResponse } from "#runtime/input/types.js";
+/** Prefix used in Telegram callback_data values generated by Ash. */
+export declare const TELEGRAM_HITL_CALLBACK_PREFIX = "ash:";
+/** Synthetic request id prefix sent through `send()` for callback queries. */
+export declare const TELEGRAM_CALLBACK_RESPONSE_PREFIX = "telegram_callback:";
+/** Synthetic request id prefix sent through `send()` for replies to ForceReply prompts. */
+export declare const TELEGRAM_REPLY_RESPONSE_PREFIX = "telegram_reply:";
+/** Minimal durable state shape used by the HITL helpers. */
+export interface TelegramHitlState {
+    hitlCallbacks?: Record<string, InputResponse>;
+    nextHitlCallbackId?: number;
+    pendingFreeformReplies?: Record<string, string>;
+}
+/** Rendered Telegram message body for one pending input request. */
+export interface TelegramInputRequestMessage {
+    readonly freeformRequestId?: string;
+    readonly replyMarkup?: Readonly<Record<string, unknown>>;
+    readonly text: string;
+}
+/** Renders one `InputRequest` as Telegram inline keyboard or ForceReply markup. */
+export declare function renderTelegramInputRequest(request: InputRequest, state: TelegramHitlState): TelegramInputRequestMessage;
+/** Records the Telegram message id that a freeform answer should reply to. */
+export declare function registerTelegramFreeformPrompt(state: TelegramHitlState, input: {
+    readonly messageId: string;
+    readonly requestId: string;
+}): void;
+/** Wraps Telegram callback data in an `InputResponse` shape for delivery. */
+export declare function telegramCallbackInputResponse(callbackData: string): InputResponse;
+/** Wraps a reply-to-message id in an `InputResponse` shape for delivery. */
+export declare function telegramReplyInputResponse(input: {
+    readonly messageId: string;
+    readonly text: string;
+}): InputResponse;
+/** True when an input response needs Telegram-specific durable-state remapping. */
+export declare function isTelegramSyntheticResponse(response: InputResponse): boolean;
+/** Remaps compact Telegram callback/reply ids into real Ash input responses. */
+export declare function resolveTelegramInputResponses(state: TelegramHitlState, responses: readonly InputResponse[]): InputResponse[];

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

@@ -0,0 +1 @@
+var TELEGRAM_HITL_CALLBACK_PREFIX=`ash:`,TELEGRAM_CALLBACK_RESPONSE_PREFIX=`telegram_callback:`,TELEGRAM_REPLY_RESPONSE_PREFIX=`telegram_reply:`,TELEGRAM_BUTTON_LABEL_MAX_LENGTH=64,TELEGRAM_INPUT_PLACEHOLDER_MAX_LENGTH=64,TELEGRAM_PROMPT_MAX_LENGTH=4e3,TELEGRAM_INLINE_ROW_SIZE=2;function renderTelegramInputRequest(e,t){let n=e.options;return n&&n.length>0?{replyMarkup:{inline_keyboard:chunk(n.map(n=>({callback_data:registerTelegramCallback(t,{optionId:n.id,requestId:e.requestId}),text:truncate(n.label,TELEGRAM_BUTTON_LABEL_MAX_LENGTH)})),TELEGRAM_INLINE_ROW_SIZE)},text:truncate(e.prompt,TELEGRAM_PROMPT_MAX_LENGTH)}:{freeformRequestId:e.requestId,replyMarkup:{force_reply:!0,input_field_placeholder:truncate(`Type your answer`,TELEGRAM_INPUT_PLACEHOLDER_MAX_LENGTH),selective:!0},text:truncate(e.prompt,TELEGRAM_PROMPT_MAX_LENGTH)}}function registerTelegramFreeformPrompt(e,t){e.pendingFreeformReplies={...e.pendingFreeformReplies,[t.messageId]:t.requestId}}function telegramCallbackInputResponse(e){return{optionId:`selected`,requestId:`${TELEGRAM_CALLBACK_RESPONSE_PREFIX}${e}`}}function telegramReplyInputResponse(e){return{requestId:`${TELEGRAM_REPLY_RESPONSE_PREFIX}${e.messageId}`,text:e.text}}function isTelegramSyntheticResponse(e){return e.requestId.startsWith(`telegram_callback:`)||e.requestId.startsWith(`telegram_reply:`)}function resolveTelegramInputResponses(e,r){let i=[];for(let a of r){if(a.requestId.startsWith(`telegram_callback:`)){let n=a.requestId.slice(TELEGRAM_CALLBACK_RESPONSE_PREFIX.length),r=e.hitlCallbacks?.[n];r!==void 0&&(i.push(r),delete e.hitlCallbacks?.[n]);continue}if(a.requestId.startsWith(`telegram_reply:`)){let t=a.requestId.slice(TELEGRAM_REPLY_RESPONSE_PREFIX.length),r=e.pendingFreeformReplies?.[t];r!==void 0&&a.text!==void 0&&(i.push({requestId:r,text:a.text}),delete e.pendingFreeformReplies?.[t]);continue}i.push(a)}return i}function registerTelegramCallback(t,n){let r=t.nextHitlCallbackId??0;t.nextHitlCallbackId=r+1;let i=`${TELEGRAM_HITL_CALLBACK_PREFIX}${r.toString(36)}`;return t.hitlCallbacks={...t.hitlCallbacks,[i]:n},i}function truncate(e,t){if(e.length<=t)return e;let n=Math.max(0,t-3);return`${e.slice(0,n).trimEnd()}...`}function chunk(e,t){let n=[];for(let r=0;r<e.length;r+=t)n.push(e.slice(r,r+t));return n}export{TELEGRAM_CALLBACK_RESPONSE_PREFIX,TELEGRAM_HITL_CALLBACK_PREFIX,TELEGRAM_REPLY_RESPONSE_PREFIX,isTelegramSyntheticResponse,registerTelegramFreeformPrompt,renderTelegramInputRequest,resolveTelegramInputResponses,telegramCallbackInputResponse,telegramReplyInputResponse};