@dbx-tools/teams 0.3.44 → 0.4.0

package/lib/src/conversation.d.ts

@@ -0,0 +1,234 @@
+/**
+ * The Teams conversation turn: run a Mastra agent against an inbound Bot
+ * Framework activity and answer with Adaptive Card attachments.
+ *
+ * This is the piece that makes `POST /api/teams/activity` behave like a Teams
+ * bot rather than a chat API that happens to return JSON. A turn is:
+ *
+ *   1. read the user's text off the inbound `message` activity;
+ *   2. ANSWER it - a normal tool-using agent turn, with no mention of cards, so
+ *      the agent queries Genie / calls its tools exactly as it would on a
+ *      streaming chat endpoint;
+ *   3. FORMAT that answer into a {@link card.CardSpec} in a second pass, via
+ *      Mastra's `structuredOutput` (prompt-injected, see
+ *      {@link JSON_PROMPT_INJECTION});
+ *   4. compile the spec with the same deterministic builder the
+ *      `create_teams_card` tool uses, and attach it to an outbound activity.
+ *
+ * The two passes are the important part. Asking for the answer AND the card
+ * shape in ONE request makes the model treat formatting as the task: it emits a
+ * card straight away and never calls its tools, so a question that should have
+ * queried a data source came back as "I don't have a real system connected -
+ * here is a template card with placeholders". Answering first, then formatting a
+ * REAL answer, makes this endpoint's content identical to the streaming
+ * endpoint's; only the presentation differs.
+ *
+ * Formatting is also why the turn does not simply rely on the agent calling
+ * `create_teams_card`: on this endpoint a card IS the response format, so it
+ * should be a property of the turn rather than a tool the model may forget.
+ * Agents keep the tool for the other direction - answering in prose on a normal
+ * chat endpoint and choosing to attach a card. When the agent DOES call it
+ * during the answering pass, that spec wins and the formatting pass is skipped.
+ *
+ * The conversation id doubles as the agent's memory thread id, so a client that
+ * keeps posting the same `conversation.id` gets a continuous conversation - the
+ * same mapping a real channel relies on.
+ *
+ * @module
+ */
+import { activity as activityContract, card } from "@dbx-tools/shared-teams";
+/**
+ * Minimal structural shape of the Mastra `Agent` this module drives.
+ *
+ * Declared structurally rather than importing `@mastra/core`'s `Agent`: this
+ * package must not depend on the Mastra plugin (the plugin depends on nothing
+ * here either), and a turn only ever needs `generate`. Any object with a
+ * compatible `generate` satisfies it, which also makes the turn trivially
+ * testable with a stub.
+ */
+export interface CardAgentLike {
+    generate(prompt: string, options: {
+        structuredOutput?: {
+            schema: typeof card.cardSpecSchema;
+            jsonPromptInjection?: boolean | "system" | "inline";
+        };
+        memory?: {
+            thread: string;
+            resource: string;
+        };
+        /**
+         * Mastra's per-turn `RequestContext`. Opaque here - the object comes from
+         * the agent plugin (see {@link AgentProviderLike.exports}) and is only
+         * forwarded - but REQUIRED for parity with the chat endpoints: Mastra's
+         * user-scoped tools read the AppKit user off it, so a turn without one
+         * answers "the data source is unreachable" where chat answers with data.
+         */
+        requestContext?: unknown;
+        abortSignal?: AbortSignal;
+    }): Promise<AgentResult>;
+}
+/**
+ * The slice of Mastra's `generate` result a turn reads.
+ *
+ * `toolResults` matters as much as `object` here: when structured output fails
+ * and the turn re-asks as prose, an agent holding the `create_teams_card` tool
+ * typically CALLS it, so the best available card spec is the tool's arguments -
+ * already in the right vocabulary - rather than anything in the prose.
+ */
+export interface AgentResult {
+    object?: unknown;
+    text?: string;
+    toolResults?: {
+        payload?: {
+            toolName?: string;
+            args?: unknown;
+        };
+        toolName?: string;
+        args?: unknown;
+    }[];
+}
+/** The bot's identity on outbound activities when the caller names none. */
+export declare const BOT_ACCOUNT: activityContract.ChannelAccount;
+/**
+ * Instructions for the FORMATTING pass only - turning an answer the agent has
+ * already produced into the card vocabulary.
+ *
+ * Deliberately NOT sent with the user's question. Asking for a card and an
+ * answer in one request makes the model treat formatting as the task: it emits a
+ * card immediately instead of calling its tools, so a question that should have
+ * queried Genie came back as "I don't have a real system connected - here is a
+ * template card". Formatting is a separate, second pass over a real answer.
+ */
+export declare const CARD_FORMAT_INSTRUCTIONS: string;
+/**
+ * Nudge added to the ANSWERING pass.
+ *
+ * The agent answers the question normally here - tools included - so this only
+ * asks for the shape that survives compression into a card well. It must not
+ * mention cards, or the model starts formatting instead of answering.
+ */
+export declare const CARD_ANSWER_INSTRUCTIONS: string;
+/**
+ * Structural shape of the sibling plugin that owns the agent registry - the
+ * slice of `@dbx-tools/appkit-mastra`'s `exports()` a turn needs.
+ *
+ * Matched structurally, by registered plugin NAME, rather than importing the
+ * Mastra plugin: this package stays a leaf add-on (it depends on no other
+ * dbx-tools runtime package, like node-email), the dependency direction stays
+ * one-way, and any plugin exposing the same `get` / `getDefault` pair can back
+ * the endpoint.
+ */
+export interface AgentProviderLike {
+    exports(): {
+        get(id: string): unknown;
+        getDefault(): unknown;
+        /**
+         * Builds the per-turn `RequestContext` the provider's tools expect. Optional
+         * so an older provider (or a differently-shaped one) still resolves an
+         * agent; the turn simply runs without user-scoped tool context then.
+         */
+        createRequestContext?(options: {
+            threadId?: string;
+            resourceId?: string;
+        }): Promise<unknown>;
+    };
+}
+/**
+ * Resolve the agent that answers a turn from the AppKit plugin registry.
+ *
+ * `agentId` picks a specific agent; omitted, the provider's default agent
+ * answers. Returns `null` when the provider is absent or the id is unknown, so
+ * the route can answer 503 / 404 instead of throwing.
+ */
+export declare const resolveCardAgent: (plugins: ReadonlyMap<string, unknown> | undefined, providerName: string, agentId?: string) => CardAgentLike | null;
+/** Options for {@link runCardTurn}. */
+export interface CardTurnOptions {
+    /** Cancels the agent call with the request. */
+    signal?: AbortSignal;
+    /** Overrides the bot identity stamped on the reply. */
+    bot?: activityContract.ChannelAccount;
+    /**
+     * Builds the Mastra `RequestContext` for the turn, from
+     * {@link resolveCardContextFactory}. Omitted, the turn still answers, but
+     * without the AppKit user its user-scoped tools cannot reach Databricks - so
+     * the route should always supply it.
+     */
+    createRequestContext?: CardContextFactory;
+}
+/** Builds the per-turn request context the agent's tools read. */
+export type CardContextFactory = (options: {
+    threadId?: string;
+    resourceId?: string;
+}) => Promise<unknown>;
+/**
+ * The agent plugin's request-context factory, when it exposes one.
+ *
+ * Resolved separately from the agent because it is the piece that gives an
+ * out-of-band turn the same tool reach as a chat turn; a provider without it
+ * still answers, just without user-scoped tools.
+ */
+export declare const resolveCardContextFactory: (plugins: ReadonlyMap<string, unknown> | undefined, providerName: string) => CardContextFactory | null;
+/**
+ * The text a `message` activity carries, or `null` when it carries none.
+ *
+ * A channel sends plenty of activities with no usable text (a `typing`
+ * indicator, a `conversationUpdate` when someone joins, or a `message` whose
+ * payload is only an attachment). Those are not errors - they simply produce no
+ * reply - so this returns `null` rather than throwing.
+ */
+export declare const promptOf: (inbound: activityContract.Activity) => string | null;
+/**
+ * Build an outbound activity carrying `cards`, addressed back to the sender of
+ * `inbound`.
+ *
+ * Exported because a client rendering an optimistic local reply, and a test
+ * asserting the envelope, both need the same construction the turn uses.
+ */
+export declare const toReplyActivity: (inbound: activityContract.Activity, cards: card.AdaptiveCard[], options?: {
+    bot?: activityContract.ChannelAccount;
+    text?: string;
+}) => activityContract.Activity;
+/**
+ * Recover a {@link card.CardSpec} from a full Adaptive Card DOCUMENT.
+ *
+ * A capable model asked for "a Microsoft Teams Adaptive Card" often answers with
+ * the finished 1.5 document instead of the small spec - correct Adaptive Card
+ * JSON, wrong schema, so `structuredOutput` rejects it (`title: expected
+ * string`) and a genuinely good answer is thrown away. Reading the document back
+ * into the spec vocabulary keeps it: the heading TextBlocks become
+ * title/subtitle, remaining TextBlocks the body, the FactSet the facts, and any
+ * `Action.OpenUrl` the actions.
+ *
+ * Deliberately tolerant about the container: `type` may be missing and the body
+ * may nest elements inside a `Container` / `ColumnSet`, so blocks are collected
+ * recursively and anything unrecognized is ignored.
+ */
+export declare const documentCardSpec: (value: unknown) => card.CardSpec | null;
+/**
+ * The card the model produced, wherever it ended up.
+ *
+ * `structuredOutput` rejects anything off-schema by THROWING, and Mastra puts
+ * the offending payload on the error (`details.value`) - so the model's real
+ * answer is recoverable from a failed call. Both the spec shape and a full
+ * Adaptive Card document are accepted, from an object or from JSON text.
+ */
+export declare const rejectedCardSpec: (err: unknown) => card.CardSpec | null;
+/**
+ * Run one conversation turn: drive `agent` with the inbound activity's text and
+ * return the activities to append to the transcript.
+ *
+ * Returns an EMPTY array for an activity that carries no prompt (a typing
+ * indicator, a join event), which is exactly what a bot does with one - the
+ * route answers `{ activities: [] }` and the transcript is unchanged.
+ *
+ * Two agent calls, in this order:
+ *
+ *   1. the ANSWER - no `structuredOutput`, so the agent's tools are available
+ *      and the content matches what the streaming endpoint would say;
+ *   2. the FORMAT - {@link formatAsCard} compiling that answer into a card.
+ *
+ * Every failure mode still yields the answer: a card the agent composed with
+ * `create_teams_card` during pass 1 short-circuits pass 2, and a failed pass 2
+ * falls back to {@link toCardSpec} over the answer text.
+ */
+export declare const runCardTurn: (agent: CardAgentLike, inbound: activityContract.Activity, options?: CardTurnOptions) => Promise<activityContract.Activity[]>;