toolroll 0.5.0

package/dist/teams-api.js

@@ -0,0 +1,204 @@
+/** Microsoft Teams through the Bot Framework REST surface: app credentials
+ * kept in an owner-only file, an outbound token per call, and inbound
+ * activities proved by the Bot Framework's signed token. No SDK. */
+import { chmodSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createPublicKey, randomBytes, verify as verifySignature } from "node:crypto";
+import { ChatDeliveryError, chatHash } from "./chat-delivery-state.js";
+import { chatObject as object } from "./chat-delivery.js";
+export class TeamsError extends ChatDeliveryError {
+}
+export const teamsCredentialFile = (dir) => join(dir, "teams-connection.json");
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const teamsGuid = (v) => typeof v === "string" && GUID.test(v);
+const validSecret = (v) => typeof v === "string" && /^[A-Za-z0-9._~-]{16,200}$/.test(v);
+export function teamsIdentity(app, tenant) {
+    return { installation: chatHash(`teams:${app.toLowerCase()}:${tenant.toLowerCase()}`), team: tenant.toLowerCase(), app: app.toLowerCase(), bot: `28:${app.toLowerCase()}`, workspace: "Microsoft Teams" };
+}
+export function loadTeamsCredentials(dir) {
+    try {
+        const v = JSON.parse(readFileSync(teamsCredentialFile(dir), "utf8"));
+        const identity = teamsGuid(v.app) && teamsGuid(v.tenant) ? teamsIdentity(v.app, v.tenant) : null;
+        return identity !== null && validSecret(v.secret) && v.installation === identity.installation && v.bot === identity.bot ? { ...identity, tenant: identity.team, secret: v.secret } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveTeamsCredentials(dir, value) {
+    const target = teamsCredentialFile(dir), temp = `${target}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(value) + "\n", { mode: 0o600, flag: "wx" });
+        chmodSync(temp, 0o600);
+        renameSync(temp, target);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+export function clearTeamsCredentials(dir) {
+    rmSync(teamsCredentialFile(dir), { force: true });
+}
+const TOKEN_URL = "https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token";
+const OPENID = "https://login.botframework.com/v1/.well-known/openidconfiguration";
+const ISSUERS = new Set(["https://api.botframework.com"]);
+let cachedToken = null;
+/** A bot access token for outbound calls (client credentials), cached until shortly before expiry. */
+export async function teamsAccessToken(credentials, fetcher = fetch, now = Date.now()) {
+    if (cachedToken !== null && cachedToken.app === credentials.app && cachedToken.expires > now + 60_000)
+        return cachedToken.value;
+    let response;
+    try {
+        response = await fetcher(TOKEN_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ grant_type: "client_credentials", client_id: credentials.app, client_secret: credentials.secret, scope: "https://api.botframework.com/.default" }),
+            redirect: "error",
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch {
+        throw new TeamsError("Microsoft sign-in is unreachable", 15_000, true);
+    }
+    if (response.status === 401 || response.status === 400)
+        throw new TeamsError("Microsoft rejected the app credentials. Check the app id, tenant and secret.", 300_000);
+    if (!response.ok)
+        throw new TeamsError("Microsoft sign-in failed", 15_000, true);
+    const data = object(await response.json().catch(() => ({})));
+    if (typeof data.access_token !== "string")
+        throw new TeamsError("Microsoft returned no access token", 15_000, true);
+    cachedToken = { app: credentials.app, value: data.access_token, expires: now + Math.max(60, Number(data.expires_in ?? 3600)) * 1000 };
+    return cachedToken.value;
+}
+export function forgetTeamsToken() { cachedToken = null; }
+/** Outbound Bot Framework calls: only conversation routes, only under an https service URL Microsoft named in a signed token. */
+export function teamsApi(credentials, fetcher = fetch) {
+    return async (method, serviceUrl, path, body) => {
+        if (!/^\/v3\/conversations\/[A-Za-z0-9:@._%-]+(?:\/activities(?:\/[A-Za-z0-9:._%-]+)?|\/members(?:\/[A-Za-z0-9:._%-]+)?)$/.test(path))
+            throw new TeamsError("Invalid Teams request");
+        let base;
+        try {
+            base = new URL(serviceUrl);
+        }
+        catch {
+            throw new TeamsError("Invalid Teams service URL");
+        }
+        if (base.protocol !== "https:" || base.username || base.password || base.search || base.hash)
+            throw new TeamsError("Invalid Teams service URL");
+        const token = await teamsAccessToken(credentials, fetcher);
+        let response;
+        try {
+            response = await fetcher(`${base.origin}${base.pathname.replace(/\/$/, "")}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+                redirect: "error",
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch {
+            throw new TeamsError("Teams is unreachable", 15_000, true);
+        }
+        if (response.status === 401) {
+            forgetTeamsToken();
+            throw new TeamsError("Teams rejected the bot token", 30_000);
+        }
+        if (response.status === 429)
+            throw new TeamsError("Teams asked to slow down", Math.max(5, Number(response.headers.get("retry-after") ?? 5)) * 1000);
+        if (!response.ok)
+            throw new TeamsError(`Teams refused the request (${response.status})`, 15_000, response.status >= 500);
+        const text = await response.text();
+        if (text.trim() === "")
+            return {};
+        try {
+            return object(JSON.parse(text));
+        }
+        catch {
+            return {};
+        }
+    };
+}
+/** Confirm the app can sign in; the tenant and app id shape the installation identity. */
+export async function checkTeamsCredentials(app, tenant, secret, fetcher = fetch) {
+    if (!teamsGuid(app) || !teamsGuid(tenant))
+        throw new TeamsError("Enter the app (client) id and the directory (tenant) id from Microsoft Entra");
+    if (!validSecret(secret))
+        throw new TeamsError("Enter the app's client secret");
+    const identity = teamsIdentity(app, tenant);
+    forgetTeamsToken();
+    await teamsAccessToken({ app: identity.app, secret }, fetcher);
+    return { ...identity, tenant: identity.team, secret };
+}
+let keyCache = null;
+async function signingKeys(fetcher, now) {
+    if (keyCache !== null && keyCache.fetched + 86_400_000 > now)
+        return keyCache.keys;
+    const config = object(await (await fetcher(OPENID, { signal: AbortSignal.timeout(15_000) })).json());
+    if (typeof config.jwks_uri !== "string" || !config.jwks_uri.startsWith("https://"))
+        throw new TeamsError("Bot Framework key metadata is unavailable", 15_000, true);
+    const jwks = object(await (await fetcher(config.jwks_uri, { signal: AbortSignal.timeout(15_000) })).json());
+    const keys = Array.isArray(jwks.keys) ? jwks.keys : [];
+    keyCache = { fetched: now, keys };
+    return keys;
+}
+export function forgetTeamsKeys() { keyCache = null; }
+const b64url = (value) => Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+/**
+ * Prove an inbound activity came from the Bot Framework for this app: an
+ * RS256 token from the Bot Framework issuer, for this app id, not expired,
+ * signed by a published key. The serviceurl claim must match the activity
+ * so a stolen token cannot redirect replies.
+ */
+export async function verifyTeamsToken(header, appId, fetcher = fetch, now = Date.now()) {
+    const match = /^Bearer ([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$/.exec(header ?? "");
+    if (match === null)
+        return null;
+    let head, claims;
+    try {
+        head = object(JSON.parse(b64url(match[1]).toString("utf8")));
+        claims = object(JSON.parse(b64url(match[2]).toString("utf8")));
+    }
+    catch {
+        return null;
+    }
+    if (head.alg !== "RS256" || typeof head.kid !== "string")
+        return null;
+    if (typeof claims.iss !== "string" || !ISSUERS.has(claims.iss))
+        return null;
+    const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (!audience.some(one => typeof one === "string" && one.toLowerCase() === appId.toLowerCase()))
+        return null;
+    if (typeof claims.exp !== "number" || claims.exp * 1000 < now - 300_000)
+        return null;
+    if (typeof claims.nbf === "number" && claims.nbf * 1000 > now + 300_000)
+        return null;
+    let keys;
+    try {
+        keys = await signingKeys(fetcher, now);
+    }
+    catch {
+        return null;
+    }
+    let key = keys.find(one => one.kid === head.kid);
+    if (key === undefined && keyCache !== null) {
+        keyCache = null;
+        try {
+            key = (await signingKeys(fetcher, now)).find(one => one.kid === head.kid);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (key === undefined || key.kty !== "RSA" || typeof key.n !== "string" || typeof key.e !== "string")
+        return null;
+    try {
+        const publicKey = createPublicKey({ key: { kty: "RSA", n: key.n, e: key.e }, format: "jwk" });
+        const ok = verifySignature("RSA-SHA256", Buffer.from(`${match[1]}.${match[2]}`, "utf8"), publicKey, b64url(match[3]));
+        if (!ok)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { appId, serviceUrl: typeof claims.serviceurl === "string" ? claims.serviceurl : null };
+}

package/dist/teams-chat.d.ts

@@ -0,0 +1,26 @@
+import { ChatState, type ChatIdentity } from "./chat-delivery-state.js";
+import { type ChatDeliveryOptions } from "./chat-delivery.js";
+import { type TeamsApi } from "./teams-api.js";
+export type TeamsChatOptions = Omit<ChatDeliveryOptions, "state" | "label" | "member" | "partSize" | "maxProposal"> & {
+    api: TeamsApi;
+};
+export declare const teamsUserId: (v: unknown) => v is string;
+/** A conversation id; a channel post's carries its thread as ";messageid=<first message>" (v89). */
+export declare const teamsConversationId: (v: unknown) => v is string;
+export declare function teamsMember(api: TeamsApi, state: ChatState, installation: string, member: string, channel: string): Promise<boolean>;
+export declare const teamsDelivery: (options: TeamsChatOptions) => ChatDeliveryOptions;
+export declare const processTeamsEvent: (options: TeamsChatOptions) => Promise<boolean>;
+export declare const planTeamsRooms: (options: TeamsChatOptions) => Promise<void>;
+export declare const planTeamsNotifications: (options: TeamsChatOptions) => Promise<void>;
+/**
+ * Save one Bot Framework activity before it is acknowledged: a personal
+ * message (or `pair <code>`), a channel message where the bot was mentioned,
+ * or an Adaptive Card submit carrying one of our tokens. The token that
+ * authenticated the request is never stored; only the service URL the
+ * conversation replies through is kept, per conversation.
+ */
+export declare function receiveTeams(state: ChatState, identity: ChatIdentity, raw: unknown, serviceUrlClaim: string | null, now: Date): boolean;
+/** One Adaptive Card: plain text, then the buttons (submit tokens, or one link). */
+export declare function teamsCard(text: string, actions: Record<string, unknown>[]): Record<string, unknown>;
+/** Send the next pending part: a plain message, an edit, or a card with its tokens. */
+export declare function deliverTeamsPart(options: TeamsChatOptions): Promise<boolean>;

package/dist/teams-chat.js

@@ -0,0 +1,215 @@
+/** Microsoft Teams on the shared chat layer: activities in, Adaptive Cards
+ * out, the same durable receipts, rooms and commands as every other channel. */
+import { chatQuestionButtons } from "./teammate-question.js";
+import { ChatState, chatHash } from "./chat-delivery-state.js";
+import { channelAccess, chatObject as object, planChatNotifications, planRoomMessages, processChatEvent } from "./chat-delivery.js";
+import { roomCommand } from "./chat-rooms.js";
+import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
+import { armedCardText, armedYesLabel, proposalLink, proposalOutcomeText, proposalPreview } from "./chat-channel.js";
+import { chatFlowButtons } from "./chat-flow.js";
+import { channelInbox } from "./chat-inbox.js";
+import { chatResultHref } from "./chat-controls.js";
+import { TeamsError } from "./teams-api.js";
+const serviceKey = (conversation) => `serviceUrl:${conversation}`;
+export const teamsUserId = (v) => typeof v === "string" && /^29:[A-Za-z0-9_=-]{10,200}$/.test(v);
+/** A conversation id; a channel post's carries its thread as ";messageid=<first message>" (v89). */
+export const teamsConversationId = (v) => typeof v === "string" && /^[A-Za-z0-9:@._%-]{8,300}(;messageid=[0-9]{1,20})?$/.test(v);
+const validServiceUrl = (v) => {
+    if (typeof v !== "string")
+        return false;
+    try {
+        const url = new URL(v);
+        return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash;
+    }
+    catch {
+        return false;
+    }
+};
+export async function teamsMember(api, state, installation, member, channel) {
+    const serviceUrl = state.meta(installation, serviceKey(channel));
+    if (serviceUrl === null)
+        return false;
+    try {
+        const found = await api("GET", serviceUrl, `/v3/conversations/${encodeURIComponent(channel)}/members/${encodeURIComponent(member)}`);
+        return found.id === member;
+    }
+    catch (error) {
+        if (error instanceof TeamsError && error.uncertain)
+            throw error;
+        return false;
+    }
+}
+export const teamsDelivery = (options) => {
+    const state = new ChatState(options.store, "teams");
+    return {
+        ...options,
+        state,
+        label: "Teams",
+        member: (member, channel) => teamsMember(options.api, state, options.identity.installation, member, channel),
+        partSize: 3500,
+        maxProposal: 6000,
+    };
+};
+export const processTeamsEvent = (options) => processChatEvent(teamsDelivery(options));
+export const planTeamsRooms = (options) => planRoomMessages(teamsDelivery(options));
+export const planTeamsNotifications = (options) => planChatNotifications(teamsDelivery(options));
+/** Strip the bot's own mention from channel text; Teams delivers channel messages only when the bot is mentioned. */
+function withoutMentions(text) {
+    return text.replace(/<at>[^<]*<\/at>/g, "").replace(/\s+/g, " ").trim();
+}
+/**
+ * Save one Bot Framework activity before it is acknowledged: a personal
+ * message (or `pair <code>`), a channel message where the bot was mentioned,
+ * or an Adaptive Card submit carrying one of our tokens. The token that
+ * authenticated the request is never stored; only the service URL the
+ * conversation replies through is kept, per conversation.
+ */
+export function receiveTeams(state, identity, raw, serviceUrlClaim, now) {
+    const activity = object(raw);
+    if (activity.type !== "message")
+        return false;
+    const conversation = object(activity.conversation), from = object(activity.from), recipient = object(activity.recipient);
+    const channel = conversation.id, member = from.id, id = activity.id;
+    const isRoom = conversation.conversationType === "channel" || conversation.conversationType === "groupChat";
+    if (!teamsConversationId(channel) || !teamsUserId(member) || typeof id !== "string" || id.length > 200)
+        return false;
+    if (recipient.id !== identity.bot || (typeof conversation.tenantId === "string" && conversation.tenantId.toLowerCase() !== identity.team))
+        return false;
+    if (!validServiceUrl(activity.serviceUrl) || (serviceUrlClaim !== null && serviceUrlClaim.replace(/\/$/, "") !== activity.serviceUrl.replace(/\/$/, "")))
+        return false;
+    if (!isRoom && conversation.conversationType !== "personal")
+        return false;
+    const value = object(activity.value);
+    const submitted = typeof value.so === "string" && /^[a-f0-9]{32}$/.test(value.so) ? value.so : null;
+    let kind, payload, eventId;
+    if (submitted !== null) {
+        kind = "action";
+        payload = { token: submitted };
+        eventId = chatHash(`${identity.installation}:action:${member}:${activity.replyToId ?? id}:${submitted}`);
+    }
+    else {
+        if (typeof activity.text !== "string")
+            return false;
+        const text = isRoom ? withoutMentions(activity.text) : activity.text.trim();
+        const pair = /^pair ([a-f0-9]{32})$/.exec(text);
+        kind = pair ? "pair" : "message";
+        payload = pair ? { hash: chatHash(pair[1]) } : { text: text.slice(0, MATE_MESSAGE_MAX_CHARS + 1), originalLength: text.length,
+            ...(Array.isArray(activity.attachments) && activity.attachments.length > 0 ? { unsupported: "Incoming files are not supported yet. Describe the request in a message; saved result screenshots open from their links." } : {}) };
+        eventId = chatHash(`${identity.installation}:message:${id}`);
+    }
+    // v89: a channel that feeds a flow takes anyone's message (as a card, with no say over anything); "flow 12" connects one.
+    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "teams", identity.installation, channel, String(payload.text ?? "")) : { watched: false, command: false };
+    const roomish = isRoom && (state.room(identity.installation, channel) !== null || (kind === "message" && roomCommand(String(payload.text ?? "")) !== null) || inbox.watched || inbox.command);
+    if (isRoom && !roomish)
+        return false;
+    const binding = state.bindingFor(identity.installation, member);
+    const open = inbox.watched && !inbox.command;
+    if (kind === "pair" ? !!binding || isRoom : !open && (!binding || !state.live(binding) || (binding.channel !== channel && !roomish)))
+        return false;
+    return state.store.transact(() => {
+        state.setMeta(identity.installation, serviceKey(channel), activity.serviceUrl, now);
+        return state.enqueue({
+            id: eventId, installation: identity.installation, binding: kind === "pair" || binding === null ? null : binding.id, kind, channel, member,
+            ts: submitted !== null ? String(activity.replyToId ?? id) : id, thread: submitted !== null ? String(activity.replyToId ?? id) : id,
+            payload: JSON.stringify(payload), created: now.toISOString(),
+        });
+    });
+}
+function openUrlAction(origin, target) {
+    if (!origin || !target || !target.path.startsWith("/") || target.path.startsWith("//"))
+        return [];
+    try {
+        const url = new URL(origin);
+        if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
+            return [];
+        return [{ type: "Action.OpenUrl", title: target.label.slice(0, 80), url: url.origin + target.path }];
+    }
+    catch {
+        return [];
+    }
+}
+/** One Adaptive Card: plain text, then the buttons (submit tokens, or one link). */
+export function teamsCard(text, actions) {
+    return {
+        type: "message",
+        attachments: [{
+                contentType: "application/vnd.microsoft.card.adaptive",
+                content: { type: "AdaptiveCard", version: "1.4", $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+                    body: [{ type: "TextBlock", text: text.slice(0, 6000), wrap: true }], ...(actions.length ? { actions } : {}) },
+            }],
+    };
+}
+/** Send the next pending part: a plain message, an edit, or a card with its tokens. */
+export async function deliverTeamsPart(options) {
+    const shared = teamsDelivery(options), state = shared.state, { store, identity } = options, now = options.clock?.() ?? new Date();
+    if (!options.current() || !state.owns(identity.installation, options.owner, now))
+        return false;
+    const row = state.prepare("SELECT p.* FROM chat_part p JOIN chat_event e ON e.id=p.event WHERE e.installation=? AND p.state='pending' AND (e.kind!='notice' OR ?=1) AND (p.next_at IS NULL OR p.next_at<=?) ORDER BY p.created,p.id LIMIT 1").get(identity.installation, options.canNotify?.() === false ? 0 : 1, now.toISOString());
+    if (!row)
+        return false;
+    const event = state.event(row.event), binding = event.binding === null ? null : state.bindingById(event.binding);
+    if (!binding || new Date(row.created).getTime() + 86_400_000 < now.getTime()) {
+        state.prepare("UPDATE chat_part SET state='dropped',problem='Delivery expired or access changed; open the saved chat' WHERE id=?").run(row.id);
+        return true;
+    }
+    try {
+        const session = event.session === null ? null : store.getMateSession(event.session);
+        const repos = await channelAccess(shared, binding, session?.ceilingDigest);
+        if (event.kind === "notice" && options.canNotify?.() === false)
+            return false;
+        const content = JSON.parse(row.payload);
+        const destination = content.channel ?? binding.channel;
+        const serviceUrl = state.meta(identity.installation, serviceKey(destination));
+        if (serviceUrl === null)
+            throw new TeamsError("This Teams conversation has no known service address yet; send it a message first", 60_000);
+        if (content.task && !repos.includes(store.lookupRef(content.task)?.repo ?? ""))
+            throw new TeamsError("Connected projects changed");
+        let text = content.text, actions = [];
+        if (content.image) {
+            text = `${content.text}\n\nScreenshots open from the saved result.`;
+            actions = openUrlAction(options.origin(), { label: "Open result", path: chatResultHref(content.image.taskId, content.image.run, "checks") });
+        }
+        if (content.proposal) {
+            const proposal = store.getMateProposal(content.proposal);
+            if (!proposal)
+                text = "This proposal is unavailable.";
+            else if (proposal.state !== "pending")
+                text = proposalOutcomeText(proposal);
+            else {
+                const preview = proposalPreview(store, proposal, repos, "teams");
+                text = content.phase === "armed" ? armedCardText(proposal, preview.text) : preview.text.replace("\n\nConfirm or Dismiss below. Nothing changes until you confirm.", "");
+                if (preview.buttons && preview.text.length <= 6000) {
+                    actions = state.prepare("SELECT token,phase FROM chat_action WHERE part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(row.id, now.toISOString())
+                        .map(action => ({ type: "Action.Submit", title: action.phase === "yes" ? armedYesLabel(proposal) : action.phase === "cancel" ? "Cancel" : action.phase === "dismiss" ? "Dismiss" : "Confirm", data: { so: String(action.token) } }));
+                    if (!actions.length)
+                        text = "This confirmation expired. Ask for a fresh proposal.";
+                }
+                else {
+                    actions = openUrlAction(options.origin(), proposalLink(store, proposal, repos, "teams") ?? { label: "Review action", path: "/chat" });
+                    text = "Review the full action in Toolroll before confirming.";
+                }
+            }
+        }
+        else if (!content.image) {
+            // A flow decision (v88): Approve / Edit / Send back, then the link.
+            const flow = content.flow ? chatFlowButtons(state, row.id, now).map(one => ({ type: "Action.Submit", title: one.label, data: { so: one.token }, ...(one.action === "approve" ? { style: "positive" } : {}) })) : [];
+            // A teammate's question (v93): its options, then "Answer in words".
+            const asked = content.question ? chatQuestionButtons(state, row.id, now).map(one => ({ type: "Action.Submit", title: one.label.slice(0, 80), data: { so: one.token } })) : [];
+            actions = [...flow, ...asked, ...openUrlAction(options.origin(), content.link)];
+        }
+        const target = content.edit ?? row.message;
+        const body = actions.length || content.proposal ? teamsCard(text, actions) : { type: "message", text, textFormat: "plain" };
+        const answer = await options.api(target ? "PUT" : "POST", serviceUrl, `/v3/conversations/${encodeURIComponent(destination)}/activities${target ? `/${encodeURIComponent(target)}` : ""}`, body);
+        const messageId = target ?? (typeof answer.id === "string" ? answer.id : null);
+        if (messageId === null)
+            throw new TeamsError("Teams did not confirm the message", 15_000, true);
+        state.prepare("UPDATE chat_part SET state='sent',message=?,attempts=attempts+1,next_at=NULL,problem=NULL WHERE id=?").run(messageId, row.id);
+        return true;
+    }
+    catch (error) {
+        const problem = error instanceof TeamsError ? error : new TeamsError("Teams delivery failed", 15_000, true);
+        state.prepare("UPDATE chat_part SET attempts=attempts+1,uncertain=?,next_at=?,problem=?,state=CASE WHEN attempts>=20 THEN 'dropped' ELSE state END WHERE id=?")
+            .run(problem.uncertain ? 1 : 0, new Date(now.getTime() + problem.retryMs).toISOString(), problem.message, row.id);
+        return true;
+    }
+}

package/dist/teams-settings.d.ts

@@ -0,0 +1,12 @@
+/** Settings → Teams: connect the Entra app once (operator), then each
+ * teammate pairs their own Teams account. The messaging endpoint the bot
+ * registration must point at is shown here; it has to be reachable from the
+ * internet, which a tailnet-only address is not. */
+import type { Store } from "./store.js";
+export declare function teamsSettingsHtml(store: Store, dir: string, csrf: string, options?: {
+    code?: string;
+    problem?: string;
+    now?: Date;
+    who?: string;
+    publicUrl?: string | null;
+}): string;

package/dist/teams-settings.js

@@ -0,0 +1,57 @@
+import { ChatState } from "./chat-delivery-state.js";
+import { loadTeamsCredentials } from "./teams-api.js";
+import { loadPrimary } from "./webhooks.js";
+import { TEAMS_MESSAGES_PATH } from "./teams.js";
+const escape = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+export function teamsSettingsHtml(store, dir, csrf, options = {}) {
+    const credentials = loadTeamsCredentials(dir), state = new ChatState(store, "teams");
+    const bindings = credentials ? state.bindings(credentials.installation).filter(one => state.live(one)) : [];
+    const binding = options.who === undefined ? null : bindings.find(one => one.approver === options.who) ?? null;
+    const others = bindings.length - (binding === null ? 0 : 1);
+    const runtime = credentials ? state.db.prepare("SELECT connected,problem,lease_until FROM teams_runtime WHERE installation=?").get(credentials.installation) : null;
+    const now = options.now ?? new Date();
+    const live = runtime && typeof runtime.lease_until === "string" && runtime.lease_until > now.toISOString() && runtime.connected;
+    const hidden = `<input type="hidden" name="csrf" value="${escape(csrf)}">`;
+    const password = '<label>Your Toolroll password<input style="min-height:44px" type="password" name="password" autocomplete="current-password" required></label>';
+    const post = (action, content) => `<form method="post" action="/settings/teams/${action}" class="card">${hidden}${content}</form>`;
+    const endpoint = options.publicUrl ? `${options.publicUrl.replace(/\/$/, "")}${TEAMS_MESSAGES_PATH}` : null;
+    let content = "";
+    if (!credentials) {
+        content =
+            "<p>Manage projects and review results in a Teams chat, and let a channel follow a team conversation.</p>" +
+                '<details open><summary>Register the bot</summary><ol><li>In <a href="https://portal.azure.com" target="_blank" rel="noopener noreferrer">Azure</a>, create an <em>Azure Bot</em> with a new single-tenant app registration; note the app (client) id and the directory (tenant) id, and create a client secret.</li>' +
+                `<li>Set its messaging endpoint to <code>${endpoint === null ? "https://your-public-address" + TEAMS_MESSAGES_PATH : escape(endpoint)}</code>. Microsoft must reach it from the internet: a tailnet-only address needs Tailscale Funnel (or another public tunnel) on that path.</li>` +
+                "<li>Enable the Microsoft Teams channel on the bot, then add the app to Teams (personal scope; team scope for channels).</li></ol></details>" +
+                post("connect", '<label>App (client) id<input style="min-height:44px" type="text" name="app-id" autocomplete="off" required></label>' +
+                    '<label>Directory (tenant) id<input style="min-height:44px" type="text" name="tenant" autocomplete="off" required></label>' +
+                    '<label>Client secret<input style="min-height:44px" type="password" name="secret" autocomplete="off" required></label>' +
+                    password + '<p class="meta">The secret stays on this installation. Next, pair your own Teams account.</p><button type="submit">Connect Teams</button>');
+    }
+    else {
+        content = `<p><strong>Microsoft Teams</strong> · ${live ? "Signed in" : "Waiting for sign-in"}</p>`;
+        if (endpoint !== null)
+            content += `<p class="meta">Messaging endpoint: <code>${escape(endpoint)}</code> — must be reachable from the internet.</p>`;
+        if (runtime?.problem)
+            content += `<p role="status">${escape(String(runtime.problem))}</p>`;
+        if (!live && !runtime?.problem)
+            content += "<p>Keep the Toolroll worker running to answer Teams messages.</p>";
+        if (options.code) {
+            content += "<h2>Pair your account</h2><p>Send this to the Toolroll bot in a personal Teams chat. It expires in 10 minutes.</p>" +
+                `<label>Pairing message<input type="text" readonly value="pair ${escape(options.code)}" autocomplete="off" style="width:100%;max-width:100%;font-size:14px;min-height:44px"></label>` +
+                '<a class="button-link" style="min-height:44px;white-space:nowrap" href="/settings/teams">Check connection</a>';
+        }
+        else if (binding && state.live(binding)) {
+            content += `<p>Your Teams account is paired.${others ? ` ${others} teammate${others === 1 ? " is" : "s are"} paired too.` : ""}</p>` +
+                "<p>Try “What needs my attention?” or send <code>status</code>. In a channel, mention the bot with <code>team</code> to follow a conversation.</p>" +
+                '<p><a href="/chat">Open saved chat</a></p>' +
+                (loadPrimary(process.env, dir) === "teams" ? "<p>Task updates are sent here.</p>" : post("alerts", '<button type="submit">Send task updates here</button>')) +
+                post("unpair", password + '<p class="meta">Unpairing ends every open button in your chat. Teammates are unaffected.</p><button type="submit">Unpair my account</button>');
+        }
+        else {
+            content += post("pair", "<h2>Pair your account</h2><p>Your paired Teams account can read your connected projects and confirm proposed changes. Password approvals still open in Toolroll." +
+                (others ? ` ${others} teammate${others === 1 ? " is" : "s are"} already paired.` : "") + "</p>" + password + '<button type="submit">Create pairing code</button>');
+        }
+        content += "<details><summary>Connection settings</summary>" + post("disconnect", password + '<button type="submit">Disconnect Teams</button>') + "</details>";
+    }
+    return `<section style="max-width:42rem;overflow-wrap:anywhere"><p><a href="/settings">Settings</a></p><h1>Teams</h1>${options.problem ? `<p class="problem" role="alert">${escape(options.problem)}</p>` : ""}${content}</section>`;
+}

package/dist/teams.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { chatObject as object } from "./chat-delivery.js";
+import { type TeamsChatOptions } from "./teams-chat.js";
+import type { Store } from "./store.js";
+export declare const TEAMS_ACTIVITY_BYTES: number;
+export declare const TEAMS_MESSAGES_PATH = "/teams/messages";
+/** The receiver: prove the Bot Framework token for this app, save the activity, acknowledge. Nothing runs here. */
+export declare function handleTeamsHttp(request: IncomingMessage, response: ServerResponse, options: {
+    store: Store;
+    dir: string;
+    fetcher?: typeof fetch;
+    clock?: () => Date;
+}): Promise<boolean>;
+/** The worker-side loop: a lease per installation, one pass a second. */
+export declare function followTeams(options: Omit<TeamsChatOptions, "identity" | "api" | "owner" | "current"> & {
+    dir: string;
+    signal: AbortSignal;
+    notifications: () => boolean;
+    fetcher?: typeof fetch;
+}): Promise<void>;
+export { object };