@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/linear/README.md

@@ -0,0 +1,65 @@
+# Linear Integration
+
+Bidirectional sync between Agent Swarm and Linear. Webhook-driven inbound (Linear issues become swarm tasks) and event-bus-driven outbound (task completion/failure posts comments back to Linear).
+
+## Setup
+
+1. **Create OAuth Application** at `linear.app/settings/api/applications`
+2. **Set callback URL** to your server's `/api/trackers/linear/callback`
+   - Local: `http://localhost:3013/api/trackers/linear/callback`
+   - Production: `https://your-domain.com/api/trackers/linear/callback`
+3. **Set Actor** to "Application" (enables `actor=app` in OAuth flow)
+4. **Enable webhooks** and select "Issue" events in the app settings
+5. **Copy credentials** to `.env`:
+   ```bash
+   LINEAR_CLIENT_ID=<from app settings>
+   LINEAR_CLIENT_SECRET=<shown once on creation>
+   LINEAR_SIGNING_SECRET=<from webhook settings>
+   # LINEAR_TEAM_ID=<optional: scope to a specific team>
+   ```
+6. **Start server**: `bun run start:http`
+7. **Run OAuth flow**: visit `http://localhost:3013/api/trackers/linear/authorize` in your browser
+8. **Verify connection**:
+   ```bash
+   curl -H "Authorization: Bearer $API_KEY" http://localhost:3013/api/trackers/linear/status
+   ```
+9. **Local webhook testing**: use ngrok or cloudflared to create a tunnel, then configure the public URL as the webhook URL in your Linear app settings:
+   ```bash
+   ngrok http 3013
+   # Then set webhook URL in Linear to: https://<ngrok-id>.ngrok.io/api/trackers/linear/webhook
+   ```
+
+## Scopes
+
+The OAuth flow requests these scopes:
+
+| Scope | Purpose |
+|-------|---------|
+| `read` | Read workspace data (teams, issues, users) |
+| `write` | Update issues and projects |
+| `issues:create` | Create new issues |
+| `comments:create` | Add comments to issues |
+| `app:assignable` | App appears in the assignee dropdown |
+| `app:mentionable` | App can be @mentioned in issues and comments |
+
+## Architecture
+
+```
+src/linear/
+  app.ts        # Initialization, env config, route registration
+  client.ts     # Linear GraphQL API client wrapper
+  oauth.ts      # OAuth route handlers (authorize, callback, status)
+  webhook.ts    # Inbound webhook handler (issue events -> swarm tasks)
+  outbound.ts   # Outbound sync (event bus -> Linear comments)
+  sync.ts       # Sync helpers (status mapping, etc.)
+  types.ts      # TypeScript types for Linear payloads
+  index.ts      # Public exports
+```
+
+**Key design decisions:**
+
+- **Generic OAuth layer** (`src/oauth/`, `oauth_apps`, `oauth_tokens` tables) serves any provider. Linear-specific code only lives in `src/linear/`.
+- **Generic tracker tables** (`tracker_sync`, `tracker_agent_mapping`) serve any tracker. The `provider` column distinguishes Linear from future integrations.
+- **Inbound**: Webhook events create swarm tasks via `createTaskExtended(source: "linear")`. The webhook handler verifies HMAC signatures using `LINEAR_SIGNING_SECRET`.
+- **Outbound**: Subscribes to the workflow event bus for `task.completed` and `task.failed` events. Posts completion/failure comments back to the linked Linear issue.
+- **Loop prevention**: A 5-second window prevents outbound sync from firing immediately after an inbound webhook (checked via `lastSyncOrigin` + `lastSyncedAt` on the tracker_sync row).

package/src/linear/app.ts

