@meetopenbot/linear 0.0.1

package/README.md

@@ -0,0 +1,79 @@
+# @meetopenbot/linear
+
+Connect [Linear](https://linear.app) to OpenBot. OAuth for setup, MCP-backed agent for issues, projects, and comments.
+
+## Features
+
+- **OAuth connect flow** — ask the agent to "connect Linear", click the link, approve in the browser, come back connected. Uses PKCE, so no client secret is required. Tokens are stored as secret workspace variables and refreshed automatically.
+- **API key fallback** — paste a personal API key into the plugin config instead.
+- **MCP agent** — `agent:invoke` runs an OpenAI agent loop with Linear MCP tools (`mcp-server-linear`) for dynamic issue/project management.
+- **Connect tools** — `linear_connect` / `linear_disconnect` for chat-driven OAuth.
+
+## Install
+
+Install from the OpenBot plugin settings (package name `@meetopenbot/linear`), or add it to an agent's `AGENT.md`:
+
+```yaml
+plugins:
+  - id: '@meetopenbot/linear'
+    config:
+      clientId: 'your-linear-oauth-client-id'
+      openaiApiKey: 'your-openai-api-key'
+```
+
+## Auth setup
+
+### Option A — Install-time OAuth from openbot.one (recommended)
+
+Install the plugin from **openbot.one → Settings → Plugins**. After the install completes you're redirected to Linear's consent screen; approve, and you land back on the plugins page connected.
+
+### Option B — Webhook OAuth (cloud / remote runtime)
+
+1. In Linear, create an OAuth application at **Settings → API → OAuth applications**.
+2. Set the callback URL to `https://<your-host>/api/webhooks/linear`.
+3. Register this plugin on your webhook agent (usually `system`) in `AGENT.md`.
+4. Set `webhookBaseUrl` in plugin config to `https://<your-host>` (or rely on the runtime's `publicBaseUrl` if provided).
+5. Run `linear_connect` and approve in the browser.
+
+> **Note:** the runtime must forward OAuth browser redirects (GET with `?code=` / `?state=`) to `POST /api/webhooks/linear` as `action:webhook` with query params in `event.data.query`.
+
+### Option C — Chat-driven OAuth (local loopback)
+
+1. In Linear, go to **Settings → API → OAuth applications** and create an application.
+2. Set the callback URL to `http://localhost:4137/oauth/callback` (or your configured `oauthPort`).
+3. Put the application's **Client ID** into the plugin's `clientId` config field.
+4. Ask the agent to *"connect Linear"*. It runs `linear_connect`, shows an authorization link, and confirms once you approve in the browser.
+
+> **Note:** loopback only works when the browser can reach the runtime on `localhost:<oauthPort>`.
+
+### Option D — API key
+
+Create a personal API key at **Linear → Settings → API** and either put it in the plugin's `apiKey` config field or save it as a secret workspace variable named `LINEAR_API_KEY`.
+
+## Config
+
+| Field | Description | Default |
+| --- | --- | --- |
+| `clientId` | Linear OAuth application Client ID | — |
+| `clientSecret` | OAuth Client Secret (optional; PKCE used when omitted) | — |
+| `apiKey` | Personal API key (skips OAuth entirely) | — |
+| `oauthPort` | Local port for the OAuth callback server | `4137` |
+| `scopes` | Comma-separated OAuth scopes | `read,write,issues:create,comments:create` |
+| `webhookBaseUrl` | Public base URL for OAuth callback (`/api/webhooks/linear`) | — |
+| `openaiApiKey` | OpenAI API key for the MCP agent loop | — |
+| `model` | OpenAI model id | `gpt-4o-mini` |
+
+## Credential resolution order
+
+1. `apiKey` from plugin config
+2. `LINEAR_API_KEY` workspace variable / env
+3. `LINEAR_ACCESS_TOKEN` OAuth token (auto-refreshed via `LINEAR_REFRESH_TOKEN`, using `clientId` from config or the `LINEAR_CLIENT_ID` variable)
+
+## Development
+
+```bash
+npm install
+npm run build   # emits dist/ (the runtime loads dist/index.js)
+```
+
+For local testing, copy or link the package into `~/.openbot/plugins/@meetopenbot/linear/` and attach it to an agent.

package/dist/api.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal Linear GraphQL helpers used by the OAuth connect flow.
+ */
+export declare const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+export declare function fetchViewer(accessToken: string): Promise<{
+    viewer: {
+        id: string;
+        name: string;
+        displayName: string;
+        email: string;
+    };
+    organization: {
+        id: string;
+        name: string;
+        urlKey: string;
+    };
+}>;

package/dist/api.js

@@ -0,0 +1,29 @@
+/**
+ * Minimal Linear GraphQL helpers used by the OAuth connect flow.
+ */
+export const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+async function linearGraphql(accessToken, query, variables) {
+    const response = await fetch(LINEAR_GRAPHQL_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${accessToken}`,
+        },
+        body: JSON.stringify({ query, variables }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Linear API request failed (${response.status}): ${body.slice(0, 500)}`);
+    }
+    const payload = (await response.json());
+    if (payload.errors?.length) {
+        throw new Error(payload.errors.map((e) => e.message).join("; "));
+    }
+    if (!payload.data) {
+        throw new Error("Linear API returned no data.");
+    }
+    return payload.data;
+}
+export async function fetchViewer(accessToken) {
+    return linearGraphql(accessToken, `query { viewer { id name displayName email } organization { id name urlKey } }`);
+}

package/dist/auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Credential resolution for the Linear plugin.
+ *
+ * Priority:
+ *   1. `apiKey` in plugin config (AGENT.md) — personal API key.
+ *   2. `LINEAR_API_KEY` workspace variable / env — personal API key.
+ *   3. `LINEAR_ACCESS_TOKEN` workspace variable — OAuth token saved by
+ *      `linear_connect`, refreshed automatically via `LINEAR_REFRESH_TOKEN`.
+ */
+import type { PluginContext } from '@meetopenbot/plugin-sdk';
+import type { LinearAuth } from './api.js';
+import { type OAuthTokens } from './oauth.js';
+export declare const VAR_API_KEY = "LINEAR_API_KEY";
+export declare const VAR_ACCESS_TOKEN = "LINEAR_ACCESS_TOKEN";
+export declare const VAR_REFRESH_TOKEN = "LINEAR_REFRESH_TOKEN";
+export declare const VAR_TOKEN_EXPIRES_AT = "LINEAR_TOKEN_EXPIRES_AT";
+/** Stored by the runtime's install-time OAuth flow; used to refresh tokens. */
+export declare const VAR_CLIENT_ID = "LINEAR_CLIENT_ID";
+export interface LinearPluginConfig {
+    apiKey?: string;
+    clientId?: string;
+    clientSecret?: string;
+    oauthPort?: number;
+    scopes?: string;
+}
+export declare function readConfig(context: PluginContext): LinearPluginConfig;
+export declare function saveTokens(context: PluginContext, tokens: OAuthTokens): Promise<void>;
+export declare function clearTokens(context: PluginContext): Promise<void>;
+export declare class NotConnectedError extends Error {
+    constructor();
+}
+/** Resolve usable Linear credentials, refreshing the OAuth token if needed. */
+export declare function resolveAuth(context: PluginContext): Promise<LinearAuth>;

package/dist/auth.js

@@ -0,0 +1,91 @@
+/**
+ * Credential resolution for the Linear plugin.
+ *
+ * Priority:
+ *   1. `apiKey` in plugin config (AGENT.md) — personal API key.
+ *   2. `LINEAR_API_KEY` workspace variable / env — personal API key.
+ *   3. `LINEAR_ACCESS_TOKEN` workspace variable — OAuth token saved by
+ *      `linear_connect`, refreshed automatically via `LINEAR_REFRESH_TOKEN`.
+ */
+import { refreshAccessToken } from './oauth.js';
+export const VAR_API_KEY = 'LINEAR_API_KEY';
+export const VAR_ACCESS_TOKEN = 'LINEAR_ACCESS_TOKEN';
+export const VAR_REFRESH_TOKEN = 'LINEAR_REFRESH_TOKEN';
+export const VAR_TOKEN_EXPIRES_AT = 'LINEAR_TOKEN_EXPIRES_AT';
+/** Stored by the runtime's install-time OAuth flow; used to refresh tokens. */
+export const VAR_CLIENT_ID = 'LINEAR_CLIENT_ID';
+/** Refresh this long before the reported expiry. */
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+export function readConfig(context) {
+    const config = (context.config ?? {});
+    return {
+        apiKey: typeof config.apiKey === 'string' && config.apiKey.trim() ? config.apiKey.trim() : undefined,
+        clientId: typeof config.clientId === 'string' && config.clientId.trim() ? config.clientId.trim() : undefined,
+        clientSecret: typeof config.clientSecret === 'string' && config.clientSecret.trim() ? config.clientSecret.trim() : undefined,
+        oauthPort: typeof config.oauthPort === 'number' ? config.oauthPort : 4137,
+        scopes: typeof config.scopes === 'string' && config.scopes.trim()
+            ? config.scopes.trim()
+            : 'read,write,issues:create,comments:create',
+    };
+}
+function variableValue(variables, key) {
+    const entry = variables[key];
+    if (typeof entry === 'string')
+        return entry || undefined;
+    return entry?.value || undefined;
+}
+export async function saveTokens(context, tokens) {
+    await context.storage.createVariable({ key: VAR_ACCESS_TOKEN, value: tokens.accessToken, secret: true });
+    if (tokens.refreshToken) {
+        await context.storage.createVariable({ key: VAR_REFRESH_TOKEN, value: tokens.refreshToken, secret: true });
+    }
+    if (tokens.expiresAt) {
+        await context.storage.createVariable({ key: VAR_TOKEN_EXPIRES_AT, value: String(tokens.expiresAt), secret: false });
+    }
+}
+export async function clearTokens(context) {
+    for (const key of [VAR_ACCESS_TOKEN, VAR_REFRESH_TOKEN, VAR_TOKEN_EXPIRES_AT]) {
+        await context.storage.deleteVariable({ key }).catch(() => { });
+    }
+}
+export class NotConnectedError extends Error {
+    constructor() {
+        super('Linear is not connected. Use the `linear_connect` tool to connect with OAuth, or set an API key in the plugin config / LINEAR_API_KEY variable.');
+        this.name = 'NotConnectedError';
+    }
+}
+/** Resolve usable Linear credentials, refreshing the OAuth token if needed. */
+export async function resolveAuth(context) {
+    const config = readConfig(context);
+    if (config.apiKey)
+        return { kind: 'apiKey', token: config.apiKey };
+    const variables = (await context.storage.getVariables().catch(() => ({})));
+    const apiKey = variableValue(variables, VAR_API_KEY) ?? process.env[VAR_API_KEY];
+    if (apiKey)
+        return { kind: 'apiKey', token: apiKey };
+    const accessToken = variableValue(variables, VAR_ACCESS_TOKEN) ?? process.env[VAR_ACCESS_TOKEN];
+    if (!accessToken)
+        throw new NotConnectedError();
+    const expiresAtRaw = variableValue(variables, VAR_TOKEN_EXPIRES_AT) ?? process.env[VAR_TOKEN_EXPIRES_AT];
+    const expiresAt = expiresAtRaw ? Number(expiresAtRaw) : undefined;
+    const refreshToken = variableValue(variables, VAR_REFRESH_TOKEN) ?? process.env[VAR_REFRESH_TOKEN];
+    // Client id from plugin config, or the variable stored by the runtime's
+    // install-time OAuth flow (openbot.one plugins page).
+    const clientId = config.clientId ?? variableValue(variables, VAR_CLIENT_ID) ?? process.env[VAR_CLIENT_ID];
+    const needsRefresh = expiresAt !== undefined && Number.isFinite(expiresAt) && Date.now() > expiresAt - REFRESH_MARGIN_MS;
+    if (needsRefresh && refreshToken && clientId) {
+        try {
+            const tokens = await refreshAccessToken({
+                refreshToken,
+                clientId,
+                clientSecret: config.clientSecret,
+            });
+            await saveTokens(context, tokens);
+            return { kind: 'oauth', token: tokens.accessToken };
+        }
+        catch {
+            // Fall through and try the stored token; a 401 will tell the user to reconnect.
+        }
+    }
+    return { kind: 'oauth', token: accessToken };
+}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import type { Storage } from "@meetopenbot/plugin-sdk";
+import { type OAuthTokens } from "./oauth.js";
+export declare const VAR_API_KEY = "LINEAR_API_KEY";
+export declare const VAR_ACCESS_TOKEN = "LINEAR_ACCESS_TOKEN";
+export declare const VAR_REFRESH_TOKEN = "LINEAR_REFRESH_TOKEN";
+export declare const VAR_TOKEN_EXPIRES_AT = "LINEAR_TOKEN_EXPIRES_AT";
+export declare const VAR_CLIENT_ID = "LINEAR_CLIENT_ID";
+export type LinearPluginConfig = {
+    clientId?: string;
+    clientSecret?: string;
+    apiKey?: string;
+    oauthPort?: number;
+    scopes?: string;
+    openaiApiKey?: string;
+    model?: string;
+    /** Public runtime base URL, e.g. https://my-host.com (used for OAuth webhook callback). */
+    webhookBaseUrl?: string;
+};
+export type LinearCredentials = {
+    accessToken: string;
+    openaiApiKey: string;
+    model: string;
+    clientId?: string;
+    clientSecret?: string;
+};
+export declare function readLinearConfig(config: Record<string, unknown>): LinearPluginConfig;
+export declare function resolveWebhookBaseUrl(config: LinearPluginConfig, publicBaseUrl?: string): string | undefined;
+export declare function saveTokens(storage: Storage, tokens: OAuthTokens): Promise<void>;
+export declare function clearTokens(storage: Storage): Promise<void>;
+export declare function formatMissingCredentials(missing: Array<"accessToken" | "openaiApiKey">): string;
+export declare function resolveLinearCredentials(config: LinearPluginConfig, storage: Storage, options?: {
+    requireOpenAi?: boolean;
+}): Promise<{
+    ok: true;
+    credentials: LinearCredentials;
+} | {
+    ok: false;
+    missing: Array<"accessToken" | "openaiApiKey">;
+}>;

package/dist/config.js

@@ -0,0 +1,152 @@
+import { refreshAccessToken } from "./oauth.js";
+export const VAR_API_KEY = "LINEAR_API_KEY";
+export const VAR_ACCESS_TOKEN = "LINEAR_ACCESS_TOKEN";
+export const VAR_REFRESH_TOKEN = "LINEAR_REFRESH_TOKEN";
+export const VAR_TOKEN_EXPIRES_AT = "LINEAR_TOKEN_EXPIRES_AT";
+export const VAR_CLIENT_ID = "LINEAR_CLIENT_ID";
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+function variableValue(variables, key) {
+    const entry = variables[key];
+    if (typeof entry === "string")
+        return entry || undefined;
+    return entry?.value || undefined;
+}
+export function readLinearConfig(config) {
+    return {
+        clientId: typeof config.clientId === "string" && config.clientId.trim()
+            ? config.clientId.trim()
+            : undefined,
+        clientSecret: typeof config.clientSecret === "string" && config.clientSecret.trim()
+            ? config.clientSecret.trim()
+            : undefined,
+        apiKey: typeof config.apiKey === "string" && config.apiKey.trim()
+            ? config.apiKey.trim()
+            : undefined,
+        oauthPort: typeof config.oauthPort === "number" ? config.oauthPort : 4137,
+        scopes: typeof config.scopes === "string" && config.scopes.trim()
+            ? config.scopes.trim()
+            : "read,write,issues:create,comments:create",
+        openaiApiKey: typeof config.openaiApiKey === "string" && config.openaiApiKey.trim()
+            ? config.openaiApiKey.trim()
+            : undefined,
+        model: typeof config.model === "string" && config.model.trim()
+            ? config.model.trim()
+            : undefined,
+        webhookBaseUrl: typeof config.webhookBaseUrl === "string" && config.webhookBaseUrl.trim()
+            ? config.webhookBaseUrl.trim()
+            : undefined,
+    };
+}
+export function resolveWebhookBaseUrl(config, publicBaseUrl) {
+    const explicit = config.webhookBaseUrl?.replace(/\/$/, "");
+    if (explicit)
+        return explicit;
+    const host = publicBaseUrl?.trim().replace(/\/$/, "");
+    if (host)
+        return host;
+    return undefined;
+}
+export async function saveTokens(storage, tokens) {
+    await storage.createVariable({
+        key: VAR_ACCESS_TOKEN,
+        value: tokens.accessToken,
+        secret: true,
+    });
+    if (tokens.refreshToken) {
+        await storage.createVariable({
+            key: VAR_REFRESH_TOKEN,
+            value: tokens.refreshToken,
+            secret: true,
+        });
+    }
+    if (tokens.expiresAt) {
+        await storage.createVariable({
+            key: VAR_TOKEN_EXPIRES_AT,
+            value: String(tokens.expiresAt),
+            secret: false,
+        });
+    }
+}
+export async function clearTokens(storage) {
+    for (const key of [VAR_ACCESS_TOKEN, VAR_REFRESH_TOKEN, VAR_TOKEN_EXPIRES_AT]) {
+        await storage.deleteVariable({ key }).catch(() => { });
+    }
+}
+export function formatMissingCredentials(missing) {
+    const lines = [
+        "Linear agent setup is incomplete. Configure the following in plugin config or environment variables:",
+    ];
+    if (missing.includes("accessToken")) {
+        lines.push("- Connect Linear with `linear_connect`, or set `apiKey` / `LINEAR_API_KEY`");
+    }
+    if (missing.includes("openaiApiKey")) {
+        lines.push("- `openaiApiKey` / `OPENAI_API_KEY` — OpenAI API key for the agent loop");
+    }
+    return lines.join("\n");
+}
+export async function resolveLinearCredentials(config, storage, options) {
+    const requireOpenAi = options?.requireOpenAi ?? true;
+    const variables = (await storage.getVariables().catch(() => ({})));
+    const resolve = (configKey, envKey) => {
+        const fromConfig = config[configKey];
+        if (typeof fromConfig === "string" && fromConfig.trim()) {
+            return fromConfig.trim();
+        }
+        if (process.env[envKey]?.trim())
+            return process.env[envKey].trim();
+        return variableValue(variables, envKey)?.trim();
+    };
+    const openaiApiKey = resolve("openaiApiKey", "OPENAI_API_KEY");
+    const model = resolve("model", "OPENAI_MODEL") ?? "gpt-4o-mini";
+    let accessToken = config.apiKey ??
+        variableValue(variables, VAR_API_KEY) ??
+        process.env[VAR_API_KEY] ??
+        variableValue(variables, VAR_ACCESS_TOKEN) ??
+        process.env[VAR_ACCESS_TOKEN];
+    const clientId = config.clientId ??
+        variableValue(variables, VAR_CLIENT_ID) ??
+        process.env[VAR_CLIENT_ID];
+    const clientSecret = config.clientSecret;
+    if (accessToken && !config.apiKey) {
+        const expiresAtRaw = variableValue(variables, VAR_TOKEN_EXPIRES_AT) ??
+            process.env[VAR_TOKEN_EXPIRES_AT];
+        const expiresAt = expiresAtRaw ? Number(expiresAtRaw) : undefined;
+        const refreshToken = variableValue(variables, VAR_REFRESH_TOKEN) ??
+            process.env[VAR_REFRESH_TOKEN];
+        const needsRefresh = expiresAt !== undefined &&
+            Number.isFinite(expiresAt) &&
+            Date.now() > expiresAt - REFRESH_MARGIN_MS;
+        if (needsRefresh && refreshToken && clientId) {
+            try {
+                const tokens = await refreshAccessToken({
+                    refreshToken,
+                    clientId,
+                    clientSecret,
+                });
+                await saveTokens(storage, tokens);
+                accessToken = tokens.accessToken;
+            }
+            catch {
+                // Fall through; a 401 from Linear will prompt reconnect.
+            }
+        }
+    }
+    const missing = [];
+    if (!accessToken)
+        missing.push("accessToken");
+    if (requireOpenAi && !openaiApiKey)
+        missing.push("openaiApiKey");
+    if (missing.length > 0) {
+        return { ok: false, missing };
+    }
+    return {
+        ok: true,
+        credentials: {
+            accessToken: accessToken,
+            openaiApiKey: openaiApiKey ?? "",
+            model,
+            clientId,
+            clientSecret,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { type PluginContext, type ToolDefinition } from "@meetopenbot/plugin-sdk";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            clientId: {
+                type: "string";
+                description: string;
+            };
+            clientSecret: {
+                type: "string";
+                description: string;
+                format: "password";
+            };
+            apiKey: {
+                type: "string";
+                description: string;
+                format: "password";
+            };
+            oauthPort: {
+                type: "number";
+                description: string;
+                default: number;
+            };
+            scopes: {
+                type: "string";
+                description: string;
+                default: string;
+            };
+            webhookBaseUrl: {
+                type: "string";
+                description: string;
+                format: "url";
+            };
+            openaiApiKey: {
+                type: "string";
+                description: string;
+                format: "password";
+            };
+            model: {
+                type: "string";
+                description: string;
+                default: string;
+            };
+        };
+    };
+    toolDefinitions: Record<string, ToolDefinition>;
+    factory: (pluginContext: PluginContext) => (builder: import("melony").MelonyBuilder<import("@meetopenbot/plugin-sdk").OpenBotState, import("@meetopenbot/plugin-sdk").OpenBotEvent>) => void;
+};
+export default _default;