@agent-native/core 0.92.11 → 0.93.0

package/corpus/core/src/integrations/slack-oauth.ts

@@ -0,0 +1,343 @@
+/** Slack OAuth v2 helpers for managed Agent Native messaging installs. */
+
+import type { SecretScope } from "../secrets/register.js";
+import type {
+  IntegrationInstallationHealth,
+  UpsertIntegrationInstallationInput,
+} from "./installations-store.js";
+
+export const SLACK_AUTHORIZE_URL = "https://slack.com/oauth/v2/authorize";
+export const SLACK_TOKEN_URL = "https://slack.com/api/oauth.v2.access";
+export const SLACK_AUTH_TEST_URL = "https://slack.com/api/auth.test";
+
+/** Scopes needed for contextual, file-aware Agent Native conversations. */
+export const SLACK_AGENT_BOT_SCOPES = [
+  "assistant:write",
+  "app_mentions:read",
+  "channels:read",
+  "channels:history",
+  "chat:write",
+  "files:read",
+  "groups:history",
+  "groups:read",
+  "im:history",
+  "im:read",
+  "mpim:history",
+  "mpim:read",
+  "pins:read",
+  "reactions:read",
+  "users:read",
+  "users:read.email",
+] as const;
+
+export interface SlackOAuthAccessResponse {
+  ok?: boolean;
+  error?: string;
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+  scope?: string;
+  bot_user_id?: string;
+  app_id?: string;
+  is_enterprise_install?: boolean;
+  authed_user?: { id?: string };
+  team?: { id?: string; name?: string } | null;
+  enterprise?: { id?: string; name?: string } | null;
+}
+
+interface SlackApiResponse {
+  ok?: boolean;
+  error?: string;
+  team_id?: string;
+  team?: string;
+  enterprise_id?: string;
+  enterprise?: string;
+  user_id?: string;
+  bot_id?: string;
+  url?: string;
+}
+
+export interface SlackAuthHealth {
+  ok: boolean;
+  health: IntegrationInstallationHealth;
+  error: string | null;
+  checkedAt: number;
+  teamId: string | null;
+  enterpriseId: string | null;
+  botId: string | null;
+  userId: string | null;
+}
+
+export interface SlackInstallSession {
+  email?: string | null;
+  orgId?: string | null;
+  orgRole?: string | null;
+}
+
+export interface SlackInstallAccess {
+  ownerEmail: string;
+  orgId: string | null;
+  secretScope: SecretScope;
+  secretScopeId: string;
+}
+
+function safeSlackError(value: unknown, fallback: string): string {
+  return typeof value === "string" && /^[a-z0-9_.-]{1,100}$/i.test(value)
+    ? value
+    : fallback;
+}
+
+export function buildSlackAuthorizeUrl(options: {
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  scopes?: readonly string[];
+  userScopes?: readonly string[];
+  teamId?: string;
+}): string {
+  const params = new URLSearchParams({
+    client_id: options.clientId,
+    redirect_uri: options.redirectUri,
+    response_type: "code",
+    scope: (options.scopes ?? SLACK_AGENT_BOT_SCOPES).join(","),
+    state: options.state,
+  });
+  if (options.userScopes?.length) {
+    params.set("user_scope", options.userScopes.join(","));
+  }
+  if (options.teamId) params.set("team", options.teamId);
+  return `${SLACK_AUTHORIZE_URL}?${params.toString()}`;
+}
+
+/** Exchange an OAuth code using Slack's preferred HTTP Basic authentication. */
+export async function exchangeSlackOAuthCode(options: {
+  code: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SlackOAuthAccessResponse> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authorization = Buffer.from(
+    `${options.clientId}:${options.clientSecret}`,
+    "utf8",
+  ).toString("base64");
+  const response = await fetchImpl(SLACK_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${authorization}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      code: options.code,
+      redirect_uri: options.redirectUri,
+    }),
+  });
+  const data = (await response
+    .json()
+    .catch(() => null)) as SlackOAuthAccessResponse | null;
+  if (!response.ok || !data?.ok) {
+    throw new Error(
+      safeSlackError(
+        data?.error,
+        `Slack OAuth exchange failed (${response.status})`,
+      ),
+    );
+  }
+  return data;
+}
+
+/**
+ * Rotate an expiring Slack token. Slack refresh tokens are one-time-use, so
+ * callers must atomically persist the returned access/refresh pair together.
+ */
+export async function refreshSlackOAuthToken(options: {
+  refreshToken: string;
+  clientId: string;
+  clientSecret: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SlackOAuthAccessResponse> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authorization = Buffer.from(
+    `${options.clientId}:${options.clientSecret}`,
+    "utf8",
+  ).toString("base64");
+  const response = await fetchImpl(SLACK_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${authorization}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+    }),
+  });
+  const data = (await response
+    .json()
+    .catch(() => null)) as SlackOAuthAccessResponse | null;
+  if (!response.ok || !data?.ok) {
+    throw new Error(
+      safeSlackError(
+        data?.error,
+        `Slack OAuth token refresh failed (${response.status})`,
+      ),
+    );
+  }
+  if (!data.access_token || !data.refresh_token) {
+    throw new Error("Slack OAuth token refresh returned an incomplete bundle");
+  }
+  return data;
+}
+
+/** Validate a bot token without ever including it in an error or result. */
+export async function testSlackAuth(
+  accessToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<SlackAuthHealth> {
+  const checkedAt = Date.now();
+  try {
+    const response = await fetchImpl(SLACK_AUTH_TEST_URL, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    const data = (await response
+      .json()
+      .catch(() => null)) as SlackApiResponse | null;
+    if (!response.ok || !data?.ok) {
+      const error = safeSlackError(
+        data?.error,
+        `Slack auth test failed (${response.status})`,
+      );
+      return {
+        ok: false,
+        health:
+          error === "invalid_auth" || error === "token_revoked"
+            ? "revoked"
+            : "degraded",
+        error,
+        checkedAt,
+        teamId: null,
+        enterpriseId: null,
+        botId: null,
+        userId: null,
+      };
+    }
+    return {
+      ok: true,
+      health: "healthy",
+      error: null,
+      checkedAt,
+      teamId: data.team_id ?? null,
+      enterpriseId: data.enterprise_id ?? null,
+      botId: data.bot_id ?? null,
+      userId: data.user_id ?? null,
+    };
+  } catch {
+    return {
+      ok: false,
+      health: "degraded",
+      error: "Slack auth test request failed",
+      checkedAt,
+      teamId: null,
+      enterpriseId: null,
+      botId: null,
+      userId: null,
+    };
+  }
+}
+
+/** Stable team/app key used by webhook payloads and the installation store. */
+export function slackInstallationKey(input: {
+  teamId?: string | null;
+  enterpriseId?: string | null;
+  apiAppId?: string | null;
+  isEnterpriseInstall?: boolean;
+}): string {
+  const workspaceId = input.isEnterpriseInstall
+    ? input.enterpriseId
+    : (input.teamId ?? input.enterpriseId);
+  if (!workspaceId) {
+    throw new Error("Slack OAuth did not return a team or enterprise id");
+  }
+  return `${input.isEnterpriseInstall ? "enterprise" : "team"}:${workspaceId}:app:${input.apiAppId || "default"}`;
+}
+
+/**
+ * Convert a successful Slack response to the generic managed-install input.
+ * The returned token bundle is server-only and must be passed directly to the
+ * encrypted installation store, never to a route response.
+ */
+export function slackOAuthResponseToInstallation(
+  response: SlackOAuthAccessResponse,
+  access: SlackInstallAccess,
+  now = Date.now(),
+): UpsertIntegrationInstallationInput {
+  if (!response.ok || !response.access_token) {
+    throw new Error("Slack OAuth response did not include a bot access token");
+  }
+  const installationKey = slackInstallationKey({
+    teamId: response.team?.id,
+    enterpriseId: response.enterprise?.id,
+    apiAppId: response.app_id,
+    isEnterpriseInstall: response.is_enterprise_install,
+  });
+  const expiresAt =
+    typeof response.expires_in === "number" && response.expires_in > 0
+      ? now + response.expires_in * 1000
+      : undefined;
+  return {
+    platform: "slack",
+    installationKey,
+    teamId: response.team?.id ?? null,
+    teamName: response.team?.name ?? null,
+    enterpriseId: response.enterprise?.id ?? null,
+    enterpriseName: response.enterprise?.name ?? null,
+    isEnterpriseInstall: response.is_enterprise_install === true,
+    apiAppId: response.app_id ?? null,
+    botUserId: response.bot_user_id ?? null,
+    scopes: response.scope?.split(",").map((scope) => scope.trim()) ?? [],
+    installedByExternalUserId: response.authed_user?.id ?? null,
+    ownerEmail: access.ownerEmail,
+    orgId: access.orgId,
+    secretScope: access.secretScope,
+    secretScopeId: access.secretScopeId,
+    tokenBundle: {
+      accessToken: response.access_token,
+      refreshToken: response.refresh_token,
+      tokenType: response.token_type,
+      expiresAt,
+    },
+    tokenExpiresAt: expiresAt ?? null,
+  };
+}
+
+/**
+ * Pure session/role gate for OAuth install routes. The caller must supply a
+ * server-verified session; org membership must be the active org context.
+ */
+export function assertSlackInstallAccess(
+  session: SlackInstallSession | null | undefined,
+): SlackInstallAccess {
+  const ownerEmail = session?.email?.trim().toLowerCase();
+  if (!ownerEmail) throw new Error("Sign in before connecting Slack.");
+  const orgId = session?.orgId?.trim() || null;
+  if (!orgId) {
+    return {
+      ownerEmail,
+      orgId: null,
+      secretScope: "user",
+      secretScopeId: ownerEmail,
+    };
+  }
+  if (session?.orgRole !== "owner" && session?.orgRole !== "admin") {
+    throw new Error("Only organization owners and admins can connect Slack.");
+  }
+  return {
+    ownerEmail,
+    orgId,
+    secretScope: "org",
+    secretScopeId: orgId,
+  };
+}

package/corpus/core/src/integrations/types.ts

@@ -1,7 +1,41 @@
 import type { H3Event } from "h3";
 
+import type { AgentChatEvent } from "../agent/types.js";
 import type { EnvKeyConfig } from "../server/create-server.js";
 
+export type IntegrationConversationType =
+  | "channel"
+  | "private_channel"
+  | "dm"
+  | "group_dm"
+  | "unknown";
+
+export type IntegrationTriggerKind = "mention" | "dm" | "thread_reply";
+
+export interface IntegrationActorTrust {
+  memberType: "owner" | "admin" | "member" | "guest" | "external" | "unknown";
+  verified: boolean;
+}
+
+export interface IntegrationContextMessage {
+  senderId?: string;
+  senderName?: string;
+  text: string;
+  timestamp: number;
+  sourceUrl?: string;
+  reactions?: Array<{ name: string; count: number }>;
+  files?: IntegrationFileReference[];
+}
+
+export interface IntegrationFileReference {
+  id: string;
+  name?: string;
+  mimetype?: string;
+  size?: number;
+  permalink?: string;
+  downloadUrl?: string;
+}
+
 /**
  * Normalized incoming message from any messaging platform.
  */
@@ -18,6 +52,22 @@ export interface IncomingMessage {
   senderEmail?: string;
   /** Platform-specific sender ID */
   senderId?: string;
+  /** How this message intentionally invoked an agent. */
+  triggerKind?: IntegrationTriggerKind;
+  /** Normalized provider conversation type for policy evaluation. */
+  conversationType?: IntegrationConversationType;
+  /** Provider tenant/workspace identifier. */
+  tenantId?: string;
+  /** Authorized integration scope resolved before execution. */
+  integrationScopeId?: string;
+  /** Normalized actor trust; unknown/unverified callers fail closed. */
+  actorTrust?: IntegrationActorTrust;
+  /** Bounded provider-native conversation context hydrated at run time. */
+  contextMessages?: IntegrationContextMessage[];
+  /** Provider file references only. Raw file bodies never belong here. */
+  files?: IntegrationFileReference[];
+  /** Server-verified approval grants carried by an interaction continuation. */
+  approvedToolCalls?: string[];
   /**
    * Whether the platform cryptographically authenticated that the message
    * genuinely came from the claimed sender (e.g. inbound email that passed
@@ -31,6 +81,31 @@ export interface IncomingMessage {
   senderVerified?: boolean;
   /** Raw platform-specific context needed for routing responses */
   platformContext: Record<string, unknown>;
+  /**
+   * Short-lived delivery context needed only while the queued task is active.
+   * Secrets such as Discord interaction tokens belong here, never in
+   * `platformContext`, thread mappings, logs, or agent-visible context.
+   */
+  responseContext?: Record<string, unknown>;
+  /** Provider-native thread/topic reference, when one exists. */
+  threadRef?: string;
+  /**
+   * Canonical provider URL for the originating message thread, when the
+   * provider can resolve one. This is safe agent-visible provenance (not a
+   * credential) and should be preserved across A2A delegation so created
+   * artifacts can link back to their request source.
+   */
+  sourceUrl?: string;
+  /**
+   * Trusted app-side routing guidance added after provider parsing. Adapters
+   * should not copy this from user-controlled webhook payload fields.
+   */
+  routingHint?: {
+    targetAgent?: string;
+    instruction: string;
+  };
+  /** Provider-native message/activity reference for contextual replies. */
+  replyRef?: string;
   /** Message timestamp (epoch ms) */
   timestamp: number;
 }
@@ -57,6 +132,10 @@ export interface OutboundTarget {
   threadRef?: string | null;
   /** Optional fallback display label */
   label?: string;
+  /** Provider tenant/workspace used to select an installation credential. */
+  tenantId?: string;
+  /** Managed installation id when the caller already resolved it. */
+  installationId?: string;
 }
 
 /**
@@ -82,6 +161,51 @@ export interface IntegrationStatus {
   requiredEnvKeys?: import("../server/create-server.js").EnvKeyConfig[];
 }
 
+export interface PlatformAdapterCapabilities {
+  /** The adapter can deliver a response to the current inbound event. */
+  replyText: boolean;
+  /** The adapter can send without an active inbound event. */
+  proactiveMessages: boolean;
+  /** The adapter preserves a provider-native thread or topic reference. */
+  nativeThreads: boolean;
+  /** The adapter can quote/reply to a specific inbound message. */
+  contextualReplies: boolean;
+  /** The provider requires an immediate deferred webhook acknowledgement. */
+  deferredWebhookResponse: boolean;
+  /** The adapter only receives explicit interactions, not ordinary messages. */
+  interactionOnly?: boolean;
+  /** The adapter can hydrate bounded native thread/file/reaction context. */
+  nativeContextHydration?: boolean;
+  /** The adapter can surface live agent progress in the provider UI. */
+  liveRunProgress?: boolean;
+}
+
+export interface PlatformRunProgress {
+  /** Receive normalized agent events. Implementations should throttle writes. */
+  onEvent(event: AgentChatEvent): Promise<void> | void;
+  /** Finalize the provider-native progress surface with the answer. */
+  complete(message: OutgoingMessage): Promise<void>;
+  /** Mark the provider-native surface failed and leave a retryable explanation. */
+  fail?(message: string): Promise<void>;
+}
+
+export interface ImmediateWebhookResponse {
+  status: number;
+  body: unknown;
+}
+
+export class UnsupportedPlatformCapabilityError extends Error {
+  readonly code = "UNSUPPORTED_PLATFORM_CAPABILITY";
+
+  constructor(
+    readonly platform: string,
+    readonly capability: keyof PlatformAdapterCapabilities,
+  ) {
+    super(`Platform ${platform} does not support ${capability}`);
+    this.name = "UnsupportedPlatformCapabilityError";
+  }
+}
+
 /**
  * Platform adapter interface — implement this for each messaging platform.
  *
@@ -96,6 +220,8 @@ export interface PlatformAdapter {
   readonly platform: string;
   /** Human-readable label */
   readonly label: string;
+  /** Explicit runtime behavior. Missing fields are treated as unsupported. */
+  readonly capabilities?: Partial<PlatformAdapterCapabilities>;
 
   /** Env keys this adapter needs (tokens, secrets, etc.) */
   getRequiredEnvKeys(): EnvKeyConfig[];
@@ -122,6 +248,29 @@ export interface PlatformAdapter {
    */
   parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null>;
 
+  /**
+   * Hydrate bounded provider-native context after durable enqueue, outside the
+   * provider acknowledgement budget. Implementations must return references,
+   * metadata, and text only — never persist file bodies or credentials.
+   */
+  hydrateIncomingMessage?(incoming: IncomingMessage): Promise<IncomingMessage>;
+
+  /**
+   * Provider-specific response returned only after a message is verified and
+   * durably enqueued. Discord uses this to return a type-5 deferred response
+   * within its three-second interaction deadline.
+   */
+  getImmediateWebhookResponse?(
+    incoming: IncomingMessage,
+  ): ImmediateWebhookResponse | null;
+
+  /**
+   * Return pre-canonical thread ids used by older adapter versions. The
+   * integration handler checks these only when the canonical mapping is
+   * missing, then aliases a match to the canonical id without forking history.
+   */
+  getLegacyExternalThreadIds?(incoming: IncomingMessage): string[];
+
   /**
    * Send the agent's response back to the messaging platform.
    *
@@ -150,6 +299,11 @@ export interface PlatformAdapter {
     incoming: IncomingMessage,
   ): Promise<{ placeholderRef: string } | null>;
 
+  /** Start a provider-native progress/streaming surface for an agent run. */
+  startRunProgress?(
+    incoming: IncomingMessage,
+  ): Promise<PlatformRunProgress | null>;
+
   /**
    * Send a proactive outbound message to a platform destination. Adapters that
    * only support direct replies can omit this.
@@ -177,6 +331,15 @@ export interface PlatformAdapter {
   getStatus(baseUrl?: string): Promise<IntegrationStatus>;
 }
 
+export function assertPlatformCapability(
+  adapter: PlatformAdapter,
+  capability: keyof PlatformAdapterCapabilities,
+): void {
+  if (adapter.capabilities?.[capability] !== true) {
+    throw new UnsupportedPlatformCapabilityError(adapter.platform, capability);
+  }
+}
+
 /**
  * Options for the integrations plugin.
  */
@@ -206,6 +369,14 @@ export interface IntegrationsPluginOptions {
    * created chat thread for an incoming platform message.
    */
   resolveOwner?: (incoming: IncomingMessage) => string | Promise<string>;
+  /**
+   * Resolve the durable execution principal for an inbound provider message.
+   * Shared channels should use a service principal; DMs may use a verified
+   * linked user. When present this supersedes `resolveOwner`.
+   */
+  resolveExecutionContext?: (
+    incoming: IncomingMessage,
+  ) => IntegrationExecutionContext | Promise<IntegrationExecutionContext>;
   /**
    * Optional preprocessor for inbound platform messages. Can intercept special
    * commands (such as `/link`) before the agent loop runs.
@@ -221,3 +392,11 @@ export interface IntegrationsPluginOptions {
     | { handled: false }
   >;
 }
+
+export interface IntegrationExecutionContext {
+  ownerEmail: string;
+  orgId: string | null;
+  principalType: "user" | "service";
+  installationId?: string;
+  scopeId?: string;
+}