Multi-tenant support in Linear adapter

.changeset/dirty-masks-bathe.md

@@ -0,0 +1,11 @@
+---
+"@chat-adapter/linear": major
+---
+
+Add multi-tenant support in the Linear adapter using `clientId` / `clientSecret`.
+
+The Linear adapter now exposes a `handleOAuthCallback()` function for OAuth multi-tenant support. 
+
+Add `clientCredentials.scopes` to the Linear adapter so single-tenant client-credentials auth can request custom OAuth scopes.
+
+Add support for agent sessions in Linear, with streaming / task / plan support.

examples/nextjs-chat/.env.example

@@ -32,12 +32,22 @@ BOT_USERNAME=mybot
 # GITHUB_WEBHOOK_SECRET=your-webhook-secret
 # GITHUB_BOT_USERNAME=my-bot  # or my-bot[bot] for GitHub Apps
 
-# Linear (optional) - use API key OR OAuth app, not both
+# Linear (optional) - use API key, access token, client credentials, or multi-tenant OAuth installs
 # API key authentication (simplest):
 # LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
-# OR OAuth app (client credentials - recommended for apps):
+# OR pre-obtained OAuth access token:
+# LINEAR_ACCESS_TOKEN=lin_oauth_xxxxxxxxxxxx
+# OR single-tenant client credentials:
+# LINEAR_CLIENT_CREDENTIALS_CLIENT_ID=your-client-id
+# LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET=your-client-secret
+# LINEAR_CLIENT_CREDENTIALS_SCOPES=read,write,comments:create,issues:create
+# OR multi-tenant OAuth installs:
 # LINEAR_CLIENT_ID=your-client-id
 # LINEAR_CLIENT_SECRET=your-client-secret
+# LINEAR_REDIRECT_URI=https://your-domain.com/api/linear/install/callback
+# Optional inbound webhook mode:
+# LINEAR_MODE=comments
+# Use LINEAR_MODE=agent-sessions for app-actor installs
 # Required for either auth method:
 # LINEAR_WEBHOOK_SECRET=your-webhook-secret
 # LINEAR_BOT_USERNAME=my-bot

examples/nextjs-chat/README.md

@@ -82,10 +82,17 @@ Copy `.env.example` for the full list. At minimum, set `BOT_USERNAME` and creden
 | `DISCORD_PUBLIC_KEY` | Discord interaction verification key |
 | `GITHUB_TOKEN` | GitHub PAT or App credentials |
 | `LINEAR_API_KEY` | Linear API key |
