experimental-ash 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # experimental-ash
 
+## 0.28.0
+
+### Minor Changes
+
+- 2e8ebcb: Add a native Microsoft Teams channel backed by the Bot Framework Activity and Connector protocols, including inbound verification, Teams conversation state, Adaptive Card HITL, proactive receive support, docs, tests, and smoke coverage.
+- 70018bd: Add a native Telegram channel for verified Bot API webhooks, Telegram delivery, HITL interactions, attachments, and proactive sessions.
+
 ## 0.27.0
 
 ### Minor Changes

package/dist/docs/public/channels/README.md

@@ -1,6 +1,6 @@
 ---
 title: "Channels"
-description: "Deliver your agent over HTTP, Slack, Discord, Twilio, and custom transports."
+description: "Deliver your agent over HTTP, Slack, Discord, Twilio, Telegram, Microsoft Teams, and custom transports."
 url: /channels
 ---
 
@@ -23,7 +23,7 @@ Ash ships the public HTTP protocol as channels:
 - `ashChannel({ auth })` for the built-in Ash protocol channel
 
 Ash also supports authored channels under `agent/channels/` for platform-specific integrations such
-as Slack, Discord, Twilio, or custom webhooks.
+as Slack, Discord, Twilio, Telegram, Microsoft Teams, or custom webhooks.
 
 ## Filesystem Shape
 
@@ -279,6 +279,53 @@ resolver when the allowed phone numbers come from dynamic state. Use `allowFrom:
 
 See [Twilio channel setup](./twilio.md) for webhook URLs, environment variables, and overrides.
 
+## Telegram Channels
+
+Telegram channels are authored with `telegramChannel()`:
+
+```ts
+import { telegramChannel } from "experimental-ash/channels/telegram";
+
+export default telegramChannel({
+  botUsername: "my_bot",
+});
+```
+
+The channel verifies Telegram's `X-Telegram-Bot-Api-Secret-Token` webhook header, accepts updates at
+`/ash/v1/telegram`, dispatches private messages and addressed group messages, and resolves HITL
+inline-keyboard callbacks and ForceReply answers back into Ash input responses. Private chats use
+chat-wide continuation tokens. Group, supergroup, and forum-topic sessions include the chat id,
+optional `message_thread_id`, and a conversation anchor so multiple bot conversations in the same
+chat do not collapse.
+
+Default delivery sends plain text through Telegram `sendMessage` with no `parse_mode`, splits text
+at Telegram's 4096-character limit, and uses best-effort `sendChatAction("typing")` progress
+indicators. Photos and documents are exposed as file parts and fetched through Telegram `getFile`
+when the model needs the bytes.
+
+See [Telegram channel setup](./telegram.md) for webhook registration, environment variables, group
+privacy notes, HITL behavior, attachments, and proactive sessions.
+
+## Microsoft Teams Channels
+
+Teams channels are authored with `teamsChannel()`:
+
+```ts
+import { teamsChannel } from "experimental-ash/channels/teams";
+
+export default teamsChannel();
+```
+
+The channel verifies Bot Connector bearer JWTs, accepts Teams Bot Framework Activity POSTs at
+`/ash/v1/teams`, dispatches personal messages and direct bot mentions, renders HITL prompts as
+Adaptive Cards, and sends agent replies through the Bot Framework Connector REST API. Personal chats
+resume by conversation id; channel and group-chat threads resume by conversation id plus root
+activity id.
+
+Proactive `receive(teams, args)` sessions require an existing conversation reference
+(`serviceUrl` and `conversationId`). See [Microsoft Teams channel setup](./teams.md) for Azure Bot
+setup, environment variables, proactive handoff, HITL, and file options.
+
 ## Cross-Channel Hand-off
 
 Route handlers can start a session on a different channel via `args.receive(channel, ...)`.
@@ -472,6 +519,7 @@ See [Channel file uploads](./attachments.md) for the full guide.
 ## What To Read Next
 
 - [Slack channel setup](./slack.md)
+- [Telegram channel setup](./telegram.md)
 - [Channel file uploads](./attachments.md)
 - [Project Layout](../project-layout.md)
 - [TypeScript API](../typescript-api.md)

package/dist/docs/public/channels/discord.md

@@ -132,19 +132,27 @@ Component and modal submissions resume the parked Ash session automatically.
 
 ## Proactive Sessions
 
-Use `receive(discord, args)` from schedules or another channel to start a Discord session:
+Use `receive(discord, { message, args, auth })` from a schedule `run` handler, or
+`args.receive(discord, ...)` from another channel, to start a Discord session:
 
 ```ts
