@meetopenbot/linear 0.0.2 → 0.0.4

package/README.md

@@ -1,79 +1,36 @@
 # @meetopenbot/linear
 
-Connect [Linear](https://linear.app) to OpenBot. OAuth for setup, MCP-backed agent for issues, projects, and comments.
+Linear specialist agent for OpenBot: MCP-backed issue, project, and comment management.
 
-## Features
+## Features (MVP)
 
-- **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.
+- **Agent** — OpenAI + Linear's official MCP (`https://mcp.linear.app/mcp`)
+- **Auth** — personal API key via plugin config or `LINEAR_API_KEY` secret
 
-## Install
+## Setup
 
-Install from the OpenBot plugin settings (package name `@meetopenbot/linear`), or add it to an agent's `AGENT.md`:
+1. Create a personal API key at [Linear → Settings → API](https://linear.app/settings/api).
+
+2. Add the plugin to your agent's `AGENT.md`:
 
 ```yaml
 plugins:
-  - id: '@meetopenbot/linear'
+  - id: "@meetopenbot/linear"
     config:
-      clientId: 'your-linear-oauth-client-id'
-      openaiApiKey: 'your-openai-api-key'
+      apiKey: lin_api_your_key_here
+      authMode: credits
+      model: openai/gpt-4o-mini
 ```
 
-## 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
+On cloud, `authMode: credits` uses your workspace credit balance. For BYOK (bring your own key), set `authMode: byok` and add `OPENAI_API_KEY` under workspace settings.
 
-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)
+You can also store the API key as a secret workspace variable named `LINEAR_API_KEY` instead of putting it in plugin config.
 
-## Development
+## Build
 
 ```bash
 npm install
-npm run build   # emits dist/ (the runtime loads dist/index.js)
+npm run build
 ```
 
-For local testing, copy or link the package into `~/.openbot/plugins/@meetopenbot/linear/` and attach it to an agent.
+Restart the OpenBot runtime to load the plugin.

package/dist/cloud-mode.js

@@ -0,0 +1,10 @@
+/** True when this runtime is a platform-managed cloud deployment. */
+export const isCloudMode = () => process.env.OPENBOT_CLOUD_MODE === "1";
+/** Default auth mode: Credits on cloud, BYOK locally. */
+export const defaultAuthMode = () => isCloudMode() ? "credits" : "byok";
+export function resolveAuthMode(config) {
+    if (config.authMode === "byok" || config.authMode === "credits") {
+        return config.authMode;
+    }
+    return defaultAuthMode();
+}

package/dist/config.js

@@ -1,10 +1,5 @@
-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;
+import { resolveAuthMode } from "./cloud-mode.js";
+import { shouldUseCreditsAuth } from "./credits-auth.js";
 function variableValue(variables, key) {
     const entry = variables[key];
     if (typeof entry === "string")
@@ -13,79 +8,35 @@ function variableValue(variables, key) {
 }
 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,
+        authMode: resolveAuthMode(config),
         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) {
+export function formatMissingCredentials(missing, authMode) {
     const lines = [
-        "Linear agent setup is incomplete. Configure the following in plugin config or environment variables:",
+        "Linear agent setup is incomplete. Configure the following in plugin config, workspace settings, or environment variables:",
     ];
-    if (missing.includes("accessToken")) {
-        lines.push("- Connect Linear with `linear_connect`, or set `apiKey` / `LINEAR_API_KEY`");
+    if (missing.includes("apiKey")) {
+        lines.push("- `apiKey` / `LINEAR_API_KEY` — Linear personal API key (Settings → Account → Security & Access → Personal API keys)");
     }
     if (missing.includes("openaiApiKey")) {
-        lines.push("- `openaiApiKey` / `OPENAI_API_KEY` — OpenAI API key for the agent loop");
+        if (authMode === "credits") {
+            lines.push("- OpenAI API key is required in BYOK mode — add `OPENAI_API_KEY` under workspace settings, or switch `authMode` to `credits` on cloud");
+        }
+        else {
+            lines.push("- `OPENAI_API_KEY` — OpenAI API key for the agent loop (BYOK mode), or switch `authMode` to `credits` on cloud");
+        }
     }
     return lines.join("\n");
 }
-export async function resolveLinearCredentials(config, storage, options) {
-    const requireOpenAi = options?.requireOpenAi ?? true;
+export async function resolveLinearCredentials(config, storage) {
+    const authMode = config.authMode ?? resolveAuthMode({});
+    const useCredits = shouldUseCreditsAuth({ authMode });
     const variables = (await storage.getVariables().catch(() => ({})));
     const resolve = (configKey, envKey) => {
         const fromConfig = config[configKey];
@@ -96,45 +47,14 @@ export async function resolveLinearCredentials(config, storage, options) {
             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 apiKey = resolve("apiKey", "LINEAR_API_KEY");
+    const openaiApiKey = process.env.OPENAI_API_KEY?.trim() ||
+        variableValue(variables, "OPENAI_API_KEY");
+    const model = resolve("model", "OPENAI_MODEL") ?? "openai/gpt-4o-mini";
     const missing = [];
-    if (!accessToken)
-        missing.push("accessToken");
-    if (requireOpenAi && !openaiApiKey)
+    if (!apiKey)
+        missing.push("apiKey");
+    if (!useCredits && !openaiApiKey)
         missing.push("openaiApiKey");
     if (missing.length > 0) {
         return { ok: false, missing };
@@ -142,11 +62,10 @@ export async function resolveLinearCredentials(config, storage, options) {
     return {
         ok: true,
         credentials: {
-            accessToken: accessToken,
-            openaiApiKey: openaiApiKey ?? "",
+            apiKey: apiKey,
+            authMode,
+            openaiApiKey: openaiApiKey || undefined,
             model,
-            clientId,
-            clientSecret,
         },
     };
 }

package/dist/credits-auth.js

@@ -0,0 +1,53 @@
+import { isCloudMode } from "./cloud-mode.js";
+export const INTEGRATIONS_TOKEN_HEADER = "x-openbot-integrations-token";
+export const CREDITS_API_KEY_PLACEHOLDER = "openbot-credits";
+/** Cloud host injects these when routing LLM calls through OpenBot Credits. */
+export function resolveCreditsAuthConfig() {
+    const baseUrl = process.env.OPENBOT_INTEGRATIONS_BASE_URL?.trim();
+    const token = process.env.OPENBOT_INTEGRATIONS_TOKEN?.trim();
+    if (!baseUrl || !token)
+        return undefined;
+    return { baseUrl: baseUrl.replace(/\/$/, ""), token };
+}
+export function creditsProviderBaseUrl(config) {
+    return `${config.baseUrl}/openai/v1`;
+}
+export function shouldUseCreditsAuth(options) {
+    if (options?.authMode === "byok")
+        return false;
+    if (options?.authMode === "credits")
+        return true;
+    return isCloudMode() && resolveCreditsAuthConfig() !== undefined;
+}
+export function isCreditsErrorMessage(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes("insufficient_credits") ||
+        lower.includes("insufficient credits") ||
+        lower.includes("402"));
+}
+export function isAuthErrorMessage(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes("api key") ||
+        lower.includes("401") ||
+        lower.includes("unauthorized") ||
+        lower.includes("authentication"));
+}
+export function isIntegrationsProviderError(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes("provider api key not configured") ||
+        (lower.includes("503") && lower.includes("provider")));
+}
+export const CREDITS_NOT_CONFIGURED_MESSAGE = "OpenBot Credits is not configured on this runtime. The cloud host must set OPENBOT_INTEGRATIONS_BASE_URL and OPENBOT_INTEGRATIONS_TOKEN (try redeploying the workspace).";
+export const CREDITS_PROVIDER_UNAVAILABLE_MESSAGE = "OpenBot Credits could not reach OpenAI — the platform provider API key is not configured yet. Try again later or switch this agent to BYOK mode.";
+export const CREDITS_AUTH_FAILED_MESSAGE = "Linear could not authenticate via OpenBot Credits. Check your workspace credit balance in settings, or switch this agent to BYOK mode.";
+export function creditsErrorMessage(message) {
+    if (isIntegrationsProviderError(message)) {
+        return CREDITS_PROVIDER_UNAVAILABLE_MESSAGE;
+    }
+    if (isCreditsErrorMessage(message)) {
+        return "Insufficient workspace credits. Add credits in workspace settings or switch this agent to BYOK mode.";
+    }
+    if (isAuthErrorMessage(message))
+        return CREDITS_AUTH_FAILED_MESSAGE;
+    return undefined;
+}