@pellux/goodvibes-tui 0.18.4

package/src/channels/builtin-runtime.ts

@@ -0,0 +1,443 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type {
+  ChannelAccountLifecycleAction,
+  ChannelAccountLifecycleResult,
+  ChannelAccountRecord,
+  ChannelActorAuthorizationRequest,
+  ChannelActorAuthorizationResult,
+  ChannelCapabilityDescriptor,
+  ChannelConversationKind,
+  ChannelDirectoryEntry,
+  ChannelDirectoryQueryOptions,
+  ChannelOperatorActionDescriptor,
+  ChannelResolvedTarget,
+  ChannelRenderRequest,
+  ChannelRenderResult,
+  ChannelSurface,
+  ChannelTargetResolveOptions,
+  ChannelToolDescriptor,
+} from '@pellux/goodvibes-sdk/platform/channels/types';
+import type { ChannelPlugin } from './plugin-registry.ts';
+import type { ProviderRuntimeSurface } from './provider-runtime.ts';
+import { buildBuiltinAccount, resolveBuiltinAccount } from './builtin/accounts.ts';
+import {
+  buildBuiltinContractHooks,
+  editBuiltinAllowlist,
+  getBuiltinDoctorReport,
+  getBuiltinLifecycleState,
+  listBuiltinRepairActions,
+  migrateBuiltinLifecycle,
+  resolveBuiltinAllowlist,
+} from './builtin/contracts.ts';
+import {
+  listBuiltinCapabilities,
+  listBuiltinOperatorActions,
+  listBuiltinTools,
+} from '@pellux/goodvibes-sdk/platform/channels/builtin/descriptors';
+import { getBuiltinSetupSchema } from './builtin/setup-schema.ts';
+import { registerBuiltinChannelPlugins } from './builtin/plugins.ts';
+import type { BuiltinChannelRuntimeDeps, ManagedSurface } from './builtin/shared.ts';
+import {
+  authorizeBuiltinActorAction,
+  runBuiltinAccountAction,
+  runBuiltinProviderApi,
+} from './builtin/account-actions.ts';
+import {
+  readConversationKind,
+  readDirectoryScope,
+  readLifecycleAction,
+} from '@pellux/goodvibes-sdk/platform/channels/builtin/parsing';
+import {
+  listBuiltinAgentTools,
+  notifyBuiltinApprovalViaRouter,
+  renderBuiltinChannelEvent,
+} from './builtin/rendering.ts';
+import { providerRuntimeStatus as providerRuntimeStatusForSurface } from './builtin/surfaces.ts';
+import {
+  inferBuiltinTargetConversationKind,
+  lookupBuiltinDirectory,
+  parseBuiltinExplicitTarget,
+  resolveBuiltinParentConversationCandidates,
+  resolveBuiltinSessionTarget,
+  resolveBuiltinTarget,
+} from './builtin/targets.ts';
+
+export class BuiltinChannelRuntime {
+  constructor(private readonly deps: BuiltinChannelRuntimeDeps) {}
+
+  registerPlugins(): void {
+    registerBuiltinChannelPlugins({
+      deps: this.deps,
+      buildAccount: (surface) => this.buildAccount(surface),
+      resolveAccount: (surface, accountId) => this.resolveAccount(surface, accountId),
+      listCapabilities: (surface) => this.listCapabilities(surface),
+      listTools: (surface) => this.listTools(surface),
+      runTool: (surface, toolId, input) => this.runTool(surface, toolId, input),
+      listOperatorActions: (surface) => this.listOperatorActions(surface),
+      runOperatorAction: (surface, actionId, input) => this.runOperatorAction(surface, actionId, input),
+      buildContractHooks: (surface) => this.buildContractHooks(surface),
+      buildProductHooks: (surface) => this.buildProductHooks(surface),
+      lookupDirectory: (surface, query, options) => this.lookupDirectory(surface, query, options),
+      lookupRouteDirectory: (surface, query, options) => this.lookupRouteDirectory(surface, query, options),
+      notifyApprovalViaRouter: (surface, approval, binding) => this.notifyApprovalViaRouter(surface, approval, binding),
+      providerRuntimeStatus: (surface) => this.providerRuntimeStatus(surface),
+    });
+  }
+
+  private accountContext() {
+    return {
+      deps: this.deps,
+      providerRuntimeStatus: (surface: ProviderRuntimeSurface) => this.providerRuntimeStatus(surface),
+    };
+  }
+
+  async buildAccount(surface: ChannelSurface): Promise<ChannelAccountRecord> {
+    return buildBuiltinAccount(this.accountContext(), surface);
+  }
+
+  async resolveAccount(surface: ChannelSurface, accountId: string): Promise<ChannelAccountRecord | null> {
+    return resolveBuiltinAccount(this.accountContext(), surface, accountId);
+  }
+
+  private contractContext() {
+    return {
+      deps: this.deps,
+      channelPolicy: this.deps.channelPolicy,
+      buildAccount: (surface: ChannelSurface) => this.buildAccount(surface),
+      resolveAccount: (surface: ChannelSurface, accountId: string) => this.resolveAccount(surface, accountId),
+      resolveTarget: (surface: ChannelSurface, options: ChannelTargetResolveOptions) => this.resolveTarget(surface, options),
+    };
+  }
+
+  async listCapabilities(surface: ChannelSurface): Promise<ChannelCapabilityDescriptor[]> {
+    const account = await this.buildAccount(surface);
+    const plugin = this.deps.channelPlugins.getBySurface(surface);
+    return listBuiltinCapabilities(surface, account, plugin?.capabilities ?? []);
+  }
+
+  listOperatorActions(surface: ChannelSurface): ChannelOperatorActionDescriptor[] {
+    return listBuiltinOperatorActions(surface);
+  }
+
+  listTools(surface: ChannelSurface): ChannelToolDescriptor[] {
+    return listBuiltinTools(surface);
+  }
+
+  async runTool(surface: ChannelSurface, toolId: string, input?: Record<string, unknown>): Promise<unknown> {
+    const tool = this.listTools(surface).find((entry) => entry.id === toolId || entry.name === toolId);
+    if (!tool) return null;
+    const actionId = tool.actionIds[0];
+    if (!actionId) return null;
+    return this.runOperatorAction(surface, actionId, input);
+  }
+
+  async runOperatorAction(
+    surface: ChannelSurface,
+    actionId: string,
+    input?: Record<string, unknown>,
+  ): Promise<unknown> {
+    if (actionId === 'inspect-account') {
+      const accountId = typeof input?.accountId === 'string' ? input.accountId : undefined;
+      return accountId ? this.resolveAccount(surface, accountId) : this.buildAccount(surface);
+    }
+    if (actionId === 'inspect-status') {
+      return this.deps.channelPlugins.listStatus().then((entries) => entries.find((entry) => entry.surface === surface) ?? null);
+    }
+    if (actionId === 'setup-schema') {
+      return this.getSetupSchema(surface);
+    }
+    if (actionId === 'doctor') {
+      const accountId = typeof input?.accountId === 'string' ? input.accountId : undefined;
+      return this.getDoctorReport(surface, accountId);
+    }
+    if (actionId === 'repair-actions') {
+      const accountId = typeof input?.accountId === 'string' ? input.accountId : undefined;
+      return this.listRepairActions(surface, accountId);
+    }
+    if (actionId === 'lifecycle-state') {
+      const accountId = typeof input?.accountId === 'string' ? input.accountId : undefined;
+      return this.getLifecycleState(surface, accountId);
+    }
+    if (actionId === 'migrate-lifecycle') {
+      const accountId = typeof input?.accountId === 'string' ? input.accountId : undefined;
+      return this.migrateLifecycle(surface, accountId, input);
+    }
+    if (actionId === 'list-directory') {
+      const scope = readDirectoryScope(input?.scope);
+      return this.deps.channelPlugins.queryDirectory(surface, {
+        query: typeof input?.query === 'string' ? input.query : undefined,
+        ...(scope ? { scope } : {}),
+        groupId: typeof input?.groupId === 'string' ? input.groupId : undefined,
+        limit: typeof input?.limit === 'number' ? input.limit : undefined,
+      });
+    }
+    if (actionId === 'list-capabilities') {
+      return this.listCapabilities(surface);
+    }
+    if (actionId === 'account-action') {
+      const action = readLifecycleAction(input?.action ?? input?.accountAction);
+      if (!action) {
+        return {
+          surface,
+          ok: false,
+          error: 'account-action requires a valid lifecycle action.',
+        };
+      }
+      return this.runAccountAction(
+        surface,
+        action,
+        typeof input?.accountId === 'string' ? input.accountId : undefined,
+        input,
+      );
+    }
+    if (actionId === 'resolve-target') {
+      const targetInput = typeof input?.target === 'string'
+        ? input.target
+        : typeof input?.input === 'string'
+          ? input.input
+          : typeof input?.query === 'string'
+            ? input.query
+            : '';
+      if (targetInput.trim().length === 0) {
+        return {
+          surface,
+          ok: false,
+          error: 'resolve-target requires "target" or "input".',
+        };
+      }
+      const preferredKind = readConversationKind(input?.preferredKind);
+      return this.resolveTarget(surface, {
+        input: targetInput,
+        ...(typeof input?.accountId === 'string' ? { accountId: input.accountId } : {}),
+        ...(preferredKind ? { preferredKind } : {}),
+        ...(typeof input?.threadId === 'string' ? { threadId: input.threadId } : {}),
+        ...(typeof input?.createIfMissing === 'boolean' ? { createIfMissing: input.createIfMissing } : {}),
+        ...(typeof input?.live === 'boolean' ? { live: input.live } : {}),
+      });
+    }
+    if (actionId === 'authorize-actor-action') {
+      const targetInput = typeof input?.target === 'string' ? input.target : undefined;
+      const target = targetInput
+        ? await this.resolveTarget(surface, {
+            input: targetInput,
+            ...(typeof input?.accountId === 'string' ? { accountId: input.accountId } : {}),
+            createIfMissing: true,
+          })
+        : undefined;
+      return this.authorizeActorAction(surface, {
+        actionId: typeof input?.actionId === 'string' ? input.actionId : 'unknown',
+        ...(typeof input?.actorId === 'string' ? { actorId: input.actorId } : {}),
+        ...(typeof input?.accountId === 'string' ? { accountId: input.accountId } : {}),
+        ...(target ? { target } : {}),
+        metadata: {},
+      });
+    }
+    if (actionId === 'resolve-allowlist') {
+      return this.resolveAllowlist(surface, {
+        ...(Array.isArray(input?.add) ? { add: input.add.filter((entry): entry is string => typeof entry === 'string') } : {}),
+        ...(Array.isArray(input?.remove) ? { remove: input.remove.filter((entry): entry is string => typeof entry === 'string') } : {}),
+        ...(input?.kind === 'user' || input?.kind === 'channel' || input?.kind === 'group' ? { kind: input.kind } : {}),
+      });
+    }
+    if (actionId === 'edit-allowlist') {
+      return this.editAllowlist(surface, {
+        ...(Array.isArray(input?.add) ? { add: input.add.filter((entry): entry is string => typeof entry === 'string') } : {}),
+        ...(Array.isArray(input?.remove) ? { remove: input.remove.filter((entry): entry is string => typeof entry === 'string') } : {}),
+        ...(typeof input?.groupId === 'string' ? { groupId: input.groupId } : {}),
+        ...(typeof input?.channelId === 'string' ? { channelId: input.channelId } : {}),
+        ...(typeof input?.workspaceId === 'string' ? { workspaceId: input.workspaceId } : {}),
+        ...(input?.kind === 'user' || input?.kind === 'channel' || input?.kind === 'group' ? { kind: input.kind } : {}),
+        ...(typeof input?.metadata === 'object' && input.metadata !== null ? { metadata: input.metadata as Record<string, unknown> } : {}),
+      });
+    }
+    if (actionId === 'provider-api') {
+      return this.runProviderApi(surface, input);
+    }
+    return null;
+  }
+
+  private buildContractHooks(surface: ChannelSurface): Pick<
+    ChannelPlugin,
+    | 'setupVersion'
+    | 'renderPolicy'
+    | 'getSetupSchema'
+    | 'doctor'
+    | 'listRepairActions'
+    | 'getLifecycleState'
+    | 'migrateLifecycle'
+    | 'resolveAllowlist'
+    | 'editAllowlist'
+  > {
+    return buildBuiltinContractHooks(this.contractContext(), surface);
+  }
+
+  private getSetupSchema(surface: ChannelSurface) {
+    return getBuiltinSetupSchema(surface);
+  }
+
+  private async listRepairActions(surface: ChannelSurface, accountId?: string) {
+    return listBuiltinRepairActions(this.contractContext(), surface, accountId);
+  }
+
+  private async getDoctorReport(surface: ChannelSurface, accountId?: string) {
+    return getBuiltinDoctorReport(this.contractContext(), surface, accountId);
+  }
+
+  private async getLifecycleState(surface: ChannelSurface, accountId?: string) {
+    return getBuiltinLifecycleState(this.contractContext(), surface, accountId);
+  }
+
+  private async migrateLifecycle(
+    surface: ChannelSurface,
+    accountId?: string,
+    input?: Record<string, unknown>,
+  ) {
+    return migrateBuiltinLifecycle(this.contractContext(), surface, accountId, input);
+  }
+
+  private async resolveAllowlist(surface: ChannelSurface, input: Parameters<typeof resolveBuiltinAllowlist>[2]) {
+    return resolveBuiltinAllowlist(this.contractContext(), surface, input);
+  }
+
+  private async editAllowlist(surface: ChannelSurface, input: Parameters<typeof editBuiltinAllowlist>[2]) {
+    return editBuiltinAllowlist(this.contractContext(), surface, input);
+  }
+
+  private buildProductHooks(surface: ChannelSurface): Pick<
+    ChannelPlugin,
+    | 'runAccountAction'
+    | 'authorizeActorAction'
+    | 'parseExplicitTarget'
+    | 'inferTargetConversationKind'
+    | 'resolveTarget'
+    | 'resolveSessionTarget'
+    | 'resolveParentConversationCandidates'
+    | 'renderEvent'
+    | 'listAgentTools'
+  > {
+    return {
+      runAccountAction: (action, accountId, input) => this.runAccountAction(surface, action, accountId, input),
+      authorizeActorAction: (request) => this.authorizeActorAction(surface, request),
+      parseExplicitTarget: (input, options) => this.parseExplicitTarget(surface, input, options),
+      inferTargetConversationKind: (input, options) => this.inferTargetConversationKind(input, options),
+      resolveTarget: (options) => this.resolveTarget(surface, options),
+      resolveSessionTarget: (target) => this.resolveSessionTarget(target),
+      resolveParentConversationCandidates: (options) => this.resolveParentConversationCandidates(surface, options),
+      renderEvent: (request) => this.renderChannelEvent(surface, request),
+      listAgentTools: () => this.listAgentTools(surface),
+    };
+  }
+
+  private async renderChannelEvent(surface: ChannelSurface, request: ChannelRenderRequest): Promise<ChannelRenderResult> {
+    return renderBuiltinChannelEvent({
+      deps: this.deps,
+      listTools: (currentSurface) => this.listTools(currentSurface),
+      runTool: (currentSurface, toolId, input) => this.runTool(currentSurface, toolId, input),
+    }, surface, request);
+  }
+
+  private async notifyApprovalViaRouter(
+    surface: ChannelSurface,
+    approval: Parameters<typeof notifyBuiltinApprovalViaRouter>[2],
+    binding: Parameters<typeof notifyBuiltinApprovalViaRouter>[3],
+  ): Promise<void> {
+    await notifyBuiltinApprovalViaRouter({
+      deps: this.deps,
+      listTools: (currentSurface) => this.listTools(currentSurface),
+      runTool: (currentSurface, toolId, input) => this.runTool(currentSurface, toolId, input),
+    }, surface, approval, binding);
+  }
+
+  private listAgentTools(surface: ChannelSurface): readonly Tool[] {
+    return listBuiltinAgentTools({
+      deps: this.deps,
+      listTools: (currentSurface) => this.listTools(currentSurface),
+      runTool: (currentSurface, toolId, input) => this.runTool(currentSurface, toolId, input),
+    }, surface);
+  }
+
+  private async runAccountAction(
+    surface: ChannelSurface,
+    action: ChannelAccountLifecycleAction,
+    accountId?: string,
+    input?: Record<string, unknown>,
+  ): Promise<ChannelAccountLifecycleResult> {
+    return runBuiltinAccountAction({
+      deps: this.deps,
+      buildAccount: (currentSurface) => this.buildAccount(currentSurface),
+      resolveAccount: (currentSurface, currentAccountId) => this.resolveAccount(currentSurface, currentAccountId),
+    }, surface, action, accountId, input);
+  }
+
+  private async authorizeActorAction(
+    surface: ChannelSurface,
+    request: ChannelActorAuthorizationRequest,
+  ): Promise<ChannelActorAuthorizationResult> {
+    return authorizeBuiltinActorAction({
+      deps: this.deps,
+      buildAccount: (currentSurface) => this.buildAccount(currentSurface),
+      resolveAccount: (currentSurface, currentAccountId) => this.resolveAccount(currentSurface, currentAccountId),
+    }, surface, request);
+  }
+
+  private async runProviderApi(surface: ChannelSurface, input?: Record<string, unknown>): Promise<unknown> {
+    return runBuiltinProviderApi({
+      deps: this.deps,
+      buildAccount: (currentSurface) => this.buildAccount(currentSurface),
+      resolveAccount: (currentSurface, currentAccountId) => this.resolveAccount(currentSurface, currentAccountId),
+    }, surface, input);
+  }
+
+  private parseExplicitTarget(
+    surface: ChannelSurface,
+    input: string,
+    options?: ChannelTargetResolveOptions,
+  ): ChannelResolvedTarget | null {
+    return parseBuiltinExplicitTarget(surface, input, options);
+  }
+
+  private inferTargetConversationKind(
+    input: string,
+    options?: ChannelTargetResolveOptions,
+  ): ChannelConversationKind {
+    return inferBuiltinTargetConversationKind(input, options);
+  }
+
+  private async resolveTarget(
+    surface: ChannelSurface,
+    options: ChannelTargetResolveOptions,
+  ): Promise<ChannelResolvedTarget | null> {
+    return resolveBuiltinTarget({ deps: this.deps }, surface, options);
+  }
+
+  private async resolveParentConversationCandidates(
+    surface: ChannelSurface,
+    options: ChannelTargetResolveOptions,
+  ): Promise<readonly ChannelResolvedTarget[]> {
+    return resolveBuiltinParentConversationCandidates({ deps: this.deps }, surface, options);
+  }
+
+  private resolveSessionTarget(target: ChannelResolvedTarget): string {
+    return resolveBuiltinSessionTarget(target);
+  }
+
+  private providerRuntimeStatus(surface: ProviderRuntimeSurface): unknown {
+    return providerRuntimeStatusForSurface(this.deps, surface);
+  }
+
+  private async lookupDirectory(
+    surface: ManagedSurface,
+    query: string,
+    options?: ChannelDirectoryQueryOptions,
+  ): Promise<ChannelDirectoryEntry[]> {
+    return lookupBuiltinDirectory({ deps: this.deps }, surface, query, options);
+  }
+
+  private async lookupRouteDirectory(
+    surface: ManagedSurface,
+    query: string,
+    options?: ChannelDirectoryQueryOptions,
+  ): Promise<ChannelDirectoryEntry[]> {
+    return lookupBuiltinDirectory({ deps: this.deps }, surface, query, { ...options, live: false });
+  }
+}

