eve 0.5.4 → 0.6.0-beta.3

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -0,0 +1,303 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { CardElement } from "#compiled/chat/index.js";
+import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { ChannelSessionOps } from "#public/definitions/defineChannel.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { type SlackBotToken, type SlackHandle, type SlackThread } from "#public/channels/slack/api.js";
+import { type SlackMessage } from "#public/channels/slack/inbound.js";
+import { type UploadPolicyInput } from "#public/channels/upload-policy.js";
+import { type SlackWebhookVerifier } from "#public/channels/slack/verify.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 Slack context passed to `onAppMention` and
+ * `onInteraction`. These hooks run on the inbound webhook side before the
+ * runtime hydrates session state, so `state` is absent here.
+ * {@link thread} owns thread-scoped operations (`post`, `postEphemeral`,
+ * `startTyping`, `refresh`, `recentMessages`, `mentionUser`); {@link slack}
+ * owns Slack identity (`channelId`, `threadTs`, `teamId`) plus the raw-API
+ * escape hatch (`request`, `uploadFiles`).
+ */
+export interface SlackContext {
+    readonly thread: SlackThread;
+    readonly slack: SlackHandle;
+}
+/**
+ * {@link SlackContext} plus the persisted per-session
+ * {@link SlackChannelState}. Built by the channel's `context()` hook and
+ * extended by {@link SlackEventContext}.
+ */
+export interface SlackChannelContext extends SlackContext {
+    state: SlackChannelState;
+}
+/**
+ * Slack context handed to `events[type]` handlers. Extends
+ * {@link SlackChannelContext} (`thread`, `slack`, hydrated `state`) with
+ * session operations ({@link ChannelSessionOps}). Unlike the pre-dispatch
+ * {@link SlackContext}, `state` is hydrated here.
+ */
+export interface SlackEventContext extends SlackChannelContext, ChannelSessionOps {
+}
+export type { SlackApiResponse, SlackBotToken, SlackHandle, SlackThread, } from "#public/channels/slack/api.js";
+export type { SlackWebhookVerifier } from "#public/channels/slack/verify.js";
+type SlackEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, channel: SlackEventContext, ctx: SessionContext) => void | Promise<void>;
+type SlackSessionFailedHandler = (data: EventData<"session.failed">, channel: SlackEventContext) => void | Promise<void>;
+/**
+ * JSON-serializable per-session state, stored verbatim across workflow
+ * step boundaries. Anything written here must round-trip through
+ * `JSON.stringify` / `JSON.parse`.
+ */
+export interface SlackChannelState {
+    /** Slack channel id seeded by the inbound mention. */
+    channelId: string | null;
+    /** Slack thread root ts. */
+    threadTs: string | null;
+    /** Slack team id, when the inbound event carried one. */
+    teamId: string | null;
+    /**
+     * Slack user id of the actor that triggered the current session/turn.
+     * Captured on every inbound mention so default handlers (e.g.
+     * `authorization.required`) can target ephemeral feedback at the right
+     * user without re-parsing the mention payload.
+     */
+    triggeringUserId?: string | null;
+    /**
+     * Buffered text from a `message.completed` event whose `finishReason`
+     * was `"tool-calls"`. The default `actions.requested` handler uses the
+     * first non-empty line as the next typing indicator, surfacing the
+     * model's pre-tool narration instead of "Running ...". Cleared at
+     * `turn.started` and after use.
+     */
+    pendingToolCallMessage?: string | null;
+    /**
+     * Connection name to Slack message ts. Each entry is the public
+     * "Connect with X to continue" status post created by the default
+     * `authorization.required` handler; the matching
+     * `authorization.completed` handler edits it in place to surface the
+     * resolution outcome.
+     */
+    pendingAuthMessageTs?: Record<string, string>;
+}
+/**
+ * Per-session metadata attached to tracing spans, projected by the
+ * channel's `metadata(state)` hook. Fields mirror the inbound mention
+ * (channel, team, thread, triggering user) and are `null` until an inbound
+ * event seeds them. Open-ended (`Record<string, unknown>`) so deployments
+ * can attach extra span attributes.
+ */
+export interface SlackInstrumentationMetadata extends Record<string, unknown> {
+    readonly channelId: string | null;
+    readonly teamId: string | null;
+    readonly threadTs: string | null;
+    readonly triggeringUserId: string | null;
+}
+/**
+ * Slack channel credentials: outbound bot token plus inbound webhook
+ * verification. Any field may be omitted to fall back to its env-var /
+ * signing-secret default.
+ */
+export interface SlackChannelCredentials {
+    /**
+     * Bot token for all outbound Slack Web API calls. Falls back to
+     * `process.env.SLACK_BOT_TOKEN` when omitted.
+     */
+    readonly botToken?: SlackBotToken;
+    /**
+     * Signing secret used to HMAC-verify inbound webhook requests. Falls
+     * back to `process.env.SLACK_SIGNING_SECRET` when neither this nor
+     * `webhookVerifier` is supplied.
+     */
+    readonly signingSecret?: string;
+    /**
+     * Custom inbound webhook verifier. When supplied, eve skips the
+     * `SLACK_SIGNING_SECRET` fallback and delegates to it. Typically set by
+     * integrations (e.g. Connect) that authenticate webhooks out-of-band.
+     */
+    readonly webhookVerifier?: SlackWebhookVerifier;
+}
+/** Target accepted by `receive(slack, { target })` for proactive sessions. */
+export interface SlackReceiveTarget {
+    readonly channelId: string;
+    readonly threadTs?: string;
+    /**
+     * Optional message posted into the Slack channel before the agent runs.
+     * The post becomes the thread root and the first turn is threaded under
+     * it, giving cross-channel handoffs a visible context anchor. Mutually
+     * exclusive with {@link threadTs}.
+     */
+    readonly initialMessage?: SlackInitialMessage;
+}
+/**
+ * Pre-agent post issued by `slackChannel().receive` when the caller
+ * provides `target.initialMessage`. Mirrors `ctx.thread.post`'s card
+ * variant so the same `Card({...})` construction can be reused.
+ */
+export interface SlackInitialMessage {
+    readonly card: CardElement;
+    readonly fallbackText?: string;
+}
+export interface SlackInteractionAction {
+    readonly actionId: string;
+    readonly value?: string;
+    readonly blockId?: string;
+    /**
+     * `selected_option.value` for radio / select / external_select
+     * widgets. `undefined` for buttons and multi-select widgets.
+     */
+    readonly selectedOptionValue?: string;
+    /**
+     * `ts` of the Slack message hosting the clicked component. Required to
+     * update that message in place via `chat.update`, since `ctx.slack.threadTs`
+     * resolves to the thread root (not the clicked message) for components
+     * inside thread replies.
+     */
+    readonly messageTs?: string;
+    /**
+     * Display label of the clicked widget: `text.text` for buttons,
+     * `selected_option.text.text` for radio/static_select. Renders the
+     * "answered" card without re-fetching the original request.
+     */
+    readonly label?: string;
+    /**
+     * Slack actor who triggered the interaction, letting `onInteraction`
+     * handlers attribute resolutions back to the clicker without re-parsing
+     * the raw payload. Always present, since Slack requires `user` on every
+     * `block_actions` payload.
+     */
+    readonly user: SlackInteractionUser;
+}
+/** Slack actor on {@link SlackInteractionAction.user}, mirroring `body.user`. */
+export interface SlackInteractionUser {
+    readonly id: string;
+    /** Modern canonical display handle. */
+    readonly username?: string;
+    /** Legacy display handle, kept for older workspaces. */
+    readonly name?: string;
+}
+/**
+ * Result of an `onAppMention` or `onDirectMessage` callback. Return an
+ * object (auth may be `null`) to dispatch a turn, or `null` to drop the
+ * inbound message. `context` strings are appended as user messages to
+ * session history before the delivery message.
+ */
+export type SlackMentionResult = {
+    readonly auth: SessionAuthContext | null;
+    readonly context?: readonly string[];
+} | null;
+export type SlackMentionResultOrPromise = SlackMentionResult | Promise<SlackMentionResult>;
+/**
+ * Alias of {@link SlackMentionResult} for the `onDirectMessage` signature,
+ * so DM handlers do not read in terms of "mention".
+ */
+export type SlackInboundResult = SlackMentionResult;
+/** {@link SlackInboundResult}, or a promise resolving to one. */
+export type SlackInboundResultOrPromise = SlackMentionResultOrPromise;
+/**
+ * Per-event Slack handlers keyed by harness stream-event type, passed to
+ * `slackChannel({ events })`. Each key is optional; supplying one replaces
+ * only that event's built-in default (see {@link defaultEvents}). Handlers
+ * receive the event data, the {@link SlackEventContext}, and the session
+ * {@link SessionContext}; `session.failed` receives only data and context.
+ */
+export interface SlackChannelEvents {
+    readonly "turn.started"?: SlackEventHandler<"turn.started">;
+    readonly "actions.requested"?: SlackEventHandler<"actions.requested">;
+    readonly "action.result"?: SlackEventHandler<"action.result">;
+    readonly "message.completed"?: SlackEventHandler<"message.completed">;
+    readonly "message.appended"?: SlackEventHandler<"message.appended">;
+    readonly "input.requested"?: SlackEventHandler<"input.requested">;
+    readonly "turn.failed"?: SlackEventHandler<"turn.failed">;
+    readonly "turn.completed"?: SlackEventHandler<"turn.completed">;
+    readonly "session.failed"?: SlackSessionFailedHandler;
+    readonly "session.completed"?: SlackEventHandler<"session.completed">;
+    readonly "session.waiting"?: SlackEventHandler<"session.waiting">;
+    readonly "authorization.required"?: SlackEventHandler<"authorization.required">;
+    readonly "authorization.completed"?: SlackEventHandler<"authorization.completed">;
+}
+export interface SlackChannelConfig {
+    readonly credentials?: SlackChannelCredentials;
+    readonly botName?: string;
+    /** Override the default webhook route path (`/eve/v1/slack`). */
+    readonly route?: string;
+    /**
+     * Inbound upload policy applied to file attachments before they reach
+     * the harness. Violating attachments are dropped with a warning so the
+     * mention's text portion still gets delivered. Pass `"disabled"` to
+     * reject every attachment. Defaults to the framework's 25 MB cap with
+     * unrestricted media types.
+     */
+    readonly uploadPolicy?: UploadPolicyInput;
+    /**
+     * Invoked when a Slack `app_mention` event arrives (only `app_mention`;
+     * other event types are ignored). Decides whether to dispatch and with
+     * what auth, and may run pre-dispatch side effects (e.g.
+     * `ctx.thread.startTyping("Thinking...")`) on the inbound webhook side
+     * before the runtime cold-starts.
+     *
+     * Return `{ auth }` to dispatch with that session auth context, or `null`
+     * to drop the mention. May be sync or async; the result is awaited before
+     * dispatching. Thrown errors are caught and logged and the mention is
+     * dropped; wrap best-effort side effects in `try/catch` to keep them
+     * non-fatal. Defaults to a workspace-scoped auth derivation that posts a
+     * `"Thinking..."` typing indicator; replacing this replaces both.
+     */
+    onAppMention?(ctx: SlackContext, message: SlackMessage): SlackMentionResultOrPromise;
+    /**
+     * Invoked on a direct message: a Slack `message` event with
+     * `channel_type: "im"`. Subtype messages (edits, deletes, joins, etc.)
+     * and bot messages (`bot_id` set, including the bot's own replies) are
+     * filtered out first, so handlers only see plain user-authored DMs.
+     * Decides whether to dispatch and with what auth, and may run
+     * pre-dispatch side effects on the inbound webhook side before cold-start.
+     *
+     * Return `{ auth }` to dispatch with that session auth context, or `null`
+     * to drop the message. May be sync or async; the result is awaited before
+     * dispatching. Thrown errors are caught and logged and the message is
+     * dropped; wrap best-effort side effects in `try/catch` to keep them
+     * non-fatal. Defaults to a workspace-scoped auth derivation that posts a
+     * `"Thinking..."` typing indicator; replacing this replaces both.
+     * Requires the bot's Slack app to subscribe to `message.im` with the
+     * `im:history` scope.
+     */
+    onDirectMessage?(ctx: SlackContext, message: SlackMessage): SlackInboundResultOrPromise;
+    /**
+     * Handler for Slack `block_actions` interactive callbacks (button
+     * clicks, select changes, etc.) **not** consumed by the framework's
+     * HITL pipeline. Slack POSTs interactive payloads to the same webhook
+     * route as mentions; the framework decodes them, routes any action whose
+     * `action_id` starts with `eve_input:` to the runtime as an HITL
+     * response (resuming a paused session), and forwards everything else
+     * here, one invocation per non-HITL action.
+     *
+     * Runs on the inbound webhook side via `waitUntil()`, so the channel
+     * returns `200 OK` immediately. Errors are caught and logged; they do
+     * not affect the webhook response or sibling invocations.
+     *
+     * The `SlackContext` here is rebuilt from the interaction payload
+     * (channel id, thread ts, team id), **not** the persisted thread state
+     * used by event handlers. Use `ctx.slack.request(...)` for arbitrary
+     * Slack Web API calls and `action.messageTs` to target `chat.update`.
+     */
+    onInteraction?(action: SlackInteractionAction, ctx: SlackContext): void | Promise<void>;
+    readonly events?: SlackChannelEvents;
+}
+/**
+ * Concrete return type of {@link slackChannel}. Named so consumers can
+ * default-export a `slackChannel(...)` call under `declaration: true`
+ * without TypeScript emitting an internal path for `Channel`.
+ */
+export interface SlackChannel extends Channel<SlackChannelState, SlackReceiveTarget, SlackInstrumentationMetadata> {
+}
+/**
+ * Slack channel factory. Wires up the webhook route, mention dispatch,
+ * interaction handling, and a baseline set of typing / error /
+ * connection-auth event handlers. Defaults apply per field: pass
+ * `onAppMention` to fully replace the default mention pipeline (auth
+ * derivation plus `"Thinking..."` typing), or an `events[type]` handler to
+ * replace only that one event. Unsupplied fields keep their defaults.
+ */
+export declare function slackChannel(config?: SlackChannelConfig): SlackChannel;

