@mastra/factory 0.0.0 → 0.1.0-alpha.3

package/dist/integrations/linear/integration.js

@@ -0,0 +1,962 @@
+// src/integrations/linear/agent-tools.ts
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+function createLinearGetIssueTool(linear, orgId) {
+  return createTool({
+    id: "linear_get_issue",
+    description: "Fetch a Linear issue's full details \u2014 title, description, state, assignee, labels, priority, and discussion comments. Use this whenever you're working on a Linear issue (e.g. ENG-123) to get its complete context.",
+    inputSchema: z.object({
+      issue: z.string().min(1).describe('The Linear issue identifier (e.g. "ENG-123") or issue UUID.')
+    }),
+    execute: async ({ issue }) => {
+      const connection = await linear.loadConnection(orgId);
+      if (!connection) {
+        return { error: "Linear is not connected for this repository. Connect Linear in Settings to fetch issues." };
+      }
+      try {
+        const accessToken = await linear.getFreshAccessToken(connection);
+        const detail = await linear.intake.getIssue({
+          connection: { type: "oauth", accessToken },
+          issueId: issue.trim()
+        });
+        if (!detail) {
+          return { error: `Linear issue "${issue}" was not found in this workspace.` };
+        }
+        return detail;
+      } catch (err) {
+        if (err instanceof LinearReauthRequiredError) {
+          return { error: err.message };
+        }
+        return { error: `Failed to fetch Linear issue: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    }
+  });
+}
+function createLinearCommentTool(linear, orgId) {
+  return createTool({
+    id: "linear_create_comment",
+    description: "Post a comment on a Linear issue (e.g. to report investigation findings, link a PR, or ask a clarifying question). The comment is posted as the connected Linear integration, so make clear it comes from the agent.",
+    inputSchema: z.object({
+      issue: z.string().min(1).describe('The Linear issue identifier (e.g. "ENG-123") or issue UUID.'),
+      body: z.string().min(1).describe("The comment body, as Linear-flavored markdown.")
+    }),
+    execute: async ({ issue, body }) => {
+      const connection = await linear.loadConnection(orgId);
+      if (!connection) {
+        return { error: "Linear is not connected for this repository. Connect Linear in Settings to post comments." };
+      }
+      if (!linear.canPostComments(connection)) {
+        return {
+          error: "The Linear connection does not have comment permissions. Reconnect Linear in Settings to grant them."
+        };
+      }
+      try {
+        const accessToken = await linear.getFreshAccessToken(connection);
+        const comment = await linear.intake.createComment({
+          connection: { type: "oauth", accessToken },
+          issueId: issue.trim(),
+          body
+        });
+        if (!comment) {
+          return { error: `Linear issue "${issue}" was not found in this workspace.` };
+        }
+        return { posted: true, url: comment.url };
+      } catch (err) {
+        if (err instanceof LinearReauthRequiredError) {
+          return { error: err.message };
+        }
+        return { error: `Failed to post Linear comment: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    }
+  });
+}
+async function buildLinearAgentTools({
+  requestContext,
+  linear
+}) {
+  if (!linear.authEnabled) return {};
+  const ctx = requestContext.get("controller");
+  const resourceId = ctx?.resourceId;
+  if (!resourceId) return {};
+  const orgId = await linear.resolveOrgId(resourceId);
+  if (!orgId) return {};
+  const check = await linear.checkConnection(orgId);
+  if (!check.connected) return {};
+  return {
+    linear_get_issue: createLinearGetIssueTool(linear, orgId),
+    // Only offered when the granted OAuth scope allows posting comments —
+    // connections made before `comments:create` was requested are read-only
+    // until the org reconnects Linear.
+    ...check.canComment ? { linear_create_comment: createLinearCommentTool(linear, orgId) } : {}
+  };
+}
+
+// src/integrations/linear/routes.ts
+import { registerApiRoute } from "@mastra/core/server";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function loose(c) {
+  return c;
+}
+async function resolveOrgTenant(c, auth) {
+  await auth.ensureUser(c);
+  const tenant = auth.tenant(c);
+  if (!tenant) return { response: c.json({ error: "unauthorized" }, 401) };
+  if (!tenant.orgId) {
+    return {
+      response: c.json(
+        {
+          error: "organization_required",
+          message: "Linear intake requires an organization. Personal accounts cannot connect Linear."
+        },
+        403
+      )
+    };
+  }
+  return { tenant: { orgId: tenant.orgId, userId: tenant.userId } };
+}
+function parseAfterCursor(raw) {
+  if (raw === void 0 || raw === "") return void 0;
+  if (raw.length > 512 || !/^[\w+/=.:-]+$/.test(raw)) return null;
+  return raw;
+}
+function linearFetchError(c, err) {
+  if (err instanceof LinearReauthRequiredError || err.status === 401) {
+    return c.json({ error: "linear_reauth_required", message: new LinearReauthRequiredError().message }, 409);
+  }
+  return c.json({ error: "linear_fetch_failed", message: err instanceof Error ? err.message : String(err) }, 502);
+}
+function buildLinearRoutes(options) {
+  const routes = [];
+  const { linear, auth, stateSigner, intake } = options;
+  const enabled = Boolean(linear) && auth.enabled();
+  const diagnostics = () => ({
+    linearAppConfigured: Boolean(linear),
+    factoryAuthEnabled: auth.enabled(),
+    appDbConfigured: true
+  });
+  routes.push(
+    registerApiRoute("/web/linear/status", {
+      method: "GET",
+      requiresAuth: false,
+      handler: async (c) => {
+        if (!enabled || !linear || !stateSigner) {
+          return c.json({
+            enabled: false,
+            connected: false,
+            workspace: null,
+            reason: "missing_config",
+            diagnostics: diagnostics()
+          });
+        }
+        await auth.ensureUser(loose(c));
+        const tenant = auth.tenant(loose(c));
+        if (!tenant) return c.json({ error: "unauthorized", reason: "auth_required" }, 401);
+        if (!tenant.orgId) {
+          return c.json({
+            enabled: true,
+            organizationRequired: true,
+            connected: false,
+            workspace: null,
+            reason: "organization_required",
+            diagnostics: diagnostics()
+          });
+        }
+        const connection = await linear.loadConnection(tenant.orgId);
+        return c.json({
+          enabled: true,
+          connected: Boolean(connection),
+          workspace: connection ? { name: connection.workspaceName, urlKey: connection.workspaceUrlKey } : null,
+          reason: connection ? "ready" : "not_connected",
+          diagnostics: diagnostics()
+        });
+      }
+    })
+  );
+  if (!enabled || !linear || !stateSigner || !intake) {
+    return routes;
+  }
+  const redirectUri = options.redirectUri ?? `${(options.baseUrl ?? "").replace(/\/$/, "")}/auth/linear/callback`;
+  routes.push(
+    registerApiRoute("/auth/linear/connect", {
+      method: "GET",
+      requiresAuth: false,
+      handler: async (c) => {
+        const resolved = await resolveOrgTenant(loose(c), auth);
+        if ("response" in resolved) return resolved.response;
+        const state = stateSigner.sign(resolved.tenant.orgId, resolved.tenant.userId);
+        return c.redirect(linear.buildAuthorizeUrl(state, redirectUri));
+      }
+    })
+  );
+  routes.push(
+    registerApiRoute("/auth/linear/callback", {
+      method: "GET",
+      requiresAuth: false,
+      handler: async (c) => {
+        const resolved = await resolveOrgTenant(loose(c), auth);
+        if ("response" in resolved) return resolved.response;
+        const { orgId, userId } = resolved.tenant;
+        const stateTenant = stateSigner.verify(c.req.query("state"));
+        if (!stateTenant || stateTenant.userId !== userId || stateTenant.orgId !== orgId) {
+          console.warn("[Linear] OAuth callback rejected: state/tenant mismatch.");
+          return c.redirect("/?linear=error");
+        }
+        const code = c.req.query("code");
+        if (!code) {
+          return c.redirect("/?linear=error");
+        }
+        try {
+          const tokens = await linear.exchangeOAuthCode(code, redirectUri);
+          const workspace = await linear.fetchWorkspace(tokens.accessToken);
+          await linear.upsertConnection({
+            orgId,
+            userId,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+            scope: tokens.scope,
+            workspaceName: workspace.name,
+            workspaceUrlKey: workspace.urlKey
+          });
+        } catch (error) {
+          console.warn(`[Linear] OAuth callback failed to persist connection for org ${orgId}.`, error);
+          return c.redirect("/?linear=error");
+        }
+        return c.redirect("/?linear=connected");
+      }
+    })
+  );
+  routes.push(
+    registerApiRoute("/web/linear/projects", {
+      method: "GET",
+      requiresAuth: false,
+      handler: async (c) => {
+        const resolved = await resolveOrgTenant(loose(c), auth);
+        if ("response" in resolved) return resolved.response;
+        const connection = await linear.loadConnection(resolved.tenant.orgId);
+        if (!connection) {
+          return c.json({ error: "linear_not_connected", message: "Connect Linear to list Linear projects." }, 409);
+        }
+        try {
+          const accessToken = await linear.getFreshAccessToken(connection);
+          const projects = await linear.listProjects(accessToken);
+          return c.json({ projects });
+        } catch (err) {
+          return linearFetchError(loose(c), err);
+        }
+      }
+    })
+  );
+  routes.push(
+    registerApiRoute("/web/linear/issues", {
+      method: "GET",
+      requiresAuth: false,
+      handler: async (c) => {
+        const resolved = await resolveOrgTenant(loose(c), auth);
+        if ("response" in resolved) return resolved.response;
+        const after = parseAfterCursor(c.req.query("after"));
+        if (after === null) return c.json({ error: "invalid_cursor" }, 400);
+        const factoryProjectId = c.req.query("factoryProjectId");
+        if (factoryProjectId && !UUID_RE.test(factoryProjectId)) {
+          return c.json({ error: "invalid_factory_project_id" }, 400);
+        }
+        const connection = await linear.loadConnection(resolved.tenant.orgId);
+        if (!connection) {
+          return c.json({ error: "linear_not_connected", message: "Connect Linear to see intake issues." }, 409);
+        }
+        await intake.ensureReady();
+        const config = await intake.getConfig({
+          orgId: resolved.tenant.orgId,
+          userId: resolved.tenant.userId,
+          integrationIds: ["linear"]
+        });
+        const selection = config.linear;
+        if (!selection.enabled) {
+          return c.json({ error: "linear_intake_disabled", message: "Linear intake is turned off in Settings." }, 404);
+        }
+        const projectIds = selection.sourceIds ?? [];
+        if (projectIds.length === 0) {
+          return c.json({ issues: [], nextCursor: null });
+        }
+        try {
+          const accessToken = await linear.getFreshAccessToken(connection);
+          const { issues, nextCursor } = await linear.intake.listIssues({
+            connection: { type: "oauth", accessToken },
+            sourceIds: projectIds,
+            cursor: after
+          });
+          const issuePayload = issues.map((issue) => ({
+            id: issue.id,
+            identifier: issue.identifier,
+            title: issue.title,
+            url: issue.url,
+            state: issue.state ?? "",
+            stateType: issue.stateType ?? "",
+            priorityLabel: issue.priority ?? "",
+            assignee: issue.assignee,
+            team: issue.source,
+            labels: issue.labels,
+            createdAt: issue.createdAt,
+            updatedAt: issue.updatedAt
+          }));
+          if (factoryProjectId && options.hooks?.ingestLinearIssues) {
+            await options.hooks.ingestLinearIssues({
+              orgId: resolved.tenant.orgId,
+              userId: resolved.tenant.userId,
+              factoryProjectId,
+              issues: issuePayload
+            });
+          }
+          return c.json({ issues: issuePayload, nextCursor });
+        } catch (err) {
+          return linearFetchError(loose(c), err);
+        }
+      }
+    })
+  );
+  return routes;
+}
+
+// src/integrations/linear/integration.ts
+var LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+var LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
+var LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+var LINEAR_ISSUES_PAGE_SIZE = 30;
+var ISSUE_COMMENTS_PAGE_SIZE = 50;
+var ISSUE_COMMENTS_MAX_PAGES = 20;
+var TOKEN_REFRESH_SKEW_MS = 6e4;
+var CONNECTION_TTL_MS = 6e4;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var LinearReauthRequiredError = class extends Error {
+  constructor() {
+    super("Linear authorization expired. Reconnect Linear to keep syncing intake issues.");
+  }
+};
+async function linearGraphql(accessToken, query, variables) {
+  const res = await fetch(LINEAR_GRAPHQL_URL, {
+    method: "POST",
+    signal: AbortSignal.timeout(15e3),
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${accessToken}`
+    },
+    body: JSON.stringify({ query, variables })
+  });
+  if (!res.ok) {
+    let detail = null;
+    try {
+      const errBody = await res.json();
+      detail = errBody.errors?.[0]?.message ?? null;
+    } catch {
+    }
+    const err = new Error(`Linear API request failed (${res.status})${detail ? `: ${detail}` : ""}`);
+    err.status = res.status;
+    throw err;
+  }
+  const body = await res.json();
+  if (body.errors?.length) {
+    throw new Error(`Linear API error: ${body.errors[0]?.message ?? "unknown error"}`);
+  }
+  if (!body.data) {
+    throw new Error("Linear API returned no data.");
+  }
+  return body.data;
+}
+var LinearIntegration = class {
+  /** Stable integration identifier (see `../base.ts`). */
+  id = "linear";
+  /** Bound once by the factory via `initialize()` before any surface is used. */
+  #storage;
+  #projects;
+  #auth;
+  /** Bind Linear's slice of the generic integration storage, the projects domain, and the host auth seam. */
+  initialize({
+    storage,
+    projects,
+    auth
+  }) {
+    this.#storage = storage;
+    this.#projects = projects;
+    this.#auth = auth;
+  }
+  get storage() {
+    if (!this.#storage) {
+      throw new Error("LinearIntegration is not initialized \u2014 the factory binds storage during prepare().");
+    }
+    return this.#storage;
+  }
+  /** Factory projects domain — maps a session's resourceId to its owning org. */
+  get projects() {
+    if (!this.#projects) {
+      throw new Error("LinearIntegration is not initialized \u2014 the factory binds storage during prepare().");
+    }
+    return this.#projects;
+  }
+  /**
+   * Whether the host runs with web auth enabled. Linear connections are
+   * org-owned, so every Linear surface is inert without a tenant auth seam.
+   */
+  get authEnabled() {
+    return this.#auth?.enabled() ?? false;
+  }
+  // ── Connection + OAuth token lifecycle ───────────────────────────────────
+  /** Load the org's Linear connection, or `null` when not connected. */
+  async loadConnection(orgId) {
+    const connection = await this.storage.connections.get(orgId);
+    if (!connection) return null;
+    const { data } = connection;
+    return {
+      id: connection.id,
+      orgId: connection.orgId,
+      userId: connection.userId,
+      accessToken: data.accessToken,
+      scope: data.scope ?? null,
+      refreshToken: data.refreshToken ?? null,
+      expiresAt: data.expiresAtMs === null || data.expiresAtMs === void 0 ? null : new Date(data.expiresAtMs),
+      workspaceName: data.workspaceName ?? null,
+      workspaceUrlKey: data.workspaceUrlKey ?? null,
+      createdAt: connection.createdAt,
+      updatedAt: connection.updatedAt
+    };
+  }
+  /** Insert or replace the org's connection (one per org). */
+  async upsertConnection(input) {
+    await this.storage.connections.upsert(input.orgId, {
+      userId: input.userId,
+      data: {
+        accessToken: input.accessToken,
+        refreshToken: input.refreshToken,
+        expiresAtMs: input.expiresAt?.getTime() ?? null,
+        scope: input.scope,
+        workspaceName: input.workspaceName,
+        workspaceUrlKey: input.workspaceUrlKey
+      }
+    });
+    this.invalidateConnectionCache(input.orgId);
+  }
+  /** Persist a rotated token set on the org's existing connection row. */
+  async #updateTokens(orgId, tokens) {
+    await this.storage.connections.update(orgId, (data) => ({
+      ...data,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAtMs: tokens.expiresAt?.getTime() ?? null,
+      // Refresh responses may omit scope; keep the recorded grant.
+      scope: tokens.scope ?? data.scope
+    }));
+  }
+  /**
+   * Whether the connection's token can post issue comments. Legacy rows
+   * without a recorded scope were minted with `read` only, so they count as
+   * read-only until the org reconnects Linear.
+   */
+  canPostComments(connection) {
+    const scopes = (connection.scope ?? "").split(/[\s,]+/).filter(Boolean);
+    return scopes.some((scope) => scope === "comments:create" || scope === "write" || scope === "admin");
+  }
+  /**
+   * In-flight refreshes keyed by org. Linear rotates refresh tokens, so two
+   * concurrent refreshes with the same token would invalidate each other —
+   * single-flight ensures one exchange per org and shares the result.
+   */
+  #inflightRefreshes = /* @__PURE__ */ new Map();
+  /**
+   * Return a usable access token for the connection, proactively refreshing
+   * it when the recorded expiry is past (or imminent). Throws
+   * `LinearReauthRequiredError` when the token is expired and cannot be
+   * refreshed — the org has to go through the OAuth flow again.
+   */
+  async getFreshAccessToken(connection) {
+    const expired = connection.expiresAt !== null && connection.expiresAt.getTime() - TOKEN_REFRESH_SKEW_MS <= Date.now();
+    if (!expired) return connection.accessToken;
+    if (!connection.refreshToken) {
+      throw new LinearReauthRequiredError();
+    }
+    const existing = this.#inflightRefreshes.get(connection.orgId);
+    if (existing) return existing;
+    const latest = await this.loadConnection(connection.orgId);
+    if (!latest) throw new LinearReauthRequiredError();
+    const concurrent = this.#inflightRefreshes.get(connection.orgId);
+    if (concurrent) return concurrent;
+    const latestExpired = latest.expiresAt !== null && latest.expiresAt.getTime() - TOKEN_REFRESH_SKEW_MS <= Date.now();
+    if (!latestExpired) return latest.accessToken;
+    if (!latest.refreshToken) throw new LinearReauthRequiredError();
+    const refreshToken = latest.refreshToken;
+    const refresh = (async () => {
+      try {
+        const tokens = await this.refreshAccessToken(refreshToken);
+        await this.#updateTokens(connection.orgId, tokens);
+        return tokens.accessToken;
+      } catch (err) {
+        const status = err.status;
+        if (status === 400 || status === 401) throw new LinearReauthRequiredError();
+        throw err;
+      } finally {
+        this.#inflightRefreshes.delete(connection.orgId);
+      }
+    })();
+    this.#inflightRefreshes.set(connection.orgId, refresh);
+    return refresh;
+  }
+  // ── Connection checks for agent tools ────────────────────────────────────
+  /** Re-check an org's Linear connection (and its scopes) at most this often. */
+  #connectionChecks = /* @__PURE__ */ new Map();
+  /**
+   * Whether the org has an active connection and whether its granted scope
+   * allows posting comments. Cached per org with a short TTL — tool-set
+   * resolution runs on every request.
+   */
+  async checkConnection(orgId) {
+    const cached = this.#connectionChecks.get(orgId);
+    if (cached && Date.now() - cached.checkedAt < CONNECTION_TTL_MS) return cached;
+    const connection = await this.loadConnection(orgId);
+    const check = {
+      connected: connection !== null,
+      canComment: connection !== null && this.canPostComments(connection),
+      checkedAt: Date.now()
+    };
+    this.#connectionChecks.set(orgId, check);
+    return check;
+  }
+  /**
+   * Drop the cached connection check for an org. Called after a connection is
+   * persisted so the tools show up on the very next run instead of after the
+   * TTL lapses.
+   */
+  invalidateConnectionCache(orgId) {
+    this.#connectionChecks.delete(orgId);
+  }
+  /**
+   * A project's org never changes, so the resourceId → orgId mapping is
+   * cached forever. `null` marks resource ids that aren't factory projects
+   * (e.g. local default resources) so we don't re-query them on every
+   * tool-set resolution.
+   */
+  #orgIdByResourceId = /* @__PURE__ */ new Map();
+  /** Map a session's resourceId to its owning org, or `null` when it isn't a project. */
+  async resolveOrgId(resourceId) {
+    const cached = this.#orgIdByResourceId.get(resourceId);
+    if (cached !== void 0) return cached;
+    if (!UUID_PATTERN.test(resourceId)) {
+      this.#orgIdByResourceId.set(resourceId, null);
+      return null;
+    }
+    let orgId;
+    try {
+      await this.projects.ensureReady();
+      const project = await this.projects.getById({ id: resourceId });
+      orgId = project?.orgId ?? null;
+    } catch {
+      return null;
+    }
+    this.#orgIdByResourceId.set(resourceId, orgId);
+    return orgId;
+  }
+  /** Test hook: clear the org/connection caches between specs. */
+  clearCaches() {
+    this.#orgIdByResourceId.clear();
+    this.#connectionChecks.clear();
+  }
+  intake = {
+    listSources: async ({ orgId }) => {
+      const connection = await this.loadConnection(orgId);
+      if (!connection) return [];
+      const accessToken = await this.getFreshAccessToken(connection);
+      const projects = await this.listProjects(accessToken);
+      return projects.map((project) => ({
+        id: project.id,
+        name: project.name,
+        type: "project"
+      }));
+    },
+    listItems: async ({ orgId, sourceIds, cursor }) => {
+      if (sourceIds.length === 0) return { items: [], nextCursor: null };
+      const connection = await this.loadConnection(orgId);
+      if (!connection) return { items: [], nextCursor: null };
+      const accessToken = await this.getFreshAccessToken(connection);
+      const page = await this.listActiveIssues(accessToken, cursor, sourceIds);
+      return {
+        items: page.issues.map((issue) => ({
+          source: { type: "issue", externalId: issue.id, url: issue.url },
+          sourceId: issue.projectId,
+          title: `${issue.identifier}: ${issue.title}`,
+          status: issue.state,
+          labels: issue.labels,
+          assignee: issue.assignee,
+          createdAt: issue.createdAt,
+          updatedAt: issue.updatedAt,
+          metadata: {
+            identifier: issue.identifier,
+            stateType: issue.stateType,
+            priority: issue.priorityLabel,
+            team: issue.team
+          }
+        })),
+        nextCursor: page.nextCursor
+      };
+    },
+    listIssues: (input) => this.#listIntakeIssues(input),
+    getIssue: (input) => this.#getIntakeIssue(input),
+    createComment: (input) => this.#createIntakeComment(input)
+  };
+  /**
+   * The OAuth connect/callback flow round-trips a signed `state` through
+   * Linear, so a multi-replica deploy needs a deployment-stable state secret.
+   */
+  requiresStableStateSigner = true;
+  #clientId;
+  #clientSecret;
+  constructor(config) {
+    const missing = ["clientId", "clientSecret"].filter((key) => !config[key]);
+    if (missing.length > 0) {
+      throw new Error(`LinearIntegration is missing required config: ${missing.join(", ")}.`);
+    }
+    this.#clientId = config.clientId;
+    this.#clientSecret = config.clientSecret;
+  }
+  // ── OAuth ────────────────────────────────────────────────────────────────
+  /**
+   * Build the OAuth authorize URL. `prompt=consent` forces the workspace
+   * picker even for an already-authorized user, so "reconnect" can switch
+   * workspaces.
+   */
+  buildAuthorizeUrl(state, redirectUri) {
+    const url = new URL(LINEAR_AUTHORIZE_URL);
+    url.searchParams.set("client_id", this.#clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", "read,comments:create");
+    url.searchParams.set("state", state);
+    url.searchParams.set("prompt", "consent");
+    return url.toString();
+  }
+  /** Exchange an OAuth `code` for a workspace-scoped token set. */
+  async exchangeOAuthCode(code, redirectUri) {
+    return this.#requestTokens({ grant_type: "authorization_code", code, redirect_uri: redirectUri }, "token exchange");
+  }
+  /**
+   * Exchange a refresh token for a new token set. Linear rotates refresh
+   * tokens, so the returned set replaces the stored one entirely. A 400/401
+   * here means the refresh token is invalid/revoked and the org must
+   * re-authorize.
+   */
+  async refreshAccessToken(refreshToken) {
+    return this.#requestTokens({ grant_type: "refresh_token", refresh_token: refreshToken }, "token refresh");
+  }
+  /** POST to Linear's token endpoint and normalize the response. */
+  async #requestTokens(params, label) {
+    const res = await fetch(LINEAR_TOKEN_URL, {
+      method: "POST",
+      signal: AbortSignal.timeout(1e4),
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        ...params,
+        client_id: this.#clientId,
+        client_secret: this.#clientSecret
+      })
+    });
+    if (!res.ok) {
+      const err = new Error(`Linear ${label} failed (${res.status})`);
+      err.status = res.status;
+      throw err;
+    }
+    const body = await res.json();
+    if (!body.access_token) {
+      throw new Error(`Linear ${label} returned no access token.`);
+    }
+    return {
+      accessToken: body.access_token,
+      refreshToken: body.refresh_token ?? null,
+      expiresAt: typeof body.expires_in === "number" ? new Date(Date.now() + body.expires_in * 1e3) : null,
+      scope: body.scope ?? null
+    };
+  }
+  // ── GraphQL reads/writes ─────────────────────────────────────────────────
+  /** Fetch the workspace (organization) the access token is scoped to. */
+  async fetchWorkspace(accessToken) {
+    const data = await linearGraphql(
+      accessToken,
+      `query { organization { name urlKey } }`
+    );
+    return { name: data.organization.name, urlKey: data.organization.urlKey };
+  }
+  async #listIntakeIssues(input) {
+    const accessToken = getLinearAccessToken(input.connection);
+    const result = await this.listActiveIssues(accessToken, input.cursor, input.sourceIds, input.labels);
+    return {
+      issues: result.issues.map((issue) => linearIssueToIntakeIssue(issue)),
+      nextCursor: result.nextCursor
+    };
+  }
+  async #getIntakeIssue(input) {
+    const accessToken = getLinearAccessToken(input.connection);
+    const issue = await this.fetchIssueDetail(accessToken, input.issueId);
+    if (!issue) return null;
+    return {
+      ...linearIssueToIntakeIssue(issue),
+      description: issue.description,
+      commentCount: issue.comments.length,
+      comments: issue.comments
+    };
+  }
+  async #createIntakeComment(input) {
+    const accessToken = getLinearAccessToken(input.connection);
+    return this.createIssueComment(accessToken, input.issueId, input.body);
+  }
+  /** List the workspace's projects (for the Settings intake-source picker). */
+  async listProjects(accessToken) {
+    const data = await linearGraphql(
+      accessToken,
+      `query { projects(first: 100) { nodes { id name state teams(first: 10) { nodes { id key name } } } } }`
+    );
+    return data.projects.nodes.map((node) => ({
+      id: node.id,
+      name: node.name,
+      state: node.state,
+      teams: node.teams.nodes.map((team) => ({ id: team.id, key: team.key, name: team.name }))
+    }));
+  }
+  /**
+   * List one page of the workspace's active issues (triage/backlog/unstarted/
+   * started — completed and canceled are excluded), most recently updated
+   * first. When `projectIds` is provided, only issues from those projects are
+   * returned.
+   */
+  async listActiveIssues(accessToken, after, projectIds, labels) {
+    const normalizedLabels = [...new Set((labels ?? []).map((label) => label.trim()).filter(Boolean))];
+    const projectFilter = projectIds?.length ? ", project: { id: { in: $projectIds } }" : "";
+    const projectVar = projectIds?.length ? ", $projectIds: [ID!]" : "";
+    const labelFilter = normalizedLabels.length > 0 ? ", labels: { name: { in: $labels } }" : "";
+    const labelVar = normalizedLabels.length > 0 ? ", $labels: [String!]" : "";
+    const data = await linearGraphql(
+      accessToken,
+      `query Intake($first: Int!, $after: String${projectVar}${labelVar}) {
+        issues(
+          first: $first
+          after: $after
+          orderBy: updatedAt
+          filter: { state: { type: { in: ["triage", "backlog", "unstarted", "started"] } }${projectFilter}${labelFilter} }
+        ) {
+          nodes {
+            id
+            identifier
+            title
+            url
+            priorityLabel
+            createdAt
+            updatedAt
+            state { name type }
+            project { id }
+            assignee { name }
+            team { key }
+            labels { nodes { name } }
+          }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`,
+      {
+        first: LINEAR_ISSUES_PAGE_SIZE,
+        after: after ?? null,
+        ...projectIds?.length ? { projectIds } : {},
+        ...normalizedLabels.length > 0 ? { labels: normalizedLabels } : {}
+      }
+    );
+    const { nodes, pageInfo } = data.issues;
+    return {
+      issues: nodes.map((node) => ({
+        id: node.id,
+        projectId: node.project.id,
+        identifier: node.identifier,
+        title: node.title,
+        url: node.url,
+        state: node.state.name,
+        stateType: node.state.type,
+        priorityLabel: node.priorityLabel,
+        assignee: node.assignee?.name ?? null,
+        team: node.team?.key ?? null,
+        labels: node.labels.nodes.map((label) => label.name),
+        createdAt: node.createdAt,
+        updatedAt: node.updatedAt
+      })),
+      nextCursor: pageInfo.hasNextPage ? pageInfo.endCursor : null
+    };
+  }
+  /** Follow `comments.pageInfo` until exhausted so long discussions aren't truncated. */
+  async #fetchRemainingIssueComments(accessToken, issueId, firstPage) {
+    const nodes = [...firstPage.nodes];
+    let { hasNextPage, endCursor } = firstPage.pageInfo;
+    for (let page = 1; hasNextPage && endCursor && page < ISSUE_COMMENTS_MAX_PAGES; page++) {
+      const data = await linearGraphql(
+        accessToken,
+        `query IssueComments($id: String!, $first: Int!, $after: String!) {
+          issue(id: $id) {
+            comments(first: $first, after: $after) {
+              nodes { body createdAt user { name } }
+              pageInfo { hasNextPage endCursor }
+            }
+          }
+        }`,
+        { id: issueId, first: ISSUE_COMMENTS_PAGE_SIZE, after: endCursor }
+      );
+      const comments = data.issue?.comments;
+      if (!comments) break;
+      nodes.push(...comments.nodes);
+      ({ hasNextPage, endCursor } = comments.pageInfo);
+    }
+    return nodes;
+  }
+  /**
+   * Fetch one issue with its description and comments. `idOrIdentifier`
+   * accepts both the Linear UUID and the human key (`ENG-123`). Returns
+   * `null` when the issue doesn't exist (Linear reports it as an "Entity not
+   * found" error).
+   */
+  async fetchIssueDetail(accessToken, idOrIdentifier) {
+    let data;
+    try {
+      data = await linearGraphql(
+        accessToken,
+        `query IssueDetail($id: String!, $commentsFirst: Int!) {
+          issue(id: $id) {
+            id
+            identifier
+            title
+            description
+            url
+            priorityLabel
+            createdAt
+            updatedAt
+            state { name type }
+            project { id }
+            assignee { name }
+            team { key }
+            labels { nodes { name } }
+            comments(first: $commentsFirst) {
+              nodes { body createdAt user { name } }
+              pageInfo { hasNextPage endCursor }
+            }
+          }
+        }`,
+        { id: idOrIdentifier, commentsFirst: ISSUE_COMMENTS_PAGE_SIZE }
+      );
+    } catch (err) {
+      if (err instanceof Error && /entity not found/i.test(err.message)) return null;
+      throw err;
+    }
+    const issue = data.issue;
+    if (!issue) return null;
+    const allComments = await this.#fetchRemainingIssueComments(accessToken, issue.id, issue.comments);
+    const comments = allComments.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+    return {
+      id: issue.id,
+      projectId: issue.project.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      description: issue.description?.trim() ? issue.description : null,
+      url: issue.url,
+      state: issue.state.name,
+      stateType: issue.state.type,
+      priorityLabel: issue.priorityLabel,
+      assignee: issue.assignee?.name ?? null,
+      team: issue.team?.key ?? null,
+      labels: issue.labels.nodes.map((label) => label.name),
+      createdAt: issue.createdAt,
+      updatedAt: issue.updatedAt,
+      comments: comments.map((comment) => ({
+        author: comment.user?.name ?? null,
+        body: comment.body,
+        createdAt: comment.createdAt
+      }))
+    };
+  }
+  /**
+   * Post a comment on an issue. `idOrIdentifier` accepts both the Linear UUID
+   * and the human key (`ENG-123`) — the identifier is resolved to a UUID
+   * first because `commentCreate` only accepts UUIDs. Returns `null` when the
+   * issue doesn't exist.
+   */
+  async createIssueComment(accessToken, idOrIdentifier, body) {
+    let issueId;
+    try {
+      const data2 = await linearGraphql(
+        accessToken,
+        `query IssueId($id: String!) { issue(id: $id) { id } }`,
+        { id: idOrIdentifier }
+      );
+      if (!data2.issue) return null;
+      issueId = data2.issue.id;
+    } catch (err) {
+      if (err instanceof Error && /entity not found/i.test(err.message)) return null;
+      throw err;
+    }
+    const data = await linearGraphql(
+      accessToken,
+      `mutation CommentCreate($input: CommentCreateInput!) {
+        commentCreate(input: $input) { success comment { id url } }
+      }`,
+      { input: { issueId, body } }
+    );
+    if (!data.commentCreate.success || !data.commentCreate.comment) {
+      throw new Error("Linear did not accept the comment.");
+    }
+    return data.commentCreate.comment;
+  }
+  // ── FactoryIntegration surface ───────────────────────────────────────────
+  /**
+   * The integration's HTTP surface: `/web/linear/*` + `/auth/linear/*` Mastra
+   * `apiRoutes` (status, OAuth connect/callback, projects + issues for
+   * Intake). Handlers operate on this instance.
+   */
+  routes(ctx) {
+    return buildLinearRoutes({
+      linear: this,
+      auth: ctx.auth,
+      stateSigner: ctx.stateSigner,
+      baseUrl: ctx.baseUrl,
+      intake: ctx.storage.intake,
+      hooks: ctx.hooks
+    });
+  }
+  /**
+   * Org-scoped agent tools: issue detail + comment tools for sessions whose
+   * project belongs to an org with an active Linear connection.
+   */
+  async agentTools(args) {
+    return buildLinearAgentTools({ requestContext: args.requestContext, linear: this });
+  }
+  /** Non-secret config snapshot for system diagnostics/startup logs. */
+  diagnostics() {
+    return {
+      oauthAppConfigured: true
+    };
+  }
+};
+function getLinearAccessToken(connection) {
+  if (connection.type !== "oauth") {
+    throw new Error("Linear capabilities require an OAuth connection.");
+  }
+  return connection.accessToken;
+}
+function linearIssueToIntakeIssue(issue) {
+  return {
+    id: issue.id,
+    identifier: issue.identifier,
+    title: issue.title,
+    url: issue.url,
+    author: null,
+    state: issue.state,
+    stateType: issue.stateType,
+    priority: issue.priorityLabel,
+    assignee: issue.assignee,
+    source: issue.team,
+    labels: issue.labels,
+    commentCount: null,
+    createdAt: issue.createdAt,
+    updatedAt: issue.updatedAt
+  };
+}
+export {
+  LinearIntegration,
+  LinearReauthRequiredError
+};
+//# sourceMappingURL=integration.js.map