package/src/channels/delivery/shared.ts

@@ -0,0 +1,199 @@
+import { ArtifactStore, type ArtifactAttachment, type ArtifactReference } from '@pellux/goodvibes-sdk/platform/artifacts/index';
+import { ConfigManager } from '../../config/manager.ts';
+import { ServiceRegistry } from '../../config/service-registry.ts';
+import type {
+  ChannelDeliveryRequest,
+  ChannelDeliveryResult,
+  ChannelDeliverySurfaceKind,
+  ChannelDeliveryTarget,
+} from './types.ts';
+
+export function resolveChannelDeliverySurfaceKind(
+  target: ChannelDeliveryTarget,
+): ChannelDeliverySurfaceKind | undefined {
+  return target.surfaceKind ?? (target.kind === 'webhook' ? 'webhook' : undefined);
+}
+
+export function titleFromBody(body: string): string {
+  const firstLine = body.split('\n').find((line) => line.trim().length > 0) ?? 'goodvibes automation';
+  return firstLine.slice(0, 80);
+}
+
+export function success(responseId?: string): ChannelDeliveryResult {
+  return responseId === undefined ? {} : { responseId };
+}
+
+function buildArtifactContentPath(artifactId: string): string {
+  return `/api/artifacts/${encodeURIComponent(artifactId)}/content`;
+}
+
+function buildArtifactContentUrl(configManager: ConfigManager, artifactId: string): string | undefined {
+  const baseUrl = String(configManager.get('controlPlane.baseUrl') ?? configManager.get('web.publicBaseUrl') ?? '').trim();
+  if (!baseUrl) return undefined;
+  return new URL(buildArtifactContentPath(artifactId), baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+
+export async function resolveAttachments(
+  request: ChannelDeliveryRequest,
+  artifactStore: ArtifactStore,
+  configManager: ConfigManager,
+  inlineLimitBytes?: number,
+): Promise<ArtifactAttachment[]> {
+  const references = request.attachments ?? [];
+  const attachments: ArtifactAttachment[] = [];
+  for (const reference of references) {
+    attachments.push(await artifactStore.toAttachment(reference, {
+      contentUrl: buildArtifactContentUrl(configManager, reference.artifactId),
+      ...(typeof inlineLimitBytes === 'number' ? { includeBase64IfSmallerThan: inlineLimitBytes } : {}),
+    }));
+  }
+  return attachments;
+}
+
+export function appendAttachmentSummary(body: string, attachments: readonly ArtifactAttachment[]): string {
+  if (attachments.length === 0) return body;
+  const lines = attachments.map((attachment) => {
+    const target = attachment.contentUrl ?? attachment.contentPath;
+    const name = attachment.filename ?? attachment.label ?? attachment.artifactId;
+    return `- ${name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes): ${target}`;
+  });
+  return `${body.trimEnd()}\n\nAttachments:\n${lines.join('\n')}`;
+}
+
+export function trimForSurface(body: string, maxChars: number): string {
+  const normalized = body.replace(/\r\n/g, '\n').trim();
+  if (normalized.length <= maxChars) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+
+export function firstNonEmpty(...values: Array<string | undefined | null>): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim();
+  }
+  return undefined;
+}
+
+export function normalizeBaseUrl(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+const msTeamsTokenCache = new Map<string, { readonly token: string; readonly expiresAt: number }>();
+
+export async function resolveMSTeamsAccessToken(
+  configManager: ConfigManager,
+  serviceRegistry: ServiceRegistry,
+): Promise<string> {
+  const appId = firstNonEmpty(
+    String(configManager.get('surfaces.msteams.appId') ?? ''),
+    process.env.MSTEAMS_APP_ID,
+  );
+  const appPassword = firstNonEmpty(
+    await serviceRegistry.resolveSecret('msteams', 'password'),
+    String(configManager.get('surfaces.msteams.appPassword') ?? ''),
+    process.env.MSTEAMS_APP_PASSWORD,
+  );
+  const tenantId = firstNonEmpty(
+    String(configManager.get('surfaces.msteams.tenantId') ?? ''),
+    process.env.MSTEAMS_TENANT_ID,
+    'botframework.com',
+  )!;
+  if (!appId) throw new Error('Missing Microsoft Teams app id');
+  if (!appPassword) throw new Error('Missing Microsoft Teams app password');
+  const cacheKey = `${tenantId}:${appId}`;
+  const cached = msTeamsTokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now() + 60_000) {
+    return cached.token;
+  }
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: appId,
+    client_secret: appPassword,
+    scope: 'https://api.botframework.com/.default',
+  });
+  const response = await fetch(`https://login.microsoftonline.com/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  const payload = await requireOkResponse('Microsoft Teams token request failed', response);
+  const record = payload && typeof payload === 'object' ? payload as Record<string, unknown> : null;
+  const token = typeof record?.access_token === 'string' ? record.access_token.trim() : '';
+  const expiresIn = typeof record?.expires_in === 'number'
+    ? record.expires_in
+    : typeof record?.expires_in === 'string'
+      ? Number(record.expires_in)
+      : 300;
+  if (!token) throw new Error('Microsoft Teams token request did not return an access token');
+  msTeamsTokenCache.set(cacheKey, {
+    token,
+    expiresAt: Date.now() + Math.max(60, Number.isFinite(expiresIn) ? expiresIn : 300) * 1_000,
+  });
+  return token;
+}
+
+export function extractResponseId(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== 'object') return undefined;
+  const record = payload as Record<string, unknown>;
+  const direct = record.id;
+  if (typeof direct === 'string' && direct.trim().length > 0) return direct.trim();
+  if (typeof direct === 'number' && Number.isFinite(direct)) return String(direct);
+  const name = record.name;
+  if (typeof name === 'string' && name.trim().length > 0) return name.trim();
+  const messageId = record.message_id;
+  if (typeof messageId === 'number' && Number.isFinite(messageId)) return String(messageId);
+  if (typeof messageId === 'string' && messageId.trim().length > 0) return messageId.trim();
+  const result = record.result;
+  if (result && typeof result === 'object') return extractResponseId(result);
+  return undefined;
+}
+
+async function readResponsePayload(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.includes('application/json')) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const text = await response.text();
+    return text.trim().length > 0 ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function requireOkResponse(label: string, response: Response): Promise<unknown> {
+  const payload = await readResponsePayload(response);
+  if (!response.ok) {
+    const detail = typeof payload === 'string'
+      ? payload
+      : payload && typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : '';
+    throw new Error(`${label} HTTP ${response.status}${detail ? `: ${detail}` : ''}`);
+  }
+  return payload;
+}
+
+export async function postBridgePayload(
+  bridgeUrl: string,
+  payload: Record<string, unknown>,
+  options: {
+    readonly label: string;
+    readonly token?: string;
+  },
+): Promise<string | undefined> {
+  const response = await fetch(bridgeUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(options.token ? { Authorization: `Bearer ${options.token}` } : {}),
+      'X-GoodVibes-Channel': String(payload.surface ?? 'bridge'),
+    },
+    body: JSON.stringify(payload),
+  });
+  const result = await requireOkResponse(options.label, response);
+  return extractResponseId(result) ?? bridgeUrl;
+}