@@ -0,0 +1,48 @@
+import { upsertOAuthApp } from "../be/db-queries/oauth";
+import { initLinearOutboundSync, teardownLinearOutboundSync } from "./outbound";
+
+let initialized = false;
+
+export function isLinearEnabled(): boolean {
+  const disabled = process.env.LINEAR_DISABLE;
+  if (disabled === "true" || disabled === "1") return false;
+  const enabled = process.env.LINEAR_ENABLED;
+  if (enabled === "false" || enabled === "0") return false;
+  return !!process.env.LINEAR_CLIENT_ID;
+}
+
+export function resetLinear(): void {
+  teardownLinearOutboundSync();
+  initialized = false;
+}
+
+export function initLinear(): boolean {
+  if (initialized) return isLinearEnabled();
+  initialized = true;
+
+  if (!isLinearEnabled()) {
+    console.log("[Linear] Integration disabled or LINEAR_CLIENT_ID not set");
+    return false;
+  }
+
+  const clientId = process.env.LINEAR_CLIENT_ID!;
+  const clientSecret = process.env.LINEAR_CLIENT_SECRET ?? "";
+  const redirectUri =
+    process.env.LINEAR_REDIRECT_URI ??
+    `http://localhost:${process.env.PORT || "3013"}/api/trackers/linear/callback`;
+
+  upsertOAuthApp("linear", {
+    clientId,
+    clientSecret,
+    authorizeUrl: "https://linear.app/oauth/authorize",
+    tokenUrl: "https://api.linear.app/oauth/token",
+    redirectUri,
+    scopes: "read,write,issues:create,comments:create,app:assignable,app:mentionable",
+    metadata: JSON.stringify({ actor: "app" }),
+  });
+
+  initLinearOutboundSync();
+
+  console.log("[Linear] Integration initialized");
+  return true;
+}

package/src/linear/client.ts

@@ -0,0 +1,18 @@
+import { LinearClient } from "@linear/sdk";
+import { getOAuthTokens } from "../be/db-queries/oauth";
+
+let linearClient: LinearClient | null = null;
+
+export function getLinearClient(): LinearClient | null {
+  const tokens = getOAuthTokens("linear");
+  if (!tokens) return null;
+
+  if (!linearClient) {
+    linearClient = new LinearClient({ accessToken: tokens.accessToken });
+  }
+  return linearClient;
+}
+
+export function resetLinearClient(): void {
+  linearClient = null;
+}

package/src/linear/index.ts

@@ -0,0 +1 @@
+export { initLinear, isLinearEnabled, resetLinear } from "./app";

package/src/linear/oauth.ts

@@ -0,0 +1,35 @@
+import { getOAuthApp } from "../be/db-queries/oauth";
+import { buildAuthorizationUrl, exchangeCode, type OAuthProviderConfig } from "../oauth/wrapper";
+
+export function getLinearOAuthConfig(): OAuthProviderConfig | null {
+  const app = getOAuthApp("linear");
+  if (!app) return null;
+
+  const metadata = JSON.parse(app.metadata || "{}");
+  return {
+    provider: "linear",
+    clientId: app.clientId,
+    clientSecret: app.clientSecret,
+    authorizeUrl: app.authorizeUrl,
+    tokenUrl: app.tokenUrl,
+    redirectUri: app.redirectUri,
+    scopes: app.scopes.split(","),
+    extraParams: metadata.actor ? { actor: metadata.actor } : {},
+  };
+}
+
+export async function getLinearAuthorizationUrl(): Promise<string | null> {
+  const config = getLinearOAuthConfig();
+  if (!config) return null;
+  const result = await buildAuthorizationUrl(config);
+  return result.url;
+}
+
+export async function handleLinearCallback(
+  code: string,
+  state: string,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
+  const config = getLinearOAuthConfig();
+  if (!config) throw new Error("Linear OAuth not configured");
+  return exchangeCode(config, code, state);
+}

package/src/linear/outbound.ts