package/dist/src/public/channels/slack/slackChannel.js

@@ -0,0 +1 @@
+import{markEventHandled}from"./utils.js";import{createLogger,logError}from"#internal/logging.js";import{POST,defineChannel}from"#public/definitions/defineChannel.js";import{mergeUploadPolicy}from"#public/channels/upload-policy.js";import{buildSlackBinding,slackContinuationToken}from"#public/channels/slack/api.js";import{defaultEvents,defaultInputRequestedHandler,defaultOnAppMention,defaultOnDirectMessage}from"#public/channels/slack/defaults.js";import{buildSlackTurnMessage,collectInboundFileParts,createSlackFetchFile}from"#public/channels/slack/attachments.js";import{formatSlackContextBlock,parseAppMentionEvent,parseDirectMessageEvent}from"#public/channels/slack/inbound.js";import{SLACK_CHANNEL_DEFAULT_ROUTE}from"#public/channels/slack/constants.js";import{handleInteractionPost}from"#public/channels/slack/interactions.js";import{verifySlackRequest}from"#public/channels/slack/verify.js";const log=createLogger(`slack.channel`);function rebuildSlackContext(e,t,n){let{thread:r,slack:i}=buildSlackBinding({botToken:n?.botToken,channelId:e.channelId??``,threadTs:e.threadTs??``,teamId:e.teamId??void 0,onThreadTsChanged(n){e.threadTs=n,e.channelId&&t.setContinuationToken(slackContinuationToken(e.channelId,n))}});return{thread:r,slack:i,state:e}}function slackChannel(e={}){let t=mergeUploadPolicy(e.uploadPolicy),n=createSlackFetchFile({botToken:e.credentials?.botToken}),l=e.onAppMention??defaultOnAppMention,u=e.onDirectMessage??defaultOnDirectMessage,d={...defaultEvents,...e.events,"input.requested":e.events?.[`input.requested`]??defaultInputRequestedHandler()},f=new Set;return defineChannel({kindHint:`slack`,state:{channelId:null,threadTs:null,teamId:null,triggeringUserId:null,pendingToolCallMessage:null,pendingAuthMessageTs:{}},fetchFile:n,metadata(e){return{channelId:e.channelId,teamId:e.teamId,threadTs:e.threadTs,triggeringUserId:e.triggeringUserId??null}},context(t,n){return rebuildSlackContext(t,n,e.credentials)},routes:[POST(e.route??SLACK_CHANNEL_DEFAULT_ROUTE,async(n,{send:r,waitUntil:i})=>{let a=await verifyInbound(n,e.credentials);return a===null?new Response(`unauthorized`,{status:401}):shouldDropSlackHttpTimeoutRetry(n.headers)?new Response(`ok`):(n.headers.get(`content-type`)??``).includes(`application/x-www-form-urlencoded`)?handleInteractionPost(a,{send:r,waitUntil:i},{config:e}):handleEventPost({body:a,send:r,waitUntil:i,onAppMention:l,onDirectMessage:u,uploadPolicy:t,handledEvents:f,headers:n.headers,credentials:e.credentials})})],async receive(t,{send:n}){let r=t.target,i=r.channelId;if(!i||typeof i!=`string`)throw Error(`slackChannel().receive requires target.channelId.`);let a=typeof r.threadTs==`string`?r.threadTs:``,s=r.initialMessage;if(s&&a.length>0)throw Error("slackChannel().receive: `threadTs` and `initialMessage` are mutually exclusive.");let c=a;if(s){let{thread:t}=buildSlackBinding({botToken:e.credentials?.botToken,channelId:i,threadTs:``,teamId:void 0}),n={card:s.card};s.fallbackText!==void 0&&(n.fallbackText=s.fallbackText),c=(await t.post(n)).id}return n(t.message,{auth:t.auth,continuationToken:slackContinuationToken(i,c),state:{channelId:i,threadTs:c||null,teamId:null,triggeringUserId:null}})},events:d})}function shouldDropSlackHttpTimeoutRetry(e){return Number(e.get(`x-slack-retry-num`)??`0`)>=1&&e.get(`x-slack-retry-reason`)===`http_timeout`}async function handleEventPost(t){let n;try{n=JSON.parse(t.body)}catch(e){return log.warn(`inbound webhook body is not valid JSON`,{error:e}),new Response(`ok`)}if(typeof n.challenge==`string`)return new Response(n.challenge,{status:200,headers:{"content-type":`text/plain`}});if(n.event_id){if(t.handledEvents.has(n.event_id))return log.warn(`received a duplicate event`,{event_id:n.event_id,event_time:n.event_time,retry_num:t.headers.get(`x-slack-retry-num`)||`(null)`,retry_reason:t.headers.get(`x-slack-retry-reason`)||`(null)`}),new Response(`ok`);markEventHandled(n.event_id,t.handledEvents)}let r=parseAppMentionEvent(n);if(r)return t.waitUntil(dispatchInboundMessage({kind:`app_mention`,message:r,handler:t.onAppMention,send:t.send,uploadPolicy:t.uploadPolicy,credentials:t.credentials})),new Response(`ok`);let i=parseDirectMessageEvent(n);return i&&t.waitUntil(dispatchInboundMessage({kind:`direct_message`,message:i,handler:t.onDirectMessage,send:t.send,uploadPolicy:t.uploadPolicy,credentials:t.credentials})),new Response(`ok`)}async function verifyInbound(e,t){try{return await verifySlackRequest(e,{signingSecret:t?.signingSecret??(t?.webhookVerifier?void 0:process.env.SLACK_SIGNING_SECRET),webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`slack inbound verification failed`,{error:e}),null}}async function dispatchInboundMessage(e){let{message:t,kind:r}=e,{thread:i,slack:a}=buildSlackBinding({botToken:e.credentials?.botToken,channelId:t.channelId,threadTs:t.threadTs,teamId:t.teamId}),s={thread:i,slack:a},c;try{c=await e.handler(s,t)}catch(e){logError(log,`${r} handler failed`,e,{channelId:t.channelId});return}if(c!=null)try{let n=await collectInboundFileParts({mention:t,thread:i,policy:e.uploadPolicy}),r=buildSlackTurnMessage(t.markdown,n),a={channelId:t.channelId,fullName:t.author?.fullName,teamId:t.teamId,threadTs:t.threadTs,userId:t.author?.userId??``,userName:t.author?.userName},o=c.context??[];await e.send({message:r,context:[formatSlackContextBlock(a),...o]},{auth:c.auth,continuationToken:slackContinuationToken(t.channelId,t.threadTs),state:{channelId:t.channelId,threadTs:t.threadTs,teamId:t.teamId??null,triggeringUserId:a.userId||null}})}catch(e){logError(log,`${r} delivery failed`,e,{channelId:t.channelId})}}export{slackChannel};

package/dist/src/public/channels/slack/thread.d.ts

@@ -0,0 +1,33 @@
+import type { SlackThread, SlackThreadMessage } from "#public/channels/slack/api.js";
+/**
+ * Boundary for {@link loadThreadContextMessages}. `"thread-root"` returns all
+ * prior thread messages; `"last-agent-reply"` returns only messages after the
+ * last agent-authored reply; a predicate returns only messages after the last
+ * one it matches.
+ */
+export type ThreadContextSince = "thread-root" | "last-agent-reply" | ((message: SlackThreadMessage) => boolean);
+/** Options for {@link loadThreadContextMessages}. */
+export interface LoadThreadContextMessagesOptions {
+    /**
+     * Boundary for returned context messages. Defaults to `"thread-root"`.
+     *
+     * Use `"last-agent-reply"` to include only user/thread messages
+     * since the last agent-authored Slack reply. Pass a predicate
+     * function for custom boundaries, such as "since the last message
+     * that mentioned a particular user".
+     */
+    readonly since?: ThreadContextSince;
+}
+/**
+ * Loads messages that are useful as background context for the current
+ * Slack thread turn.
+ *
+ * Returns an empty array when `message` is the thread root. For thread
+ * replies, refreshes the bound Slack thread and returns its recent
+ * messages before the triggering message, filtered by {@link options}.
+ * Formatting and model-message role choice stay with the caller.
+ */
+export declare function loadThreadContextMessages(thread: Pick<SlackThread, "recentMessages" | "refresh">, message: {
+    readonly threadTs: string;
+    readonly ts: string;
+}, options?: LoadThreadContextMessagesOptions): Promise<SlackThreadMessage[]>;

package/dist/src/public/channels/slack/thread.js

@@ -0,0 +1 @@
+async function loadThreadContextMessages(e,t,n={}){if(isThreadRootMessage(t))return[];await e.refresh();let r=e.recentMessages.findIndex(e=>e.ts===t.ts);return applySinceBoundary((r===-1?e.recentMessages:e.recentMessages.slice(0,r)).filter(e=>e.threadTs===t.threadTs&&e.ts!==t.ts),n.since)}function isThreadRootMessage(e){return e.threadTs===e.ts}function findLastIndex(e,t){for(let n=e.length-1;n>=0;--n)if(t(e[n]))return n;return-1}function applySinceBoundary(e,t){let n=t??`thread-root`;if(typeof n==`function`){let t=findLastIndex(e,n);return e.slice(t+1)}switch(n){case`thread-root`:return[...e];case`last-agent-reply`:{let t=findLastIndex(e,e=>e.isMe);return e.slice(t+1)}}}export{loadThreadContextMessages};

package/dist/src/public/channels/slack/utils.d.ts

@@ -0,0 +1 @@
+export declare function markEventHandled(eventId: string, handledEvents: Set<string>): void;

package/dist/src/public/channels/slack/utils.js

@@ -0,0 +1 @@
+const MAX_HANDLED_EVENTS=1e4;function markEventHandled(e,t){if(t.add(e),t.size>MAX_HANDLED_EVENTS)for(;t.size>MAX_HANDLED_EVENTS/2;)t.delete(t.values().next().value)}export{markEventHandled};

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

@@ -0,0 +1,48 @@
+/**
+ * Slack inbound-webhook verification.
+ *
+ * The native channel replaces `createSlackAdapter`'s built-in HMAC
+ * check with a self-contained verifier:
+ *
+ * 1. If the caller supplied a {@link SlackWebhookVerifier} (e.g.
+ *    Connect's OIDC-based forwarder), delegate to it.
+ * 2. Otherwise, recompute the Slack v0 HMAC and compare with
+ *    `X-Slack-Signature`. Rejects requests older than five minutes to
+ *    foil replay attacks.
+ *
+ * Returns the verified raw body string on success so the caller can
+ * parse it without re-reading the request stream.
+ */
+/**
+ * Caller-supplied inbound webhook verifier. Used as an alternative to
+ * HMAC verification — e.g. Connect supplies a verifier that
+ * authenticates Connect-forwarded webhooks with Vercel OIDC instead
+ * of Slack's signing secret.
+ *
+ * Contract (matches the chat SDK's `SlackAdapterConfig.webhookVerifier`):
+ *
+ * - **Throw / reject** → the channel responds 401 to Slack.
+ * - **Return a falsy value** (`null` / `undefined` / `false` / `""` /
+ *   `0`) → the channel responds 401 to Slack. This lets verifiers
+ *   signal rejection without throwing — e.g. Connect's `vercelOidc()`
+ *   returns `null` on a failed OIDC check.
+ * - **Return a truthy non-string value** → verification accepted.
+ * - **Return a string** → verification accepted, and the string
+ *   replaces the raw body for downstream parsing. Useful when the
+ *   verifier canonicalizes or substitutes the verified payload.
+ */
+export type SlackWebhookVerifier = (request: Request, body: string) => unknown | Promise<unknown>;
+export interface SlackVerifyOptions {
+    readonly signingSecret: string | undefined;
+    readonly webhookVerifier: SlackWebhookVerifier | undefined;
+    /** Max allowed clock skew, in seconds. Defaults to 5 minutes. */
+    readonly maxSkewSeconds?: number;
+}
+/**
+ * Verifies an inbound Slack webhook and returns its raw body.
+ *
+ * Throws when neither a signing secret nor a custom verifier is
+ * available, when signature/timestamp checks fail, or when the
+ * caller-supplied verifier rejects.
+ */
+export declare function verifySlackRequest(request: Request, options: SlackVerifyOptions): Promise<string>;

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

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{createHmac,timingSafeEqual}from"node:crypto";const log=createLogger(`slack.verify`);async function verifySlackRequest(e,n){let r=await e.text();if(n.webhookVerifier!==void 0){let t=await n.webhookVerifier(e,r);if(!t)throw Error(`slackChannel: inbound webhook verifier rejected the request.`);return typeof t==`string`?t:r}if(!n.signingSecret)throw Error(`slackChannel: missing signing secret. Pass credentials.signingSecret, set SLACK_SIGNING_SECRET, or supply credentials.webhookVerifier.`);let i=e.headers.get(`x-slack-request-timestamp`)??``,a=e.headers.get(`x-slack-signature`)??``;if(!i||!a)throw Error(`slackChannel: inbound request missing Slack signature headers.`);let o=Number(i);if(!Number.isFinite(o))throw Error(`slackChannel: inbound request has malformed timestamp.`);let s=n.maxSkewSeconds??300,c=Math.floor(Date.now()/1e3);if(Math.abs(c-o)>s)throw Error(`slackChannel: inbound request timestamp outside allowed skew.`);let l=`v0:${i}:${r}`;if(!constantTimeCompare(`v0=${createHmac(`sha256`,n.signingSecret).update(l).digest(`hex`)}`,a))throw Error(`slackChannel: inbound request signature mismatch.`);return r}function constantTimeCompare(e,t){if(e.length!==t.length)return!1;try{return timingSafeEqual(Buffer.from(e),Buffer.from(t))}catch(e){return log.debug(`timingSafeEqual threw`,{error:e}),!1}}export{verifySlackRequest};

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

@@ -0,0 +1,155 @@
+/**
+ * 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
+ * Eve 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;
+    /** Fetch override for tests or non-standard runtimes. */
+    readonly fetch?: TeamsFetch;
+    /**
+     * Microsoft OAuth host for the client-credentials token flow. Defaults to
+     * `https://login.microsoftonline.com`. Eve ignores it when
+     * `credentials.tokenProvider` is set.
+     */
+    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 Eve-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 Eve. */
+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.
+ * `type: "message"` carries the message fields; `type: "typing"` is a
+ * content-free typing indicator sent as-is, without normalization or
+ * channelData merging.
+ */
+export interface TeamsOutboundActivity extends TeamsMessageBody {
+    readonly conversation?: JsonObject;
+    readonly from?: TeamsChannelAccount;
+    readonly recipient?: TeamsChannelAccount;
+    readonly replyToId?: string;
+    readonly type: "message" | "typing";
+}
+/** Maximum character length for a single outbound Teams activity before `splitTeamsMessageText` chunks it (80 KiB). */
+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 `content` into chunks no longer than `TEAMS_MESSAGE_TEXT_MAX_LENGTH`,
+ * breaking on paragraph, then line, then word boundaries before a hard cut.
+ * Returns a single-element array when `content` already fits.
+ */
+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;

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

@@ -0,0 +1,4 @@
+import{isObject}from"#shared/guards.js";import{parseJsonObject}from"#shared/json.js";const TEAMS_MESSAGE_TEXT_MAX_LENGTH=80*1024,BOT_FRAMEWORK_TENANT=`botframework.com`,accessTokenCache=new Map;function teamsContinuationToken(e){return[e.tenantId??`_`,e.conversationId,e.replyToActivityId??``].map(e=>encodeURIComponent(e)).join(`:`)}async function resolveTeamsAppId(e){let t=e??process.env.MICROSOFT_APP_ID??process.env.TEAMS_APP_ID;if(!t)throw Error(`MICROSOFT_APP_ID or TEAMS_APP_ID is required.`);return typeof t==`function`?await t():t}async function resolveTeamsAppPassword(e){let t=e??process.env.MICROSOFT_APP_PASSWORD??process.env.TEAMS_APP_PASSWORD;if(!t)throw Error(`MICROSOFT_APP_PASSWORD or TEAMS_APP_PASSWORD is required.`);return typeof t==`function`?await t():t}async function resolveTeamsTenantId(e){let t=e??process.env.MICROSOFT_TENANT_ID??process.env.TEAMS_TENANT_ID;if(t)return typeof t==`function`?await t():t}async function resolveTeamsAccessToken(t={}){let n=t.credentials;if(n?.tokenProvider!==void 0)return normalizeAccessTokenResult(await n.tokenProvider()).accessToken;let a=await resolveTeamsAppId(n?.appId),o=await resolveTeamsAppPassword(n?.appPassword),s=await resolveTeamsTenantId(n?.tenantId),c=trimTrailingSlash(t.loginBaseUrl??`https://login.microsoftonline.com`),l=`${c}:${s??BOT_FRAMEWORK_TENANT}:${a}`,u=accessTokenCache.get(l),d=Date.now();if(u!==void 0&&u.expiresAt-6e4>d)return u.accessToken;let f=`${c}/${encodeURIComponent(s??BOT_FRAMEWORK_TENANT)}/oauth2/v2.0/token`,p=new URLSearchParams({client_id:a,client_secret:o,grant_type:`client_credentials`,scope:`https://api.botframework.com/.default`}),m=await(t.fetch??fetch)(f,{body:p,headers:{"content-type":`application/x-www-form-urlencoded`},method:`POST`}),h=await parseResponseBody(m);if(!m.ok)throw Error(`Teams access-token request failed with HTTP ${m.status}.`);let g=isObject(h)?h:{},_=typeof g.access_token==`string`?g.access_token:``;if(!_)throw Error(`Teams access-token response did not include access_token.`);let v=typeof g.expires_in==`number`?g.expires_in:3600;return accessTokenCache.set(l,{accessToken:_,expiresAt:d+v*1e3}),_}async function callTeamsConnectorApi(e){let n=e.fetch??fetch,r=new Headers;r.set(`authorization`,`Bearer ${await resolveTeamsAccessToken(e)}`),r.set(`content-type`,`application/json; charset=utf-8`);let i={headers:r,method:e.method??`POST`};e.body!==void 0&&(i.body=JSON.stringify(parseJsonObject(e.body)));let a=await n(`${trimTrailingSlash(e.serviceUrl)}${e.path}`,i);return{body:await parseResponseBody(a),ok:a.ok,status:a.status}}async function sendTeamsActivity(e){let t=await callTeamsConnectorApi({...e,body:e.body,path:`/v3/conversations/${encodeURIComponent(e.conversationId)}/activities`});if(!t.ok)throw Error(`Teams send activity failed with HTTP ${t.status}.`);return toPostedActivity(t.body)}async function replyToTeamsActivity(e){let t=await callTeamsConnectorApi({...e,body:e.body,path:`/v3/conversations/${encodeURIComponent(e.conversationId)}/activities/${encodeURIComponent(e.activityId)}`});if(!t.ok)throw Error(`Teams reply activity failed with HTTP ${t.status}.`);return toPostedActivity(t.body)}async function updateTeamsActivity(e){let t=await callTeamsConnectorApi({...e,body:e.body,method:`PUT`,path:`/v3/conversations/${encodeURIComponent(e.conversationId)}/activities/${encodeURIComponent(e.activityId)}`});if(!t.ok)throw Error(`Teams update activity failed with HTTP ${t.status}.`);return toPostedActivity(t.body)}async function triggerTeamsTypingIndicator(e){let t=await callTeamsConnectorApi({...e,body:{type:`typing`},path:`/v3/conversations/${encodeURIComponent(e.conversationId)}/activities`});if(!t.ok)throw Error(`Teams typing indicator failed with HTTP ${t.status}.`)}function splitTeamsMessageText(e){if(e.length<=81920)return[e];let t=[],r=e;for(;r.length>TEAMS_MESSAGE_TEXT_MAX_LENGTH;){let e=r.lastIndexOf(`
+
+`,TEAMS_MESSAGE_TEXT_MAX_LENGTH);e<=0&&(e=r.lastIndexOf(`
+`,TEAMS_MESSAGE_TEXT_MAX_LENGTH)),e<=0&&(e=r.lastIndexOf(` `,TEAMS_MESSAGE_TEXT_MAX_LENGTH)),e<=0&&(e=TEAMS_MESSAGE_TEXT_MAX_LENGTH),t.push(r.slice(0,e).trimEnd()),r=r.slice(e).trimStart()}return t.push(r),t}function normalizeTeamsPostInput(e){return typeof e==`string`?{text:e,textFormat:`markdown`}:e}function normalizeAccessTokenResult(e){if(typeof e==`string`)return{accessToken:e};let t=e.expiresAt instanceof Date?e.expiresAt.getTime():e.expiresAt;return{accessToken:e.accessToken,expiresAt:t}}function toPostedActivity(t){let n=isObject(t)?t:{};return{id:typeof n.id==`string`?n.id:``,raw:t}}function trimTrailingSlash(e){return e.replace(/\/+$/,``)}async function parseResponseBody(e){let t=await e.text();if(!t)return null;try{return JSON.parse(t)}catch{return t}}export{TEAMS_MESSAGE_TEXT_MAX_LENGTH,callTeamsConnectorApi,normalizeTeamsPostInput,replyToTeamsActivity,resolveTeamsAccessToken,resolveTeamsAppId,resolveTeamsAppPassword,resolveTeamsTenantId,sendTeamsActivity,splitTeamsMessageText,teamsContinuationToken,triggerTeamsTypingIndicator,updateTeamsActivity};

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

@@ -0,0 +1,35 @@
+import type { FilePart, UserContent } from "ai";
+import type { FetchFileResult } from "#channel/adapter.js";
+import type { TeamsAttachment } from "#public/channels/teams/api.js";
+import { type UploadPolicyInput } from "#public/channels/upload-policy.js";
+import type { UploadPolicy } from "#public/channels/upload-policy.js";
+/** File handling options for the native Teams channel. */
+export interface TeamsFilesConfig {
+    /**
+     * Hosts whose file URLs may be fetched, or `"*"` for any host. Defaults to
+     * `[]` (no hosts), so attachments are dropped until you allowlist their host.
+     */
+    readonly allowedHosts?: readonly string[] | "*";
+    /** Enable inbound attachment ingestion. Off unless explicitly `true`. */
+    readonly enabled?: boolean;
+    /** Size and type limits applied to accepted attachments. */
+    readonly uploadPolicy?: UploadPolicyInput;
+}
+/** Normalized file handling policy used by the Teams channel. */
+export interface TeamsFilesPolicy {
+    readonly allowedHosts: readonly string[] | "*";
+    readonly enabled: boolean;
+    readonly uploadPolicy: UploadPolicy;
+}
+/** Normalizes author-provided Teams file options. */
+export declare function normalizeTeamsFilesPolicy(config: TeamsFilesConfig | undefined): TeamsFilesPolicy;
+/** Collects Teams attachment file parts when file support is explicitly enabled. */
+export declare function collectTeamsFileParts(attachments: readonly TeamsAttachment[], policy: TeamsFilesPolicy): FilePart[];
+/** Combines text + file parts into the UserContent shape expected by the harness. */
+export declare function buildTeamsTurnMessage(text: string, fileParts: readonly FilePart[]): string | UserContent;
+/**
+ * Builds the channel `fetchFile` resolver for Teams file URLs. Returns null when
+ * files are disabled or the URL host is not in `allowedHosts`; otherwise fetches
+ * the bytes and throws on a non-2xx response.
+ */
+export declare function createTeamsFetchFile(policy: TeamsFilesPolicy): (url: string) => Promise<FetchFileResult | null>;

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

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{isObject}from"#shared/guards.js";import{evaluateFilePart,formatUploadPolicyViolation,isUploadsDisabled,mergeUploadPolicy}from"#public/channels/upload-policy.js";const log=createLogger(`teams.attachments`);function normalizeTeamsFilesPolicy(e){return{allowedHosts:e?.allowedHosts??[],enabled:e?.enabled===!0,uploadPolicy:mergeUploadPolicy(e?.uploadPolicy)}}function collectTeamsFileParts(e,t){if(!t.enabled||isUploadsDisabled(t.uploadPolicy))return[];let a=[];for(let i of e){let e=toTeamsFilePart(i,a.length,t);if(e===null)continue;let o=evaluateFilePart(e,t.uploadPolicy);if(o!==null){log.warn(`dropped Teams attachment — ${formatUploadPolicyViolation(o)}`,{name:i.name});continue}a.push(e)}return a}function buildTeamsTurnMessage(e,t){return t.length===0?e:e.trim().length===0?[...t]:[{type:`text`,text:e},...t]}function createTeamsFetchFile(e){return async t=>{if(!e.enabled||!isAllowedUrl(t,e.allowedHosts))return null;let n=await fetch(t);if(!n.ok)throw Error(`Teams file fetch returned HTTP ${n.status} for ${t}.`);return{bytes:Buffer.from(await n.arrayBuffer()),mediaType:n.headers.get(`content-type`)??void 0}}}function toTeamsFilePart(e,t,n){let r=readAttachmentUrl(e);return!r||!isAllowedUrl(r,n.allowedHosts)?null:{data:new URL(r),filename:e.name??`teams-attachment-${t}`,mediaType:inferMediaType(e),type:`file`}}function readAttachmentUrl(e){return e.contentType===`application/vnd.microsoft.teams.file.download.info`&&isObject(e.content)&&typeof e.content.downloadUrl==`string`?e.content.downloadUrl:e.contentUrl&&!e.contentType.startsWith(`application/vnd.microsoft.card.`)?e.contentUrl:null}function inferMediaType(e){return e.contentType===`application/vnd.microsoft.teams.file.download.info`&&(isObject(e.content)&&typeof e.content.fileType==`string`?e.content.fileType:void 0)===`txt`?`text/plain`:e.contentType||`application/octet-stream`}function isAllowedUrl(e,t){if(t===`*`)return!0;let n;try{n=new URL(e)}catch{return!1}return t.some(e=>n.host===e||n.hostname===e)}export{buildTeamsTurnMessage,collectTeamsFileParts,createTeamsFetchFile,normalizeTeamsFilesPolicy};

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

@@ -0,0 +1,24 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { ConnectionAuthorizationOutcome } from "#protocol/message.js";
+import { type TeamsMention } from "#public/channels/teams/api.js";
+import type { TeamsMessageActivity } from "#public/channels/teams/inbound.js";
+import type { TeamsChannelEvents, TeamsContext, TeamsInboundResult } from "#public/channels/teams/teamsChannel.js";
+/** Default auth projection for Teams message actors. */
+export declare function defaultTeamsAuth(message: TeamsMessageActivity): SessionAuthContext;
+/** Default message hook: mention-gated dispatch with Teams user auth. */
+export declare function defaultOnMessage(ctx: TeamsContext, message: TeamsMessageActivity): Promise<TeamsInboundResult>;
+/** Built-in Teams event handlers for typing, replies, HITL, auth cards, and terminal errors. */
+export declare const defaultEvents: TeamsChannelEvents;
+/** Capitalizes the first character of a connection name for Teams auth card display (e.g. "linear" -> "Linear"). */
+export declare function formatConnectionDisplayName(connectionName: string): string;
+/** Builds final-state text for a completed connection authorization attempt. */
+export declare function buildAuthCompletedText(input: {
+    readonly displayName: string;
+    readonly outcome: ConnectionAuthorizationOutcome;
+    readonly reason?: string;
+}): string;
+/** Builds a Teams mention entity and matching text for one channel account. */
+export declare function teamsMentionUser(user: {
+    readonly id: string;
+    readonly name?: string;
+}): TeamsMention;