+| `LINEAR_CLIENT_ID` | Linear OAuth app client ID for multi-tenant installs |
+| `LINEAR_CLIENT_SECRET` | Linear OAuth app client secret for multi-tenant installs |
+| `LINEAR_REDIRECT_URI` | Linear OAuth callback URL |
+| `LINEAR_MODE` | Linear inbound mode: `comments` or `agent-sessions` |
+| `LINEAR_WEBHOOK_SECRET` | Linear webhook signing secret |
 | `REDIS_URL` | Redis connection string |
 
 See the [Chat SDK docs](https://chat-sdk.dev/docs) for full platform setup guides.
 
+For Linear app-actor mode, set `LINEAR_MODE=agent-sessions`, enable **Agent session events** on the webhook, install the Linear app with `actor=app` and `app:mentionable`, and keep using the existing `thread.startTyping()` / `thread.post(...)` handler flow. The adapter maps those calls onto Linear agent activities automatically.
+
 ## Recording and replay
 
 The app includes a recording system for capturing production webhook interactions and converting them into replay tests.

examples/nextjs-chat/src/app/api/linear/install/callback/route.ts

@@ -0,0 +1,29 @@
+import { bot } from "@/lib/bot";
+
+export async function GET(request: Request) {
+  const adapter = bot.getAdapter("linear");
+  const redirectUri = process.env.LINEAR_REDIRECT_URI;
+
+  if (!adapter) {
+    return new Response("Linear adapter not configured", { status: 500 });
+  }
+
+  if (!redirectUri) {
+    return new Response("LINEAR_REDIRECT_URI is not configured", {
+      status: 500,
+    });
+  }
+
+  try {
+    await bot.initialize();
+    const { organizationId } = await adapter.handleOAuthCallback(request, {
+      redirectUri,
+    });
+    return new Response(
+      `Linear app installed for organization ${organizationId}!`
+    );
+  } catch (error) {
+    console.error("[linear/install/callback] OAuth error:", error);
+    return new Response("OAuth installation failed", { status: 500 });
+  }
+}

examples/nextjs-chat/src/app/api/linear/install/route.ts

@@ -0,0 +1,31 @@
+const LINEAR_INSTALL_SCOPES = [
+  "read",
+  "write",
+  "comments:create",
+  "issues:create",
+  "app:mentionable",
+];
+
+export function GET() {
+  const clientId = process.env.LINEAR_CLIENT_ID;
+  const redirectUri = process.env.LINEAR_REDIRECT_URI;
+
+  if (!clientId) {
+    return new Response("LINEAR_CLIENT_ID is not configured", { status: 500 });
+  }
+
+  if (!redirectUri) {
+    return new Response("LINEAR_REDIRECT_URI is not configured", {
+      status: 500,
+    });
+  }
+
+  const installUrl = new URL("https://linear.app/oauth/authorize");
+  installUrl.searchParams.set("client_id", clientId);
+  installUrl.searchParams.set("redirect_uri", redirectUri);
+  installUrl.searchParams.set("response_type", "code");
+  installUrl.searchParams.set("actor", "app");
+  installUrl.searchParams.set("scope", LINEAR_INSTALL_SCOPES.join(","));
+
+  return Response.redirect(installUrl.toString(), 302);
+}

examples/nextjs-chat/src/app/page.tsx

@@ -92,7 +92,14 @@ GITHUB_WEBHOOK_SECRET=...`}
 
       <h3>Linear</h3>
       <pre>
-        {`LINEAR_API_KEY=lin_api_...
+        {`# Single-workspace
+LINEAR_API_KEY=lin_api_...
+LINEAR_WEBHOOK_SECRET=...
+
+# OR multi-tenant OAuth installs
+LINEAR_CLIENT_ID=...
+LINEAR_CLIENT_SECRET=...
+LINEAR_REDIRECT_URI=https://your-domain.com/api/linear/install/callback
 LINEAR_WEBHOOK_SECRET=...`}
       </pre>
     </main>

examples/nextjs-chat/src/lib/adapters.ts

@@ -203,19 +203,24 @@ export function buildAdapters(): Adapters {
     }
   }
 
-  // Linear adapter (optional) - env vars: LINEAR_WEBHOOK_SECRET + (LINEAR_API_KEY or LINEAR_CLIENT_ID/SECRET)
+  // Linear adapter (optional) - env vars: LINEAR_WEBHOOK_SECRET + (LINEAR_API_KEY, LINEAR_ACCESS_TOKEN, LINEAR_CLIENT_CREDENTIALS_*, or LINEAR_CLIENT_ID/SECRET).
+  // Set LINEAR_MODE=agent-sessions for app-actor installs with Agent session events + app:mentionable.
   if (process.env.LINEAR_WEBHOOK_SECRET) {
     try {
       adapters.linear = withRecording(
         createLinearAdapter({
           logger: logger.child("linear"),
+          mode:
+            process.env.LINEAR_MODE === "agent-sessions"
+              ? "agent-sessions"
+              : "comments",
         }),
         "linear",
         LINEAR_METHODS
       );
     } catch {
       console.warn(
-        "[chat] Failed to create linear adapter (check LINEAR_API_KEY or LINEAR_CLIENT_ID/SECRET)"
+        "[chat] Failed to create linear adapter (check LINEAR_API_KEY, LINEAR_ACCESS_TOKEN, LINEAR_CLIENT_CREDENTIALS_*, or LINEAR_CLIENT_ID/SECRET)"
       );
     }
   }