@@ -0,0 +1,212 @@
+import { getTrackerSync, updateTrackerSync } from "../be/db-queries/tracker";
+import { workflowEventBus } from "../workflows/event-bus";
+import { getLinearClient } from "./client";
+import {
+  endAgentSession,
+  postAgentSessionAction,
+  postAgentSessionThought,
+  taskSessionMap,
+} from "./sync";
+
+let subscribed = false;
+
+const LOOP_PREVENTION_WINDOW_MS = 5_000;
+
+export function initLinearOutboundSync(): void {
+  if (subscribed) return;
+  subscribed = true;
+
+  workflowEventBus.on("task.created", handleTaskCreated);
+  workflowEventBus.on("task.completed", handleTaskCompleted);
+  workflowEventBus.on("task.failed", handleTaskFailed);
+  workflowEventBus.on("task.cancelled", handleTaskCancelled);
+  workflowEventBus.on("task.progress", handleTaskProgress);
+  console.log("[Linear] Outbound sync subscribed to event bus");
+}
+
+export function teardownLinearOutboundSync(): void {
+  if (!subscribed) return;
+  subscribed = false;
+
+  workflowEventBus.off("task.created", handleTaskCreated);
+  workflowEventBus.off("task.completed", handleTaskCompleted);
+  workflowEventBus.off("task.failed", handleTaskFailed);
+  workflowEventBus.off("task.cancelled", handleTaskCancelled);
+  workflowEventBus.off("task.progress", handleTaskProgress);
+  console.log("[Linear] Outbound sync unsubscribed from event bus");
+}
+
+async function handleTaskCreated(data: unknown): Promise<void> {
+  const { taskId, source } = data as { taskId: string; source?: string };
+  if (!taskId) return;
+
+  // Only post action activities for Linear-sourced tasks that have an AgentSession
+  if (source !== "linear") return;
+
+  const sessionId = taskSessionMap.get(taskId);
+  if (!sessionId) return;
+
+  postAgentSessionAction(sessionId, "Processing", `Task ${taskId} assigned to agent`).catch(
+    (err) => {
+      console.error(`[Linear Outbound] Failed to post action activity for task ${taskId}:`, err);
+    },
+  );
+}
+
+async function handleTaskProgress(data: unknown): Promise<void> {
+  const { taskId, progress } = data as { taskId: string; progress?: string };
+  if (!taskId || !progress) return;
+
+  const sessionId = taskSessionMap.get(taskId);
+  if (!sessionId) return;
+
+  postAgentSessionThought(sessionId, progress).catch((err) => {
+    console.error(`[Linear Outbound] Failed to post progress thought for task ${taskId}:`, err);
+  });
+}
+
+async function handleTaskCompleted(data: unknown): Promise<void> {
+  const { taskId, output } = data as { taskId: string; output?: string };
+  if (!taskId) return;
+
+  const sync = getTrackerSync("linear", "task", taskId);
+  if (!sync) return;
+
+  if (shouldSkipForLoopPrevention(sync)) return;
+
+  const sessionId = taskSessionMap.get(taskId);
+  const body = output ? `Task completed.\n\n${output.slice(0, 2000)}` : "Task completed.";
+
+  // Prefer AgentSession activity (shows in the agent panel) over issue comment (avoids duplication)
+  if (sessionId) {
+    endAgentSession(sessionId, body, "response").catch((err) => {
+      console.error(`[Linear Outbound] Failed to end AgentSession for task ${taskId}:`, err);
+    });
+    taskSessionMap.delete(taskId);
+    console.log(`[Linear Outbound] Posted completion response to AgentSession for task ${taskId}`);
+  } else {
+    // No session — fall back to issue comment
+    try {
+      const client = getLinearClient();
+      if (!client) {
+        console.log("[Linear Outbound] No Linear client available, skipping sync for", taskId);
+        return;
+      }
+      const comment = output
+        ? `Task completed by swarm agent.\n\nOutput:\n${output.slice(0, 2000)}`
+        : "Task completed by swarm agent.";
+      await client.createComment({ issueId: sync.externalId, body: comment });
+      console.log(`[Linear Outbound] Posted completion comment for task ${taskId}`);
+    } catch (error) {
+      console.error(
+        `[Linear Outbound] Failed to sync task completion for ${taskId}:`,
+        error instanceof Error ? error.message : error,
+      );
+    }
+  }
+
+  updateTrackerSync(sync.id, {
+    lastSyncOrigin: "swarm",
+    lastSyncedAt: new Date().toISOString(),
+  });
+}
+
+async function handleTaskFailed(data: unknown): Promise<void> {
+  const { taskId, failureReason } = data as { taskId: string; failureReason?: string };
+  if (!taskId) return;
+
+  const sync = getTrackerSync("linear", "task", taskId);
+  if (!sync) return;
+
+  if (shouldSkipForLoopPrevention(sync)) return;
+
+  const sessionId = taskSessionMap.get(taskId);
+  const body = failureReason ? `Task failed.\n\n${failureReason.slice(0, 2000)}` : "Task failed.";
+
+  // Prefer AgentSession error activity over issue comment (avoids duplication)
+  if (sessionId) {
+    endAgentSession(sessionId, body, "error").catch((err) => {
+      console.error(`[Linear Outbound] Failed to end AgentSession for task ${taskId}:`, err);
+    });
+    taskSessionMap.delete(taskId);
+    console.log(`[Linear Outbound] Posted failure error to AgentSession for task ${taskId}`);
+  } else {
+    // No session — fall back to issue comment
+    try {
+      const client = getLinearClient();
+      if (!client) {
+        console.log("[Linear Outbound] No Linear client available, skipping sync for", taskId);
+        return;
+      }
+      const comment = failureReason
+        ? `Task failed.\n\nReason:\n${failureReason.slice(0, 2000)}`
+        : "Task failed.";
+      await client.createComment({ issueId: sync.externalId, body: comment });
+      console.log(`[Linear Outbound] Posted failure comment for task ${taskId}`);
+    } catch (error) {
+      console.error(
+        `[Linear Outbound] Failed to sync task failure for ${taskId}:`,
+        error instanceof Error ? error.message : error,
+      );
+    }
+  }
+
+  updateTrackerSync(sync.id, {
+    lastSyncOrigin: "swarm",
+    lastSyncedAt: new Date().toISOString(),
+  });
+}
+
+async function handleTaskCancelled(data: unknown): Promise<void> {
+  const { taskId } = data as { taskId: string };
+  if (!taskId) return;
+
+  const sync = getTrackerSync("linear", "task", taskId);
+  if (!sync) return;
+
+  if (shouldSkipForLoopPrevention(sync)) return;
+
+  const sessionId = taskSessionMap.get(taskId);
+  const body = "Task cancelled.";
+
+  if (sessionId) {
+    endAgentSession(sessionId, body, "error").catch((err) => {
+      console.error(
+        `[Linear Outbound] Failed to end AgentSession for cancelled task ${taskId}:`,
+        err,
+      );
+    });
+    taskSessionMap.delete(taskId);
+    console.log(`[Linear Outbound] Posted cancellation to AgentSession for task ${taskId}`);
+  } else {
+    try {
+      const client = getLinearClient();
+      if (!client) {
+        console.log("[Linear Outbound] No Linear client available, skipping sync for", taskId);
+        return;
+      }
+      await client.createComment({ issueId: sync.externalId, body: "Task cancelled by swarm." });
+      console.log(`[Linear Outbound] Posted cancellation comment for task ${taskId}`);
+    } catch (error) {
+      console.error(
+        `[Linear Outbound] Failed to sync task cancellation for ${taskId}:`,
+        error instanceof Error ? error.message : error,
+      );
+    }
+  }
+
+  updateTrackerSync(sync.id, {
+    lastSyncOrigin: "swarm",
+    lastSyncedAt: new Date().toISOString(),
+  });
+}
+
+function shouldSkipForLoopPrevention(sync: {
+  lastSyncOrigin: string | null;
+  lastSyncedAt: string;
+}): boolean {
+  if (sync.lastSyncOrigin !== "external") return false;
+  const lastSyncTime = new Date(sync.lastSyncedAt).getTime();
+  if (Number.isNaN(lastSyncTime)) return false;
+  return Date.now() - lastSyncTime < LOOP_PREVENTION_WINDOW_MS;
+}