-import { defineSchedule, receive } from "experimental-ash/schedules";
+import { defineSchedule } from "experimental-ash/schedules";
 import discord from "../channels/discord.js";
 
 export default defineSchedule({
   cron: "0 9 * * 1-5",
-  markdown: "Post the daily summary.",
-  channel: receive(discord, {
-    channelId: "123456789012345678",
-    initialMessage: "Daily summary",
-  }),
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(discord, {
+        message: "Post the daily summary.",
+        args: {
+          channelId: "123456789012345678",
+          initialMessage: "Daily summary",
+        },
+        auth: appAuth,
+      }),
+    );
+  },
 });
 ```
 

package/dist/docs/public/channels/teams.md

@@ -0,0 +1,121 @@
+---
+title: "Microsoft Teams channel setup"
+description: "Create a Microsoft Teams-backed Ash channel with the Bot Framework Activity protocol."
+---
+
+# Microsoft Teams Channel Setup
+
+The Teams channel accepts Bot Framework Activity POSTs from Microsoft Teams, verifies Bot
+Connector bearer JWTs, dispatches message activities to Ash, renders HITL prompts as Adaptive
+Cards, and delivers agent responses through the Bot Framework Connector REST API.
+
+## Add The Channel
+
+Create `agent/channels/teams.ts`:
+
+```ts
+import { teamsChannel } from "experimental-ash/channels/teams";
+
+export default teamsChannel();
+```
+
+Set the credentials Ash needs:
+
+```bash
+MICROSOFT_APP_ID=...
+MICROSOFT_APP_PASSWORD=...
+# Optional for single-tenant bots:
+MICROSOFT_TENANT_ID=...
+```
+
+By default, the channel mounts `POST /ash/v1/teams`. Configure your Azure Bot or Teams app
+messaging endpoint to that public URL.
+
+Use `route` when the bot endpoint needs a different path:
+
+```ts
+export default teamsChannel({
+  route: "/api/teams/activity",
+});
+```
+
+## Message Dispatch
+
+The default `onMessage` behavior dispatches personal-chat messages and channel/group-chat messages
+that directly mention the bot. Ambient messages delivered through Teams resource-specific consent
+are parsed but ignored unless you override `onMessage`.
+
+```ts
+import { teamsChannel, defaultTeamsAuth } from "experimental-ash/channels/teams";
+
+export default teamsChannel({
+  onMessage(ctx, message) {
+    if (message.scope !== "personal" && !message.isBotMentioned) return null;
+    return { auth: defaultTeamsAuth(message) };
+  },
+});
+```
+
+Ash strips the bot mention from channel/group prompts, adds a compact `<teams_context>` block, and
+keeps personal chats scoped to one Ash session per Teams conversation. Channel and group-chat
+threads are scoped by the root activity id (`replyToId ?? id`).
+
+## Delivery And HITL
+
+Default delivery posts Markdown messages with `textFormat: "markdown"`, splits oversized text, and
+sends typing indicators on turn start and action requests. `input.requested` renders Adaptive Cards:
+buttons/options use `Action.Submit`, select requests use `Input.ChoiceSet`, and freeform requests
+use `Input.Text`.
+
+Adaptive Card submit activities are converted into Ash `inputResponses` automatically. Non-HITL
+invoke activities can be handled with `onInvoke(ctx, activity)`.
+
+## Proactive Sessions
+
+Use `receive(teams, args)` only when you already have a Teams conversation reference. Teams v1 does
+not create new chats by AAD user id.
+
+```ts
+import { defineSchedule, receive } from "experimental-ash/schedules";
+import teams from "../channels/teams.js";
+
+export default defineSchedule({
+  cron: "0 9 * * 1-5",
+  markdown: "Post the daily summary.",
+  channel: receive(teams, {
+    serviceUrl: "https://smba.trafficmanager.net/teams",
+    conversationId: "19:...",
+    conversationType: "channel",
+    tenantId: "tenant-id",
+    initialMessage: "Daily summary",
+  }),
+});
+```
+
+For channel/group-chat proactive sessions without `replyToActivityId`, the first posted message
+becomes the thread anchor and the channel re-keys the Ash continuation token to that activity id.
+
+## Files
+
+Text support is enabled by default. Inbound file parts are opt-in:
+
+```ts
+export default teamsChannel({
+  files: {
+    enabled: true,
+    allowedHosts: ["contoso.sharepoint.com"],
+  },
+});
+```
+
+This covers personal-scope Teams file download attachments and simple public media URLs. Graph-based
+channel file retrieval and outbound file-consent upload are intentionally outside v1.
+
+## Teams References
+
+- [Teams conversational bots](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/build-conversational-capability)
+- [Teams channel and group chat bot conversations](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-and-group-conversations)
+- [Bot Connector authentication](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-authentication?view=azure-bot-service-4.0)
+- [Bot Connector REST API reference](https://learn.microsoft.com/sr-latn-rs/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0)
+- [Teams proactive messages](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
+- [Teams card actions](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions)

package/dist/docs/public/channels/telegram.md

@@ -0,0 +1,201 @@
+---
+title: "Telegram channel setup"
+description: "Create a Telegram-backed Ash channel for bot webhooks, replies, HITL, and attachments."
+---
+
+# Telegram Channel Setup
+
+The Telegram channel accepts Telegram Bot API webhooks. It verifies Telegram's
+`X-Telegram-Bot-Api-Secret-Token` header before parsing the update, dispatches private messages and
+addressed group messages, and sends default replies through `sendMessage`.
+
+## Add The Channel
+
+Create `agent/channels/telegram.ts`:
+
+```ts
+import { telegramChannel } from "experimental-ash/channels/telegram";
+
+export default telegramChannel({
+  botUsername: "my_bot",
+});
+```
+
+Set the credentials Ash needs for inbound verification and outbound replies:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:...
+TELEGRAM_WEBHOOK_SECRET_TOKEN=...
+```
+
+- `TELEGRAM_BOT_TOKEN` sends replies, typing indicators, callback acknowledgements, and proactive
+  messages.
+- `TELEGRAM_WEBHOOK_SECRET_TOKEN` must match the `secret_token` value you register with Telegram's
+  `setWebhook`.
+
+You can also pass the same values in config:
+
+```ts
+export default telegramChannel({
+  botUsername: "my_bot",
+  credentials: {
+    botToken: process.env.TELEGRAM_BOT_TOKEN,
+    webhookSecretToken: process.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
+  },
+});
+```
+
+By default, the channel mounts `POST /ash/v1/telegram`.
+
+## Register The Webhook
+
+Register the deployed public URL with Telegram's Bot API:
+
+```bash
+curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://your-app.example.com/ash/v1/telegram",
+    "secret_token": "'"$TELEGRAM_WEBHOOK_SECRET_TOKEN"'",
+    "allowed_updates": ["message", "callback_query"]
+  }'
+```
+
+Webhook setup is external to Ash; the runtime does not call `setWebhook` for you.
+
+## Message Dispatch
+
+Private chats dispatch normal text, captions, photos, and documents by default. The default
+`onMessage` derives Telegram user auth, starts a typing indicator, and returns `{ auth }`.
+
+Groups and supergroups are gated more narrowly:
+
+- bot commands dispatch, including `/ask` and `/ask@my_bot`
+- `@my_bot` mentions dispatch when `botUsername` is configured
+- replies to bot messages dispatch
+- unaddressed group chatter is ignored
+
+For Telegram forum topics, the channel includes `message_thread_id` in the continuation token and
+outbound messages so separate topics do not collapse into one session.
+
+Override `onMessage` when you need custom auth or additional filtering:
+
+```ts
+import { telegramChannel } from "experimental-ash/channels/telegram";
+
+export default telegramChannel({
+  botUsername: "my_bot",
+  onMessage(ctx, message) {
+    if (message.chat.type !== "private" && !message.text.includes("@my_bot")) return null;
+    return {
+      auth: {
+        authenticator: "telegram",
+        principalType: "user",
+        principalId: message.from?.id ?? message.chat.id,
+        attributes: {
+          chat_id: message.chat.id,
+          chat_type: message.chat.type,
+        },
+      },
+    };
+  },
+});
+```
+
+Telegram group privacy is controlled by BotFather. With privacy mode enabled, Telegram only sends
+commands, replies, and service messages to the bot. Disable privacy mode only if your bot should see
+all group messages; Ash still applies the group dispatch gate above.
+
+## Delivery
+
+The default `"message.completed"` handler sends plain text with `sendMessage`. Ash does not set
+`parse_mode`, so generated Markdown is delivered as literal text rather than being parsed by
+Telegram. Messages longer than Telegram's 4096-character text limit are split into multiple
+`sendMessage` calls.
+
+Default progress handlers call `sendChatAction` with `typing`. Typing failures are logged and
+swallowed because the indicator is only a UX hint.
+
+Custom event handlers can use `ctx.telegram`:
+
+```ts
+export default telegramChannel({
+  events: {
+    async "message.completed"(event, ctx) {
+      if (event.finishReason === "tool-calls" || !event.message) return;
+      await ctx.telegram.sendMessage(`Result:\n${event.message}`);
+    },
+  },
+});
+```
+
+## Human Input
+
+Pending Ash input requests render in Telegram:
+
+- option requests render as inline keyboard buttons
+- freeform requests render as `ForceReply` prompts
+
+Telegram caps `callback_data` at 64 bytes, so Ash stores compact callback ids in durable channel
+state and remaps them to the original Ash input response when the callback query arrives. Freeform
+answers resume when the user replies to the specific prompt message.
+
+Callback queries generated by Ash are acknowledged with `answerCallbackQuery` automatically. Other
+callback queries are passed to `onCallbackQuery` when you provide one.
+
+## Attachments
+
+Inbound photos and documents become AI SDK file parts with internal `telegram-file:` URLs. When the
+model needs the bytes, the channel calls Telegram `getFile`, downloads the file through the Bot API
+file endpoint, and enforces the channel upload policy.
+
+```ts
+export default telegramChannel({
+  uploadPolicy: {
+    allowedMediaTypes: ["image/*", "application/pdf"],
+    maxBytes: 10 * 1024 * 1024,
+  },
+});
+```
+
+V1 supports inbound photos and documents. Polling, inline mode, payments, business-account updates,
+channel posts, stickers, and outbound sandbox-file sharing are not included.
+
+## Proactive Sessions
+
+Use `receive(telegram, { message, args, auth })` from a schedule `run` handler, or
+`args.receive(telegram, ...)` from another channel, to start a Telegram session:
+
+```ts
+import { defineSchedule } from "experimental-ash/schedules";
+import telegram from "../channels/telegram.js";
+
+export default defineSchedule({
+  cron: "0 9 * * 1-5",
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(telegram, {
+        message: "Post the daily summary.",
+        args: {
+          chatId: "123456789",
+          initialMessage: "Daily summary",
+        },
+        auth: appAuth,
+      }),
+    );
+  },
+});
+```
+
+`chatId` is required. Pass `messageThreadId` for forum topics. Pass `conversationId` to resume a
+known group conversation, or `initialMessage` to post an anchor message first; those two options are
+mutually exclusive.
+
+## Telegram References
+
+- [Telegram Bot API](https://core.telegram.org/bots/api)
+- [setWebhook](https://core.telegram.org/bots/api#setwebhook)
+- [sendMessage](https://core.telegram.org/bots/api#sendmessage)
+- [sendChatAction](https://core.telegram.org/bots/api#sendchataction)
+- [answerCallbackQuery](https://core.telegram.org/bots/api#answercallbackquery)
+- [getFile](https://core.telegram.org/bots/api#getfile)

package/dist/docs/public/typescript-api.md

@@ -30,7 +30,9 @@ for `defineAgent`.
 - `defineChannel(...)` - HTTP channel entrypoints in `channels/` with `routes`, `state`, `context()`, and typed event handlers (`experimental-ash/channels`)
 - `defineHook(...)` - lifecycle and stream-event subscriber in `hooks/<slug>.ts` (`experimental-ash/hooks`)
 - `defineSandbox(...)` - override the agent's single sandbox in `sandbox.ts` (or `sandbox/sandbox.ts` when paired with a `workspace/` folder) (`experimental-ash/sandbox`)
-- `defineSchedule(...)` - recurring jobs in `schedules/<name>.ts` or `schedules/<name>.md`; requires `cron` and `markdown`, `channel` is optional (`experimental-ash/schedules`)
+- `defineSchedule(...)` - recurring jobs in `schedules/<name>.ts` or `schedules/<name>.md`;
+  TypeScript schedules require `cron` and exactly one of `markdown` or `run`
+  (`experimental-ash/schedules`)
 - `defineSkill(...)` - module-authored skills (`experimental-ash/skills`)
 - `defineInstructions(...)` - module-authored instructions prompt (`experimental-ash/instructions`)
 - `defineTool(...)` - typed executable integration in `tools/<name>.ts` (`experimental-ash/tools`)
@@ -109,6 +111,43 @@ Channel and Twilio types exported from `experimental-ash/channels/twilio`:
   `confidence`, ...)
 - `verifyTwilioRequest`, `signTwilioRequest` - Ash-owned Twilio webhook signature helpers
 
+Channel and Telegram types exported from `experimental-ash/channels/telegram`:
+
+- `telegramChannel` - Telegram Bot API webhook channel factory for messages, callback queries,
+  HITL, attachments, typing indicators, and proactive sessions
+- `telegramContinuationToken` - helper for the channel-local raw token
+  (`chatId:messageThreadId:conversationId`)
+- `TelegramChannelConfig` - config type for credentials, route, Bot API overrides, upload policy,
+  `botUsername`, hooks, and event handlers
+- `TelegramContext` - pre-dispatch context for `onMessage` and `onCallbackQuery` (`telegram`)
+- `TelegramEventContext` - event-handler context (`telegram`, `session`, plus mutable `state`)
+- `TelegramHandle` - Telegram handle with `request()`, `post()`, `sendMessage()`,
+  `startTyping()`, `answerCallbackQuery()`, and `editMessageReplyMarkup()`
+- `TelegramMessage` - parsed inbound message payload (`text`, `caption`, `chat`, `from`,
+  `attachments`, reply context, ...)
+- `TelegramCallbackQuery` - parsed callback query payload passed to `onCallbackQuery`
+- `TelegramAttachment` - parsed inbound photo or document metadata
+- `TelegramReceiveArgs` - arguments accepted by proactive `receive(telegram, ...)`
+- `verifyTelegramRequest` - Ash-owned webhook secret-token verification helper
+
+Channel and Microsoft Teams types exported from `experimental-ash/channels/teams`:
+
+- `teamsChannel` - Teams channel factory for Bot Framework Activity webhooks and Connector delivery
+- `TeamsChannelConfig` - config type for credentials, route, event handlers, message/invoke hooks,
+  Adaptive Card version, and opt-in file handling
+- `TeamsContext` - pre-dispatch context for `onMessage` and `onInvoke` (`thread`, `teams`)
+- `TeamsEventContext` - event-handler context (`thread`, `teams`, mutable `state`)
+- `TeamsHandle` - low-level Connector handle with `sendActivity`, `replyToActivity`,
+  `updateActivity`, `startTyping`, and `request`
+- `TeamsThread` - conversation-scoped `post`, `update`, `startTyping`, and `mentionUser`
+- `TeamsMessageActivity` / `TeamsInvokeActivity` - parsed inbound Activity payloads
+- `TeamsReceiveArgs` - proactive/cross-channel handoff args requiring `serviceUrl` and
+  `conversationId`
+- `teamsContinuationToken` - channel-local Teams continuation-token helper
+- `defaultTeamsAuth` - default Teams actor-to-session-auth projection
+- `verifyTeamsRequest`, `verifyTeamsJwt` - Ash-owned Bot Connector request/JWT verification helpers
+- `sendTeamsActivity`, `replyToTeamsActivity`, `updateTeamsActivity` - Connector REST helpers
+
 Channel types exported from `experimental-ash/channels`:
 
 - `defineChannel` - channel primitive with `routes`, `state`, `context()`, and event handlers
@@ -138,6 +177,7 @@ import { defineChannel, POST, GET } from "experimental-ash/channels";
 import { ashChannel } from "experimental-ash/channels/ash";
 import { vercelOidc } from "experimental-ash/channels/auth";
 import { slackChannel } from "experimental-ash/channels/slack";
+import { telegramChannel } from "experimental-ash/channels/telegram";
 ```
 
 Inside a route handler, the helpers object exposes:

package/dist/src/internal/application/package.js

@@ -1 +1 @@
-import{createRequire}from"node:module";import{basename,dirname,join}from"node:path";import{existsSync,readFileSync,realpathSync}from"node:fs";import{ASH_PACKAGE_NAME}from"#internal/package-name.js";import{fileURLToPath}from"node:url";var cachedPackageInfo,BUNDLED_FALLBACK_PACKAGE_VERSION=`0.27.0`,BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER=`__ASH_PACKAGE_VERSION_PLACEHOLDER__`,WORKFLOW_MODULE_ALIASES={"workflow/api":`src/compiled/@workflow/core/runtime.js`,"workflow/errors":`src/compiled/@workflow/errors/index.js`,"workflow/internal/private":`src/compiled/@workflow/core/private.js`,"workflow/runtime":`src/compiled/@workflow/core/runtime.js`};function resolveFallbackPackageVersion(){return BUNDLED_FALLBACK_PACKAGE_VERSION===BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER?`0.0.0`:BUNDLED_FALLBACK_PACKAGE_VERSION}var FALLBACK_PACKAGE_INFO={name:ASH_PACKAGE_NAME,version:resolveFallbackPackageVersion()};function resolveCurrentModulePath(){return typeof __filename==`string`?__filename:resolveCurrentModulePathFromStack()}function resolveCurrentModulePathFromStack(){let e=Error.prepareStackTrace;try{Error.prepareStackTrace=(e,t)=>t;let e=Error().stack?.[0]?.getFileName();if(typeof e!=`string`||e.length===0)throw Error(`Failed to resolve the current module path from the stack trace.`);return e.startsWith(`file:`)?fileURLToPath(e):e}finally{Error.prepareStackTrace=e}}var require=createRequire(resolveCurrentModulePath());function isBuildOutputPackageRoot(e){return basename(e)===`dist`&&existsSync(join(dirname(e),`package.json`))}function resolvePackageBuildRoot(){let e=dirname(realpathSync(resolveCurrentModulePath()));for(;;){if(isBuildOutputPackageRoot(e))return e;let t=dirname(e);if(t===e)return null;e=t}}function findNearestPackageRoot(e){let t=e;for(;;){if(existsSync(join(t,`package.json`))&&!isBuildOutputPackageRoot(t))return t;let r=dirname(t);if(r===t)throw Error(`Failed to resolve package root from "${e}".`);t=r}}function resolvePackageRoot(){return findNearestPackageRoot(dirname(realpathSync(resolveCurrentModulePath())))}function tryResolvePackageRoot(){try{return resolvePackageRoot()}catch{return}}function rewriteSourceFilePathForBuild(e){return e.replace(/\.[cm]?tsx?$/,`.js`)}function resolvePackageSourceFilePath(e){let t=resolvePackageBuildRoot();return t===null?join(resolvePackageRoot(),e):join(t,rewriteSourceFilePathForBuild(e))}function resolvePackageSourceDirectoryPath(e){let t=resolvePackageBuildRoot();return join(t===null?resolvePackageRoot():t,e)}function resolvePackageCompiledFilePath(e){let t=resolvePackageBuildRoot();return t===null?join(resolvePackageRoot(),`.generated`,`compiled`,e.replace(/^src\/compiled\//,``)):join(t,e)}function normalizeInstalledPackageInfo(e){let t=e;if(!(typeof t.name!=`string`||typeof t.version!=`string`))return{name:t.name,version:t.version}}function tryReadInstalledPackageInfo(e,t){let n=normalizeInstalledPackageInfo(JSON.parse(readFileSync(e,`utf8`)));if(n?.name===t)return n}function resolveInstalledPackageInfo(){if(cachedPackageInfo)return cachedPackageInfo;let e=tryResolvePackageRoot(),t=e===void 0?void 0:tryReadInstalledPackageInfo(join(e,`package.json`),ASH_PACKAGE_NAME);if(t)return cachedPackageInfo=t,cachedPackageInfo;try{let e=tryReadInstalledPackageInfo(require.resolve(`${ASH_PACKAGE_NAME}/package.json`),ASH_PACKAGE_NAME);if(e)return cachedPackageInfo=e,cachedPackageInfo}catch{}return cachedPackageInfo={...FALLBACK_PACKAGE_INFO},cachedPackageInfo}function resolveWorkflowModulePath(e){if(e===`workflow`)return resolvePackageSourceFilePath(`src/internal/workflow/index.ts`);if(e===`workflow/internal/builtins`)return resolvePackageSourceFilePath(`src/internal/workflow/builtins.ts`);let t=WORKFLOW_MODULE_ALIASES[e];return t===void 0?require.resolve(e):resolvePackageCompiledFilePath(t)}export{resolveInstalledPackageInfo,resolvePackageRoot,resolvePackageSourceDirectoryPath,resolvePackageSourceFilePath,resolveWorkflowModulePath};
+import{createRequire}from"node:module";import{basename,dirname,join}from"node:path";import{existsSync,readFileSync,realpathSync}from"node:fs";import{ASH_PACKAGE_NAME}from"#internal/package-name.js";import{fileURLToPath}from"node:url";var cachedPackageInfo,BUNDLED_FALLBACK_PACKAGE_VERSION=`0.28.0`,BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER=`__ASH_PACKAGE_VERSION_PLACEHOLDER__`,WORKFLOW_MODULE_ALIASES={"workflow/api":`src/compiled/@workflow/core/runtime.js`,"workflow/errors":`src/compiled/@workflow/errors/index.js`,"workflow/internal/private":`src/compiled/@workflow/core/private.js`,"workflow/runtime":`src/compiled/@workflow/core/runtime.js`};function resolveFallbackPackageVersion(){return BUNDLED_FALLBACK_PACKAGE_VERSION===BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER?`0.0.0`:BUNDLED_FALLBACK_PACKAGE_VERSION}var FALLBACK_PACKAGE_INFO={name:ASH_PACKAGE_NAME,version:resolveFallbackPackageVersion()};function resolveCurrentModulePath(){return typeof __filename==`string`?__filename:resolveCurrentModulePathFromStack()}function resolveCurrentModulePathFromStack(){let e=Error.prepareStackTrace;try{Error.prepareStackTrace=(e,t)=>t;let e=Error().stack?.[0]?.getFileName();if(typeof e!=`string`||e.length===0)throw Error(`Failed to resolve the current module path from the stack trace.`);return e.startsWith(`file:`)?fileURLToPath(e):e}finally{Error.prepareStackTrace=e}}var require=createRequire(resolveCurrentModulePath());function isBuildOutputPackageRoot(e){return basename(e)===`dist`&&existsSync(join(dirname(e),`package.json`))}function resolvePackageBuildRoot(){let e=dirname(realpathSync(resolveCurrentModulePath()));for(;;){if(isBuildOutputPackageRoot(e))return e;let t=dirname(e);if(t===e)return null;e=t}}function findNearestPackageRoot(e){let t=e;for(;;){if(existsSync(join(t,`package.json`))&&!isBuildOutputPackageRoot(t))return t;let r=dirname(t);if(r===t)throw Error(`Failed to resolve package root from "${e}".`);t=r}}function resolvePackageRoot(){return findNearestPackageRoot(dirname(realpathSync(resolveCurrentModulePath())))}function tryResolvePackageRoot(){try{return resolvePackageRoot()}catch{return}}function rewriteSourceFilePathForBuild(e){return e.replace(/\.[cm]?tsx?$/,`.js`)}function resolvePackageSourceFilePath(e){let t=resolvePackageBuildRoot();return t===null?join(resolvePackageRoot(),e):join(t,rewriteSourceFilePathForBuild(e))}function resolvePackageSourceDirectoryPath(e){let t=resolvePackageBuildRoot();return join(t===null?resolvePackageRoot():t,e)}function resolvePackageCompiledFilePath(e){let t=resolvePackageBuildRoot();return t===null?join(resolvePackageRoot(),`.generated`,`compiled`,e.replace(/^src\/compiled\//,``)):join(t,e)}function normalizeInstalledPackageInfo(e){let t=e;if(!(typeof t.name!=`string`||typeof t.version!=`string`))return{name:t.name,version:t.version}}function tryReadInstalledPackageInfo(e,t){let n=normalizeInstalledPackageInfo(JSON.parse(readFileSync(e,`utf8`)));if(n?.name===t)return n}function resolveInstalledPackageInfo(){if(cachedPackageInfo)return cachedPackageInfo;let e=tryResolvePackageRoot(),t=e===void 0?void 0:tryReadInstalledPackageInfo(join(e,`package.json`),ASH_PACKAGE_NAME);if(t)return cachedPackageInfo=t,cachedPackageInfo;try{let e=tryReadInstalledPackageInfo(require.resolve(`${ASH_PACKAGE_NAME}/package.json`),ASH_PACKAGE_NAME);if(e)return cachedPackageInfo=e,cachedPackageInfo}catch{}return cachedPackageInfo={...FALLBACK_PACKAGE_INFO},cachedPackageInfo}function resolveWorkflowModulePath(e){if(e===`workflow`)return resolvePackageSourceFilePath(`src/internal/workflow/index.ts`);if(e===`workflow/internal/builtins`)return resolvePackageSourceFilePath(`src/internal/workflow/builtins.ts`);let t=WORKFLOW_MODULE_ALIASES[e];return t===void 0?require.resolve(e):resolvePackageCompiledFilePath(t)}export{resolveInstalledPackageInfo,resolvePackageRoot,resolvePackageSourceDirectoryPath,resolvePackageSourceFilePath,resolveWorkflowModulePath};

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

@@ -0,0 +1,140 @@
+/**
+ * Minimal Microsoft Teams Bot Framework Connector REST wrapper.
+ *
+ * The native Teams channel talks directly to the Bot Framework Activity
+ * protocol instead of exposing BotBuilder or Teams SDK objects through
+ * Ash public APIs.
+ */
+import { type JsonObject } from "#shared/json.js";
+/** Microsoft application id, materialized directly or from an async secret provider. */
+export type TeamsAppId = string | (() => string | Promise<string>);
+/** Microsoft application password, materialized directly or from an async secret provider. */
+export type TeamsAppPassword = string | (() => string | Promise<string>);
+/** Microsoft tenant id, materialized directly or from an async secret provider. */
+export type TeamsTenantId = string | (() => string | Promise<string>);
+/** Fetch implementation override used by tests or non-standard runtimes. */
+export type TeamsFetch = typeof fetch;
+/** Result shape accepted from a caller-owned Bot Connector token provider. */
+export type TeamsAccessTokenResult = string | {
+    readonly accessToken: string;
+    readonly expiresAt?: Date | number;
+};
+/** Caller-owned Bot Connector token provider. */
+export type TeamsTokenProvider = () => TeamsAccessTokenResult | Promise<TeamsAccessTokenResult>;
+/** Credentials used by the native Teams channel. */
+export interface TeamsCredentials {
+    readonly appId?: TeamsAppId;
+    readonly appPassword?: TeamsAppPassword;
+    readonly tenantId?: TeamsTenantId;
+    readonly tokenProvider?: TeamsTokenProvider;
+}
+/** Shared Teams API options. */
+export interface TeamsApiOptions {
+    readonly credentials?: TeamsCredentials;
+    readonly fetch?: TeamsFetch;
+    readonly loginBaseUrl?: string;
+}
+/** Raw Teams Connector API response body. */
+export interface TeamsApiResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly body: unknown;
+}
+/** Minimal ResourceResponse object returned by Teams write operations. */
+export interface TeamsPostedActivity {
+    /** Teams/Bot Framework activity id, when one was returned. */
+    readonly id: string;
+    /** Connector's raw JSON response. */
+    readonly raw: unknown;
+}
+/** Bot Framework channel account shape surfaced by the native Teams channel. */
+export interface TeamsChannelAccount {
+    readonly aadObjectId?: string;
+    readonly id: string;
+    readonly name?: string;
+    readonly role?: string;
+}
+/** Bot Framework mention entity shape used by Teams messages. */
+export interface TeamsMention {
+    readonly mentioned: TeamsChannelAccount;
+    readonly text: string;
+    readonly type: "mention";
+}
+/** Bot Framework/Teams attachment shape supported by Ash-owned APIs. */
+export interface TeamsAttachment {
+    readonly content?: JsonObject;
+    readonly contentType: string;
+    readonly contentUrl?: string;
+    readonly name?: string;
+}
+/** JSON body supported by Teams message endpoints used by Ash. */
+export interface TeamsMessageBody {
+    readonly attachments?: readonly TeamsAttachment[];
+    readonly channelData?: JsonObject;
+    readonly entities?: readonly TeamsMention[];
+    readonly inputHint?: string;
+    readonly speak?: string;
+    readonly suggestedActions?: JsonObject;
+    readonly text?: string;
+    readonly textFormat?: "markdown" | "plain" | "xml";
+}
+/** Outbound Bot Framework activity body sent through the Connector API. */
+export interface TeamsOutboundActivity extends TeamsMessageBody {
+    readonly conversation?: JsonObject;
+    readonly from?: TeamsChannelAccount;
+    readonly recipient?: TeamsChannelAccount;
+    readonly replyToId?: string;
+    readonly type: "message" | "typing";
+}
+/** Conservative text budget for one Teams bot message. */
+export declare const TEAMS_MESSAGE_TEXT_MAX_LENGTH: number;
+/** Builds the channel-local continuation token for one Teams conversation/thread. */
+export declare function teamsContinuationToken(input: {
+    readonly conversationId: string;
+    readonly replyToActivityId?: string | null;
+    readonly tenantId?: string | null;
+}): string;
+/** Resolves a Teams app id, falling back to `MICROSOFT_APP_ID` then `TEAMS_APP_ID`. */
+export declare function resolveTeamsAppId(appId?: TeamsAppId): Promise<string>;
+/** Resolves a Teams app password, falling back to `MICROSOFT_APP_PASSWORD` then `TEAMS_APP_PASSWORD`. */
+export declare function resolveTeamsAppPassword(appPassword?: TeamsAppPassword): Promise<string>;
+/** Resolves a Teams tenant id, falling back to `MICROSOFT_TENANT_ID` then `TEAMS_TENANT_ID`. */
+export declare function resolveTeamsTenantId(tenantId?: TeamsTenantId): Promise<string | undefined>;
+/** Resolves a Bot Connector access token, using a custom provider or client credentials. */
+export declare function resolveTeamsAccessToken(options?: TeamsApiOptions): Promise<string>;
+/** Low-level Bot Framework Connector API call. */
+export declare function callTeamsConnectorApi(input: TeamsApiOptions & {
+    readonly body?: TeamsOutboundActivity | JsonObject;
+    readonly method?: "DELETE" | "GET" | "POST" | "PUT";
+    readonly path: string;
+    readonly serviceUrl: string;
+}): Promise<TeamsApiResponse>;
+/** Sends a non-reply activity to one Teams conversation. */
+export declare function sendTeamsActivity(input: TeamsApiOptions & {
+    readonly body: TeamsOutboundActivity;
+    readonly conversationId: string;
+    readonly serviceUrl: string;
+}): Promise<TeamsPostedActivity>;
+/** Sends a reply activity to one Teams conversation activity. */
+export declare function replyToTeamsActivity(input: TeamsApiOptions & {
+    readonly activityId: string;
+    readonly body: TeamsOutboundActivity;
+    readonly conversationId: string;
+    readonly serviceUrl: string;
+}): Promise<TeamsPostedActivity>;
+/** Updates an existing Teams bot activity. */
+export declare function updateTeamsActivity(input: TeamsApiOptions & {
+    readonly activityId: string;
+    readonly body: TeamsOutboundActivity;
+    readonly conversationId: string;
+    readonly serviceUrl: string;
+}): Promise<TeamsPostedActivity>;
+/** Triggers Teams' typing indicator for one conversation. */
+export declare function triggerTeamsTypingIndicator(input: TeamsApiOptions & {
+    readonly conversationId: string;
+    readonly serviceUrl: string;
+}): Promise<void>;
+/** Splits text into chunks that fit Teams' conservative message-size budget. */
+export declare function splitTeamsMessageText(content: string): readonly string[];
+/** Normalizes a string or message body into a Teams message activity body. */
+export declare function normalizeTeamsPostInput(message: string | TeamsMessageBody): TeamsMessageBody;