@meetopenbot/linear 0.0.2 → 0.0.4

package/dist/index.js

@@ -1,250 +1,42 @@
-import { agentOutput, definePlugin, shouldHandleInvoke, toolResult, uiWidget, webhookHttpResponse, } from "@meetopenbot/plugin-sdk";
-import { clearTokens, formatMissingCredentials, readLinearConfig, resolveLinearCredentials, resolveWebhookBaseUrl, saveTokens, } from "./config.js";
+import { agentOutput, definePlugin, shouldHandleInvoke, uiWidget, } from "@meetopenbot/plugin-sdk";
+import { isCloudMode } from "./cloud-mode.js";
+import { CREDITS_NOT_CONFIGURED_MESSAGE, creditsErrorMessage, resolveCreditsAuthConfig, } from "./credits-auth.js";
+import { formatMissingCredentials, readLinearConfig, resolveLinearCredentials, } from "./config.js";
+import { resolveModelConfigField } from "./model-registry.js";
 import { runLinearAgent } from "./linear-agent.js";
-import { buildIssuesListWidget, isAssignedIssuesPrompt, isListIssuesPrompt, issuesListTitle, } from "./linear-issues.js";
-import { OAUTH_WEBHOOK_PROVIDER, buildOAuthRedirectUri, fetchViewer, handleWebhookOAuthCallback, startOAuthFlow, startWebhookOAuthFlow, } from "./oauth.js";
-/** Client-side action handled by openbot.one — opens `value.url` in the browser. */
-const OPEN_URL_ACTION_ID = "open_url";
-const CONNECT_TOOL = {
-    description: "Connect the workspace to Linear via OAuth. Returns an authorization link the user must open in their browser; after they approve, the token is stored automatically. Use this when Linear is not connected yet or credentials expired.",
-    inputSchema: { type: "object", properties: {} },
-};
-const DISCONNECT_TOOL = {
-    description: "Disconnect Linear: removes the stored OAuth tokens from the workspace.",
-    inputSchema: { type: "object", properties: {} },
-};
-const CONNECT_WAIT_MS = 120 * 1000;
-const CONNECT_WIDGET_ID = "linear-connect";
-const CONNECT_PROMPT_WIDGET_ID = "linear-connect-prompt";
-const toolDefinitions = {
-    linear_connect: CONNECT_TOOL,
-    linear_disconnect: DISCONNECT_TOOL,
-};
-function* emitConnectReply(mode, context, event, data) {
-    if (mode === "tool") {
-        yield toolResult("linear_connect", event, data);
-        return;
-    }
-    yield agentOutput({
-        agentId: context.agentId,
-        content: data.output,
-        threadId: event.meta?.threadId,
-        meta: event.meta,
-    });
-}
-function* yieldOAuthAuthorizeWidget(agentId, authorizeUrl, modeHint, options) {
-    yield uiWidget({
-        agentId,
-        threadId: options.threadId,
-        meta: options.meta,
-        widget: {
-            kind: "message",
-            widgetId: options.widgetId ?? CONNECT_WIDGET_ID,
-            title: "Connect Linear",
-            body: `Open Linear in your browser to authorize OpenBot. ${modeHint}`,
-            actions: [
-                {
-                    id: OPEN_URL_ACTION_ID,
-                    label: "Connect Linear",
-                    variant: "primary",
-                    value: { url: authorizeUrl },
-                },
-            ],
-        },
-    });
-}
-async function createOAuthHandle(context, publicBaseUrl) {
-    const config = readLinearConfig(context.config ?? {});
-    const webhookBaseUrl = resolveWebhookBaseUrl(config, publicBaseUrl);
-    if (config.apiKey || !config.clientId)
-        return null;
-    const scopes = config.scopes ?? "read,write,issues:create,comments:create";
-    const handle = webhookBaseUrl
-        ? await startWebhookOAuthFlow({
-            storage: context.storage,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-            scopes,
-            webhookBaseUrl,
-        })
-        : startOAuthFlow({
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-            port: config.oauthPort ?? 4137,
-            scopes,
-            onSuccess: (tokens) => saveTokens(context.storage, tokens),
-        });
-    const modeHint = webhookBaseUrl
-        ? `After approval, Linear redirects to \`${handle.redirectUri}\`.`
-        : "After you approve access you'll be redirected back and can return here.";
-    return { handle, modeHint };
-}
-function notConnectedMessage(missing) {
-    const needsConnect = missing.includes("accessToken");
-    const needsOpenAi = missing.includes("openaiApiKey");
-    if (needsConnect && needsOpenAi) {
-        return "Linear isn't connected yet, and the OpenAI API key is missing. Connect Linear below, then add `openaiApiKey` to the plugin config.";
-    }
-    if (needsConnect) {
-        return "Linear isn't connected yet. Click **Connect Linear** below to open the authorization page.";
-    }
-    return formatMissingCredentials(missing);
-}
-async function* handleConnect(context, event, publicBaseUrl, replyMode = "tool") {
-    const config = readLinearConfig(context.config ?? {});
-    const threadId = event.meta?.threadId;
-    const webhookBaseUrl = resolveWebhookBaseUrl(config, publicBaseUrl);
-    if (config.apiKey) {
-        yield* emitConnectReply(replyMode, context, event, {
-            output: "Linear is already configured with an API key in the plugin config — no OAuth connection needed.",
-        });
-        return;
-    }
-    const oauth = await createOAuthHandle(context, publicBaseUrl);
-    if (!oauth) {
-        const webhookHint = webhookBaseUrl
-            ? `   set its callback URL to ${buildOAuthRedirectUri(webhookBaseUrl)},`
-            : `   set its callback URL to http://localhost:${config.oauthPort}/oauth/callback (local), or configure webhookBaseUrl for ${buildOAuthRedirectUri("https://<your-host>")},`;
-        yield* emitConnectReply(replyMode, context, event, {
-            output: [
-                "Linear OAuth is not configured. Ways to connect:",
-                "1. Recommended: open the OpenBot web app → Settings → Plugins and click Connect on the Linear plugin (install-time OAuth, no setup needed).",
-                "2. Self-hosted OAuth: create an OAuth application at https://linear.app/settings/api/applications,",
-                webhookHint,
-                "   then put its Client ID into this plugin's `clientId` config field and run linear_connect again.",
-                "3. API key: create a personal API key at https://linear.app/settings/api and put it into the `apiKey` config field (or a LINEAR_API_KEY secret variable).",
-            ].join("\n"),
-        });
-        return;
-    }
-    const { handle, modeHint } = oauth;
-    yield* yieldOAuthAuthorizeWidget(context.agentId, handle.authorizeUrl, modeHint, { threadId, meta: event.meta });
-    const outcome = await Promise.race([
-        handle.completion,
-        new Promise((resolve) => {
-            const t = setTimeout(() => resolve("pending"), CONNECT_WAIT_MS);
-            t.unref?.();
-        }),
-    ]);
-    if (outcome === "pending") {
-        yield* emitConnectReply(replyMode, context, event, {
-            authorizeUrl: handle.authorizeUrl,
-            redirectUri: handle.redirectUri,
-            output: "Authorization link sent. Waiting for the user to approve in the browser — the link stays valid for 10 minutes. Once they confirm, ask me to work with Linear again.",
-        });
-        return;
-    }
-    if (!outcome) {
-        yield* emitConnectReply(replyMode, context, event, {
-            error: "authorization_failed",
-            output: "Linear authorization did not complete (denied, failed, or the callback is unavailable). Run linear_connect to try again.",
-        });
-        return;
-    }
-    let who = "";
-    try {
-        const { viewer, organization } = await fetchViewer(outcome.accessToken);
-        who = ` as ${viewer.displayName ?? viewer.name} in workspace "${organization.name}"`;
-    }
-    catch {
-        // Connection succeeded even if the identity lookup failed.
-    }
-    yield uiWidget({
-        agentId: context.agentId,
-        threadId,
-        widget: {
-            kind: "message",
-            widgetId: CONNECT_WIDGET_ID,
-            title: "Linear connected",
-            body: `✅ Connected to Linear${who}.`,
-            state: "submitted",
-        },
-    });
-    yield* emitConnectReply(replyMode, context, event, {
-        connected: true,
-        output: `Successfully connected to Linear${who}. Tokens are stored securely and refresh automatically.`,
-    });
-}
+import { loadThreadContext } from "./thread-context.js";
+const modelField = await resolveModelConfigField();
 const linearPluginConfigSchema = {
     type: "object",
     properties: {
-        clientId: {
-            type: "string",
-            description: "Linear OAuth application Client ID (create one at linear.app/settings/api/applications)",
-        },
-        clientSecret: {
-            type: "string",
-            description: "Linear OAuth application Client Secret (optional — PKCE is used when omitted)",
-            format: "password",
+        ...(isCloudMode()
+            ? {
+                authMode: {
+                    type: "string",
+                    description: "Credits uses your workspace credit balance via OpenBot. BYOK uses `OPENAI_API_KEY` from workspace settings.",
+                    enum: ["credits", "byok"],
+                    default: "credits",
+                },
+            }
+            : {}),
+        model: {
+            ...modelField,
+            description: "OpenAI model for direct Linear agent invocations",
         },
         apiKey: {
             type: "string",
-            description: "Linear personal API key (alternative to OAuth)",
+            description: "Linear personal API key (Settings → Account → Security & Access → Personal API keys)",
             format: "password",
         },
-        oauthPort: {
-            type: "number",
-            description: "Local port for the OAuth callback (must match the OAuth app callback URL)",
-            default: 4137,
-        },
-        scopes: {
-            type: "string",
-            description: "Comma-separated OAuth scopes",
-            default: "read,write,issues:create,comments:create",
-        },
-        webhookBaseUrl: {
-            type: "string",
-            description: "Public runtime base URL for OAuth callback via /api/webhooks/linear (e.g. https://my-host.com). Falls back to host publicBaseUrl when omitted.",
-            format: "url",
-        },
-        openaiApiKey: {
-            type: "string",
-            description: "OpenAI API key for direct Linear agent invocations",
-            format: "password",
-        },
-        model: {
-            type: "string",
-            description: "OpenAI model id for direct Linear agent invocations (default: gpt-4o-mini)",
-            default: "gpt-4o-mini",
-        },
     },
 };
 export default definePlugin({
-    id: "linear",
     name: "Linear",
-    description: "Linear OAuth connect flow and MCP-backed agent for issues, projects, and comments",
+    description: "Linear MCP-backed specialist agent for issues, projects, and comments",
     configSchema: linearPluginConfigSchema,
-    toolDefinitions,
     factory: (pluginContext) => (builder) => {
         const { agentId, config, storage } = pluginContext;
         const linearConfig = readLinearConfig(config);
-        const publicBaseUrl = pluginContext.publicBaseUrl ?? "";
-        builder.on("action:webhook", async function* (event) {
-            const webhook = event;
-            if (webhook.data.provider !== OAUTH_WEBHOOK_PROVIDER)
-                return;
-            const result = await handleWebhookOAuthCallback({
-                storage,
-                query: webhook.data.query ?? {},
-                onSuccess: (tokens) => saveTokens(storage, tokens),
-            });
-            if (result.kind === "ignore")
-                return;
-            yield webhookHttpResponse({
-                status: result.status,
-                headers: { "Content-Type": "text/html; charset=utf-8" },
-                body: result.html,
-            });
-        });
-        builder.on("action:linear_connect", async function* (event) {
-            yield* handleConnect(pluginContext, event, publicBaseUrl);
-        });
-        builder.on("action:linear_disconnect", async function* (event) {
-            await clearTokens(storage);
-            yield toolResult("linear_disconnect", event, {
-                output: "Linear disconnected — stored OAuth tokens were removed.",
-            });
-        });
         builder.on("agent:invoke", async function* (event, ctx) {
             if (!shouldHandleInvoke(event, agentId))
                 return;
@@ -259,56 +51,63 @@ export default definePlugin({
             if (!auth.ok) {
                 yield agentOutput({
                     agentId,
-                    content: notConnectedMessage(auth.missing),
+                    content: formatMissingCredentials(auth.missing, linearConfig.authMode),
+                    threadId,
+                    meta: event.meta,
+                });
+                return;
+            }
+            if (auth.credentials.authMode === "credits" &&
+                !resolveCreditsAuthConfig()) {
+                yield agentOutput({
+                    agentId,
+                    content: CREDITS_NOT_CONFIGURED_MESSAGE,
                     threadId,
                     meta: event.meta,
                 });
-                if (auth.missing.includes("accessToken")) {
-                    const oauth = await createOAuthHandle(pluginContext, publicBaseUrl);
-                    if (oauth) {
-                        yield* yieldOAuthAuthorizeWidget(agentId, oauth.handle.authorizeUrl, oauth.modeHint, {
-                            threadId,
-                            meta: event.meta,
-                            widgetId: CONNECT_PROMPT_WIDGET_ID,
-                        });
-                    }
-                }
                 return;
             }
             try {
-                const reply = await runLinearAgent({
+                const threadContext = await loadThreadContext(storage, {
+                    channelId: ctx.state.channelId,
+                    threadId,
+                    agentId,
+                    currentMessage: userMessage,
+                });
+                for await (const chunk of runLinearAgent({
                     prompt: userMessage,
+                    threadContext: threadContext || undefined,
+                    authMode: auth.credentials.authMode,
                     openaiApiKey: auth.credentials.openaiApiKey,
-                    accessToken: auth.credentials.accessToken,
+                    apiKey: auth.credentials.apiKey,
                     model: auth.credentials.model,
-                });
-                const issues = reply.issues;
-                const shouldListIssues = isListIssuesPrompt(userMessage) || isAssignedIssuesPrompt(userMessage);
-                if (shouldListIssues || issues.length > 0) {
-                    yield uiWidget({
+                })) {
+                    if (chunk.kind === "widget") {
+                        yield uiWidget({
+                            agentId,
+                            widget: chunk.widget,
+                            threadId,
+                            meta: event.meta,
+                        });
+                        continue;
+                    }
+                    yield agentOutput({
                         agentId,
+                        content: chunk.content,
                         threadId,
                         meta: event.meta,
-                        widget: buildIssuesListWidget(issues, {
-                            title: issuesListTitle(userMessage),
-                        }),
                     });
                 }
-                const content = reply.toolErrors.length > 0 && !reply.usedTools
-                    ? `${reply.text}\n\nMCP note: ${reply.toolErrors.join("; ")}`
-                    : reply.text;
-                yield agentOutput({
-                    agentId,
-                    content,
-                    threadId,
-                    meta: event.meta,
-                });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                const creditsMessage = auth.credentials.authMode === "credits"
+                    ? creditsErrorMessage(message)
+                    : undefined;
                 yield agentOutput({
                     agentId,
-                    content: `Linear agent error: ${message}`,
+                    content: (creditsMessage ?? message) ||
+                        "Linear agent failed for an unknown reason. Please try again.",
                     threadId,
                     meta: event.meta,
                 });

package/dist/linear-agent.js

@@ -1,72 +1,153 @@
-import { createOpenAI } from "@ai-sdk/openai";
 import { generateText, stepCountIs } from "ai";
-import { extractIssuesFromToolResults } from "./linear-issues.js";
 import { createLinearMcpClient } from "./linear-mcp.js";
-const SYSTEM_PROMPT = `You are the OpenBot Linear specialist agent.
-You MUST use the provided Linear MCP tools for every request about issues, projects, teams, or comments.
-Never guess or invent Linear data. If a tool returns no results, say so explicitly.
-For listing or searching issues, call linear_get_user first when the user asks for issues assigned to them, then call linear_search_issues with the correct filters.
-Summarize tool results clearly in plain text. Be concise and friendly.`;
-function extractToolErrors(toolResults) {
-    const errors = [];
-    for (const toolResult of toolResults) {
-        const output = toolResult.output;
-        if (!output || typeof output !== "object")
-            continue;
-        const record = output;
-        if (typeof record.error === "string") {
-            errors.push(`${toolResult.toolName}: ${record.error}`);
-            continue;
-        }
-        if (typeof record.isError === "boolean" && record.isError) {
-            const text = typeof record.text === "string"
-                ? record.text
-                : JSON.stringify(record).slice(0, 300);
-            errors.push(`${toolResult.toolName}: ${text}`);
-        }
+import { throwMcpError } from "./mcp-errors.js";
+import { wrapMcpTools } from "./mcp-tool-args.js";
+import { resolveOpenAiModel } from "./model.js";
+const TOOL_OUTPUT_MAX_LENGTH = 2_000;
+function formatToolOutput(output) {
+    if (output === undefined || output === null)
+        return "Done.";
+    if (typeof output === "string")
+        return truncate(output);
+    try {
+        return truncate(JSON.stringify(output, null, 2));
     }
-    return errors;
+    catch {
+        return truncate(String(output));
+    }
+}
+function truncate(text) {
+    if (text.length <= TOOL_OUTPUT_MAX_LENGTH)
+        return text;
+    return `${text.slice(0, TOOL_OUTPUT_MAX_LENGTH)}…`;
+}
+function toolCallWidget(args) {
+    return {
+        kind: "message",
+        variant: "basic",
+        display: "collapsed",
+        widgetId: args.widgetId,
+        title: args.title,
+        ...(args.body ? { body: args.body } : {}),
+    };
 }
-export async function runLinearAgent(args) {
-    const openai = createOpenAI({ apiKey: args.openaiApiKey });
-    const mcpClient = await createLinearMcpClient({
-        accessToken: args.accessToken,
+const SYSTEM_PROMPT = `You are the OpenBot Linear specialist agent. Help users search, read, create, and update Linear issues, projects, teams, comments, and documents.
+
+## Ground rules
+- Use Linear MCP tools for all workspace facts. Never invent issue IDs, titles, statuses, assignees, URLs, or counts.
+- Authentication is already configured. Do not call auth tools.
+- Use prior conversation context when provided. Treat the latest user message as the current request.
+- If the request is ambiguous (missing team, assignee, or required fields), ask a short clarifying question instead of guessing.
+- Omit optional tool parameters when unused. Never pass empty strings or empty arrays for optional filters or pagination.
+- Confirm before destructive actions unless the user was explicit.
+
+## Tool selection
+- Known issue identifier (e.g. ENG-123): get_issue.
+- Discovery or filters (status, assignee, team, text): list_issues. For the current user's issues, use assignee "me".
+- Projects: list_projects to browse, get_project for one project.
+- Teams, workflow states, and labels: list_teams, get_team, list_issue_statuses, list_issue_labels.
+- Current user: get_user.
+- Comments: list_comments, create_comment.
+- Product help: search_documentation.
+
+## Create and update workflow
+1. Resolve team, status, label, assignee, and project details via list_teams, list_issue_statuses, list_issue_labels, list_projects, or get_user as needed.
+2. Perform the mutation with create_issue, update_issue, create_project, or update_project.
+3. Summarize what changed, including identifiers (e.g. ENG-123), titles, and key fields.
+
+Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Normal, 4 = Low.
+
+## Response style
+Reply in concise plain text. Lead with the outcome, then key details (identifiers, titles, status, assignee). Mention if you searched but found nothing.`;
+export async function* runLinearAgent(args) {
+    const model = resolveOpenAiModel(args.model ?? "openai/gpt-4o-mini", {
+        authMode: args.authMode,
+        openaiApiKey: args.openaiApiKey,
     });
-    try {
-        const tools = await mcpClient.tools();
-        if (Object.keys(tools).length === 0) {
-            throw new Error("Linear MCP server returned no tools. Check that mcp-server-linear is installed and reachable.");
+    const mcpSession = await createLinearMcpClient({
+        apiKey: args.apiKey,
+    }).catch((error) => {
+        throwMcpError("launch", error);
+    });
+    const queue = [];
+    let wake;
+    let agentDone = false;
+    let agentError;
+    const enqueue = (event) => {
+        queue.push(event);
+        wake?.();
+        wake = undefined;
+    };
+    const waitForQueue = () => new Promise((resolve) => {
+        wake = resolve;
+    });
+    const agentTask = (async () => {
+        try {
+            const rawTools = await mcpSession.client.tools().catch((error) => {
+                throwMcpError("tools", error);
+            });
+            if (Object.keys(rawTools).length === 0) {
+                throwMcpError("tools", new Error("Linear MCP server returned no tools"));
+            }
+            const tools = wrapMcpTools(rawTools);
+            const prompt = args.threadContext
+                ? `${args.threadContext}\n\nCurrent message:\n${args.prompt}`
+                : args.prompt;
+            const result = await generateText({
+                model,
+                system: SYSTEM_PROMPT,
+                prompt,
+                tools,
+                stopWhen: stepCountIs(10),
+                onToolExecutionStart: ({ toolCall }) => {
+                    enqueue({
+                        kind: "widget",
+                        widget: toolCallWidget({
+                            widgetId: toolCall.toolCallId,
+                            title: toolCall.toolName,
+                        }),
+                    });
+                },
+                onToolExecutionEnd: ({ toolCall, toolOutput }) => {
+                    enqueue({
+                        kind: "widget",
+                        widget: toolCallWidget({
+                            widgetId: toolCall.toolCallId,
+                            title: toolCall.toolName,
+                            body: formatToolOutput(toolOutput),
+                        }),
+                    });
+                },
+            }).catch((error) => {
+                throwMcpError("agent", error);
+            });
+            enqueue({
+                kind: "reply",
+                content: result.text.trim() || "Done.",
+            });
         }
-        const result = await generateText({
-            model: openai(args.model ?? "gpt-4o-mini"),
-            system: SYSTEM_PROMPT,
-            prompt: args.prompt,
-            tools,
-            stopWhen: stepCountIs(10),
-        });
-        const toolResults = result.steps.flatMap((step) => step.toolResults.map((toolResult) => ({
-            toolName: toolResult.toolName,
-            output: toolResult.output,
-        })));
-        const issues = extractIssuesFromToolResults(toolResults);
-        const toolErrors = extractToolErrors(toolResults);
-        const text = result.text.trim();
-        if (!text && toolErrors.length > 0) {
-            return {
-                text: `Linear tool error: ${toolErrors[0]}`,
-                issues,
-                usedTools: toolResults.length > 0,
-                toolErrors,
-            };
+        catch (error) {
+            agentError = error;
+        }
+        finally {
+            agentDone = true;
+            wake?.();
+            wake = undefined;
+        }
+    })();
+    try {
+        while (!agentDone || queue.length > 0) {
+            if (queue.length === 0) {
+                await waitForQueue();
+                continue;
+            }
+            yield queue.shift();
         }
-        return {
-            text: text || (issues.length > 0 ? `Found ${issues.length} issue(s).` : "Done."),
-            issues,
-            usedTools: toolResults.length > 0,
-            toolErrors,
-        };
+        await agentTask;
+        if (agentError)
+            throw agentError;
     }
     finally {
-        await mcpClient.close();
+        await mcpSession.client.close().catch(() => undefined);
     }
 }

package/dist/linear-mcp.js

@@ -1,26 +1,14 @@
-import { createRequire } from "node:module";
 import { createMCPClient } from "@ai-sdk/mcp";
-import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
-const require = createRequire(import.meta.url);
-function resolveMcpServerLinearLaunch() {
-    try {
-        const entry = require.resolve("mcp-server-linear");
-        return { command: process.execPath, args: [entry] };
-    }
-    catch {
-        return { command: "npx", args: ["-y", "mcp-server-linear"] };
-    }
-}
+const LINEAR_MCP_URL = "https://mcp.linear.app/mcp";
 export async function createLinearMcpClient(args) {
-    const launch = resolveMcpServerLinearLaunch();
-    return createMCPClient({
-        transport: new Experimental_StdioMCPTransport({
-            command: launch.command,
-            args: launch.args,
-            env: {
-                ...process.env,
-                LINEAR_ACCESS_TOKEN: args.accessToken,
+    const client = await createMCPClient({
+        transport: {
+            type: "http",
+            url: LINEAR_MCP_URL,
+            headers: {
+                Authorization: `Bearer ${args.apiKey}`,
             },
-        }),
+        },
     });
+    return { client };
 }

package/dist/mcp-errors.js

@@ -0,0 +1,40 @@
+function summarizeMessage(message, maxLength = 240) {
+    const trimmed = message.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= maxLength)
+        return trimmed;
+    return `${trimmed.slice(0, maxLength - 1)}…`;
+}
+export function formatMcpUserError(error, phase) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (phase === "launch" ||
+        lower.includes("enoent") ||
+        lower.includes("err_invalid_arg_value") ||
+        (lower.includes("spawn") && lower.includes("npx")) ||
+        lower.includes("command not found")) {
+        return "Could not connect to Linear MCP at mcp.linear.app. Check your network access and API key, then try again.";
+    }
+    if (lower.includes("401") ||
+        lower.includes("unauthorized") ||
+        lower.includes("invalid api key") ||
+        lower.includes("invalid token") ||
+        (lower.includes("authentication") && lower.includes("linear"))) {
+        return "Linear API key appears invalid or expired. Update your personal API key in plugin config or the LINEAR_API_KEY workspace secret.";
+    }
+    if ((lower.includes("connection") && lower.includes("closed")) ||
+        lower.includes("transport closed") ||
+        lower.includes("econnreset") ||
+        lower.includes("econnrefused")) {
+        return "The Linear MCP server disconnected unexpectedly. Try your request again; if it keeps failing, restart the OpenBot runtime.";
+    }
+    if (phase === "tools") {
+        return `Could not connect to Linear MCP tools: ${summarizeMessage(message)}`;
+    }
+    if (phase === "agent") {
+        return `Linear agent failed while talking to MCP: ${summarizeMessage(message)}`;
+    }
+    return `Could not start the Linear MCP server: ${summarizeMessage(message)}`;
+}
+export function throwMcpError(phase, error) {
+    throw new Error(formatMcpUserError(error, phase));
+}