@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/slack-provisioning-client.ts

@@ -0,0 +1,411 @@
+/**
+ * agent/src/slack-provisioning-client.ts
+ * SlackProvisioningClient interface and HttpSlackProvisioningClient implementation.
+ *
+ * Used during the one-time agent provisioning flow:
+ *   1. apps.manifest.create — creates the Slack app from a manifest
+ *
+ * apps.manifest.create returns credentials (client_id, client_secret, signing_secret)
+ * directly in the response — no separate oauth.v2.access exchange needed.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface AppManifestDisplayInfo {
+  name: string;
+  description?: string;
+  long_description?: string;
+  background_color?: string;
+}
+
+interface AppManifestBotUser {
+  display_name: string;
+  always_online?: boolean;
+}
+
+interface AppManifestOAuthConfig {
+  scopes: {
+    bot?: string[];
+    user?: string[];
+  };
+  redirect_urls?: string[];
+}
+
+interface AppManifestSettings {
+  event_subscriptions?: {
+    bot_events?: string[];
+  };
+  interactivity?: {
+    is_enabled: boolean;
+    request_url?: string;
+  };
+  org_deploy_enabled?: boolean;
+  socket_mode_enabled?: boolean;
+}
+
+export interface AppManifest {
+  display_information: AppManifestDisplayInfo;
+  features?: {
+    app_home?: {
+      home_tab_enabled?: boolean;
+      messages_tab_enabled?: boolean;
+      messages_tab_read_only_enabled?: boolean;
+    };
+    bot_user?: AppManifestBotUser;
+    agent_view?: {
+      agent_description?: string;
+      suggested_prompts?: { title: string; message: string }[];
+    };
+  };
+  oauth_config?: AppManifestOAuthConfig;
+  settings?: AppManifestSettings;
+}
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface SlackProvisioningClient {
+  /**
+   * Call apps.manifest.create with the given xoxp- user token and manifest.
+   * Returns the new app's ID, OAuth redirect URL, and OAuth credentials.
+   */
+  createAppManifest(
+    xoxpToken: string,
+    manifest: AppManifest,
+  ): Promise<{
+    appId: string;
+    oauthRedirectUrl: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+  }>;
+
+  /**
+   * Call apps.manifest.update with the given xoxp- user token, app ID, and manifest.
+   * Updates the manifest of an already-provisioned Slack app in-place.
+   */
+  updateAppManifest(
+    xoxpToken: string,
+    appId: string,
+    manifest: AppManifest,
+  ): Promise<void>;
+
+  /**
+   * Call apps.manifest.delete with the given xoxp- user token and app ID.
+   * Permanently deletes a provisioned Slack app.
+   */
+  deleteApp(xoxpToken: string, appId: string): Promise<void>;
+
+  /**
+   * Exchange an OAuth authorization code for a bot token via oauth.v2.access.
+   */
+  exchangeOAuthCode(
+    code: string,
+    clientId: string,
+    clientSecret: string,
+    redirectUri: string,
+  ): Promise<{ botToken: string }>;
+
+  /**
+   * Call auth.test with a bot token to resolve the bot's own Slack user id.
+   * Used right after exchangeOAuthCode() to persist `agent.slackId`.
+   */
+  authTest(botToken: string): Promise<{ userId: string }>;
+}
+
+// ─── Agent manifest ───────────────────────────────────────────────────────────
+
+/**
+ * Builds the Slack app manifest for a Shipwright agent.
+ *
+ * Used for both initial provisioning (pass redirectUri for the OAuth callback)
+ * and subsequent manifest syncs (omit redirectUri to keep localhost default).
+ * Socket Mode and the full event/agent view config are always applied — there
+ * is no separate "provisioning-only" manifest.
+ *
+ * The canonical bot scope list is exported as `AGENT_BOT_SCOPES` so that other
+ * code paths (e.g. the sync-manifest reinstall OAuth URL) can stay in sync
+ * without duplicating the array.
+ */
+export const AGENT_BOT_SCOPES: string[] = [
+  "app_mentions:read",
+  "assistant:write",
+  "channels:history",
+  "channels:read",
+  "chat:write",
+  "files:read",
+  "files:write",
+  "groups:history",
+  "im:history",
+  "im:write",
+  "mpim:history",
+  "reactions:read",
+  "reactions:write",
+  "users:read",
+  "users:read.email",
+];
+
+export function buildAgentManifest(
+  appName: string,
+  redirectUri?: string,
+): AppManifest {
+  return {
+    display_information: {
+      name: appName,
+      description: `${appName} — powered by Shipwright`,
+      background_color: "#1a1a2e",
+    },
+    features: {
+      app_home: {
+        home_tab_enabled: false,
+        messages_tab_enabled: true,
+        messages_tab_read_only_enabled: false,
+      },
+      bot_user: {
+        display_name: appName,
+        always_online: true,
+      },
+      agent_view: {
+        agent_description: `${appName} — powered by Shipwright`,
+        suggested_prompts: [],
+      },
+    },
+    oauth_config: {
+      scopes: {
+        bot: AGENT_BOT_SCOPES,
+      },
+      ...(redirectUri !== undefined ? { redirect_urls: [redirectUri] } : {}),
+    },
+    settings: {
+      org_deploy_enabled: false,
+      socket_mode_enabled: true,
+      event_subscriptions: {
+        bot_events: [
+          "agent_session_stopped",
+          "app_mention",
+          "message.channels",
+          "message.groups",
+          "message.im",
+          "reaction_added",
+        ],
+      },
+    },
+  };
+}
+
+// ─── HTTP implementation ──────────────────────────────────────────────────────
+
+/**
+ * Production implementation — calls real Slack API endpoints.
+ *
+ * The constructor takes optional Slack API URL overrides for testing/staging.
+ */
+export class HttpSlackProvisioningClient implements SlackProvisioningClient {
+  private readonly apiBase: string;
+  private readonly fetchFn: typeof fetch;
+
+  constructor(opts?: { apiBase?: string; fetchFn?: typeof fetch }) {
+    this.apiBase = opts?.apiBase ?? "https://slack.com/api";
+    this.fetchFn = opts?.fetchFn ?? fetch;
+  }
+
+  async exchangeOAuthCode(
+    code: string,
+    clientId: string,
+    clientSecret: string,
+    redirectUri: string,
+  ): Promise<{ botToken: string }> {
+    const url = `${this.apiBase}/oauth.v2.access`;
+    const params = new URLSearchParams({
+      code,
+      redirect_uri: redirectUri,
+    });
+
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString(
+      "base64",
+    );
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${credentials}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: params.toString(),
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `Slack oauth.v2.access HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as {
+      ok: boolean;
+      error?: string;
+      access_token?: string;
+    };
+
+    if (!data.ok) {
+      throw new Error(`Slack oauth.v2.access failed: ${data.error}`);
+    }
+
+    if (!data.access_token) {
+      throw new Error("Slack oauth.v2.access response missing access_token");
+    }
+
+    return { botToken: data.access_token };
+  }
+
+  async authTest(botToken: string): Promise<{ userId: string }> {
+    const url = `${this.apiBase}/auth.test`;
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${botToken}`,
+      },
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `Slack auth.test HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as {
+      ok: boolean;
+      error?: string;
+      user_id?: string;
+    };
+
+    if (!data.ok) {
+      throw new Error(`Slack auth.test failed: ${data.error}`);
+    }
+
+    if (!data.user_id) {
+      throw new Error("Slack auth.test response missing user_id");
+    }
+
+    return { userId: data.user_id };
+  }
+
+  async updateAppManifest(
+    xoxpToken: string,
+    appId: string,
+    manifest: AppManifest,
+  ): Promise<void> {
+    const url = `${this.apiBase}/apps.manifest.update`;
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${xoxpToken}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify({
+        app_id: appId,
+        manifest: JSON.stringify(manifest),
+      }),
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `Slack apps.manifest.update HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as { ok: boolean; error?: string };
+
+    if (!data.ok) {
+      throw new Error(`Slack apps.manifest.update failed: ${data.error}`);
+    }
+  }
+
+  async deleteApp(xoxpToken: string, appId: string): Promise<void> {
+    const url = `${this.apiBase}/apps.manifest.delete`;
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${xoxpToken}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify({ app_id: appId }),
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `Slack apps.manifest.delete HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as { ok: boolean; error?: string };
+
+    if (!data.ok) {
+      throw new Error(`Slack apps.manifest.delete failed: ${data.error}`);
+    }
+  }
+
+  async createAppManifest(
+    xoxpToken: string,
+    manifest: AppManifest,
+  ): Promise<{
+    appId: string;
+    oauthRedirectUrl: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+  }> {
+    const url = `${this.apiBase}/apps.manifest.create`;
+    const resp = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${xoxpToken}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify({ manifest: JSON.stringify(manifest) }),
+    });
+
+    if (!resp.ok) {
+      throw new Error(
+        `Slack apps.manifest.create HTTP error: ${resp.status} ${resp.statusText}`,
+      );
+    }
+
+    const data = (await resp.json()) as {
+      ok: boolean;
+      error?: string;
+      app_id?: string;
+      oauth_authorize_url?: string;
+      credentials?: {
+        client_id?: string;
+        client_secret?: string;
+        signing_secret?: string;
+      };
+    };
+
+    if (!data.ok) {
+      throw new Error(`Slack apps.manifest.create failed: ${data.error}`);
+    }
+
+    if (!data.app_id || !data.oauth_authorize_url) {
+      throw new Error(
+        "Slack apps.manifest.create response missing app_id or oauth_authorize_url",
+      );
+    }
+
+    if (
+      !data.credentials?.client_id ||
+      !data.credentials?.client_secret ||
+      !data.credentials?.signing_secret
+    ) {
+      throw new Error(
+        "Slack apps.manifest.create response missing credentials (client_id, client_secret, or signing_secret)",
+      );
+    }
+
+    return {
+      appId: data.app_id,
+      oauthRedirectUrl: data.oauth_authorize_url,
+      clientId: data.credentials.client_id,
+      clientSecret: data.credentials.client_secret,
+      signingSecret: data.credentials.signing_secret,
+    };
+  }
+}

package/src/slack-provisioning-client.unit.test.ts

@@ -0,0 +1,80 @@
+/**
+ * admin/src/slack-provisioning-client.unit.test.ts
+ * Unit tests for buildAgentManifest. No I/O, no network — shape assertions only.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { buildAgentManifest } from "./slack-provisioning-client.ts";
+
+const NAME = "test-agent";
+const REDIRECT = "https://shipwright.example.com/admin/provision/complete";
+
+describe("buildAgentManifest", () => {
+  describe("buildAgentManifest without redirectUri (unit)", () => {
+    const manifest = buildAgentManifest(NAME);
+
+    it("sets socket_mode_enabled: true", () => {
+      expect(manifest.settings?.socket_mode_enabled).toBe(true);
+    });
+
+    it("includes required bot events", () => {
+      const events = manifest.settings?.event_subscriptions?.bot_events ?? [];
+      expect(events).toContain("message.im");
+      expect(events).toContain("message.channels");
+      expect(events).toContain("message.groups");
+      expect(events).toContain("app_mention");
+      expect(events).toContain("reaction_added");
+      // AGS-1.1: Slack's native Stop/session-cancellation event for the
+      // Agent Sessions API — without this subscription the agent has no way
+      // to know when Slack has externally halted a stream (confirmed via
+      // repeated missing_agent_session_stopped_event_subscription log lines).
+      expect(events).toContain("agent_session_stopped");
+    });
+
+    it("includes agent_view", () => {
+      expect(manifest.features?.agent_view).toBeDefined();
+      expect(manifest.features?.agent_view?.agent_description).toContain(NAME);
+    });
+
+    it("sets always_online: true", () => {
+      expect(manifest.features?.bot_user?.always_online).toBe(true);
+    });
+
+    it("includes required scopes", () => {
+      const scopes = manifest.oauth_config?.scopes.bot ?? [];
+      expect(scopes).toContain("assistant:write");
+      expect(scopes).toContain("app_mentions:read");
+      expect(scopes).toContain("im:history");
+      expect(scopes).toContain("mpim:history");
+      expect(scopes).toContain("channels:history");
+      expect(scopes).toContain("groups:history");
+      expect(scopes).toContain("chat:write");
+      expect(scopes).toContain("users:read.email");
+    });
+
+    it("omits redirect_urls when no redirectUri provided", () => {
+      expect(manifest.oauth_config?.redirect_urls).toBeUndefined();
+    });
+
+    it("uses agent name in display_information", () => {
+      expect(manifest.display_information.name).toBe(NAME);
+      expect(manifest.display_information.description).toContain(NAME);
+    });
+  });
+
+  describe("provisioning (with redirectUri)", () => {
+    const manifest = buildAgentManifest(NAME, REDIRECT);
+
+    it("sets redirect_urls to the provided URI", () => {
+      expect(manifest.oauth_config?.redirect_urls).toEqual([REDIRECT]);
+    });
+
+    it("still sets socket_mode_enabled: true", () => {
+      expect(manifest.settings?.socket_mode_enabled).toBe(true);
+    });
+
+    it("still includes agent_view", () => {
+      expect(manifest.features?.agent_view).toBeDefined();
+    });
+  });
+});