@calltelemetry/openclaw-linear 0.2.0 → 0.3.1

package/README.md

@@ -4,12 +4,60 @@ Webhook-driven Linear integration with OAuth support, multi-agent routing, and a
 
 ## What It Does
 
+- **Auto-triage** — New issues are automatically estimated (story points), labeled, and prioritized with a posted assessment
 - **Issue triage** — When an issue is assigned/delegated to the app user, an agent estimates story points, applies labels, and posts an assessment
 - **Agent sessions** — Full plan-approve-implement-audit pipeline triggered from Linear's agent UI
 - **@mention routing** — Comment mentions like `@qa` or `@infra` route to specific role-based agents with different expertise
 - **App notifications** — Responds to Linear app mentions and assignments via branded comments
 - **Activity tracking** — Emits thought/action/response events visible in Linear's agent session UI
 
+## Quick Install
+
+```bash
+openclaw plugins install @calltelemetry/openclaw-linear
+openclaw gateway restart
+```
+
+That's it — the plugin is installed and enabled. Continue with the [setup steps](#setup) below to configure Linear OAuth and webhooks.
+
+> To install from a local checkout instead: `openclaw plugins install --link /path/to/linear`
+
+## First Run
+
+After installing, the plugin loads but **will not process any webhooks or agent tools until you authenticate**. You'll see this in the logs:
+
+```
+Linear agent extension registered (agent: default, token: missing)
+```
+
+This is normal — the plugin does not crash without auth. It registers all routes and CLI commands, but webhook handlers and tools will return errors until a token is available.
+
+To authenticate:
+
+```bash
+# Set your OAuth app credentials
+export LINEAR_CLIENT_ID="your_client_id"
+export LINEAR_CLIENT_SECRET="your_client_secret"
+
+# Run the OAuth flow
+openclaw openclaw-linear auth
+
+# Verify
+openclaw openclaw-linear status
+```
+
+The auth flow stores tokens in `~/.openclaw/auth-profiles.json`. This file is created automatically — you do not need to create it manually. After auth, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+You should now see `token: profile` in the logs:
+
+```
+Linear agent extension registered (agent: default, token: profile)
+```
+
 ## Prerequisites
 
 - OpenClaw gateway running (systemd service)
@@ -153,16 +201,28 @@ export OPENCLAW_GATEWAY_PORT="18789"  # if non-default
 
 ### 5. Install the Plugin
 
-Add the plugin path to your OpenClaw config (`~/.openclaw/openclaw.json`):
+If you haven't already installed via [Quick Install](#quick-install):
+
+```bash
+openclaw plugins install @calltelemetry/openclaw-linear
+openclaw gateway restart
+```
+
+This registers the plugin in your OpenClaw config and restarts the gateway to load it.
+
+<details>
+<summary>Manual config (advanced)</summary>
+
+If you prefer to manage config by hand, add the plugin path to `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "plugins": {
     "load": {
-      "paths": ["/path/to/claw-extensions/linear"]
+      "paths": ["/path/to/linear"]
     },
     "entries": {
-      "linear": {
+      "openclaw-linear": {
         "enabled": true
       }
     }
@@ -170,11 +230,8 @@ Add the plugin path to your OpenClaw config (`~/.openclaw/openclaw.json`):
 }
 ```
 
-Restart the gateway to load the plugin:
-
-```bash
-openclaw gateway restart
-```
+Then restart: `openclaw gateway restart`
+</details>
 
 ### 6. Run the OAuth Flow
 
@@ -183,7 +240,7 @@ There are two ways to authorize the plugin with Linear.
 #### Option A: CLI Flow (Recommended)
 
 ```bash
-openclaw auth linear oauth
+openclaw openclaw-linear auth
 ```
 
 This launches the OAuth flow interactively:
@@ -283,13 +340,61 @@ Create `~/.openclaw/agent-profiles.json` to define role-based agents:
 | Field | Required | Description |
 |---|---|---|
 | `label` | Yes | Display name in Linear comments |
-| `mission` | Yes | Agent's role description (provided as context when dispatched) |
-| `isDefault` | One agent | The default agent handles OAuth app events and assignment triage |
+| `mission` | Yes | Agent's role description (injected as system context when the agent is dispatched) |
+| `isDefault` | One agent | The default agent handles OAuth app events, agent sessions, and assignment triage |
 | `mentionAliases` | Yes | @mention triggers in comments (e.g., `@qa` in a comment routes to the QA agent) |
 | `appAliases` | No | Triggers via OAuth app webhook (default agent only, for app-level @mentions) |
 | `avatarUrl` | No | Avatar displayed on branded comments. Falls back to `[Label]` prefix if not set. |
 
-Each agent ID (the JSON key) must match a configured OpenClaw agent in `openclaw.json`. The plugin dispatches to agents via `openclaw agent --agent <id>`.
+#### How agent-profiles.json connects to openclaw.json
+
+Each key in `agent-profiles.json` (e.g., `"lead"`, `"qa"`) must have a matching agent definition in your OpenClaw config (`~/.openclaw/openclaw.json`). The Linear plugin dispatches work via `openclaw agent --agent <id>`, so the agent must actually exist.
+
+Example — if `agent-profiles.json` defines `"lead"` and `"qa"`, your `openclaw.json` needs:
+
+```json
+{
+  "agents": {
+    "lead": {
+      "model": "claude-sonnet-4-5-20250929",
+      "systemPrompt": "You are a product lead agent...",
+      "tools": ["linear_list_issues", "linear_create_issue", "linear_add_comment"]
+    },
+    "qa": {
+      "model": "claude-sonnet-4-5-20250929",
+      "systemPrompt": "You are a QA engineer agent...",
+      "tools": ["linear_list_issues", "linear_add_comment"]
+    }
+  }
+}
+```
+
+#### Routing flow
+
+```
+Linear comment "@qa review this test plan"
+  → Plugin matches "qa" in mentionAliases
+  → Looks up agent-profiles.json → finds "qa" profile
+  → Dispatches: openclaw agent --agent qa --message "<issue context + comment>"
+  → OpenClaw loads "qa" agent config from openclaw.json
+  → Agent runs with the qa profile's mission as context
+  → Response posted back to Linear as a branded comment with qa's label/avatar
+```
+
+For agent sessions (triggered by the Linear agent UI or app @mentions):
+
+```
+Linear AgentSessionEvent.created
+  → Plugin resolves the default agent (isDefault: true)
+  → Runs the 3-stage pipeline (plan → implement → audit)
+  → Each stage dispatches via the default agent's openclaw.json config
+```
+
+#### What happens if they don't match
+
+- **Agent profile exists but no matching openclaw.json agent:** The dispatch fails and an error is logged. The webhook returns 200 (Linear requirement) but no comment is posted.
+- **openclaw.json agent exists but no profile:** The agent works for direct CLI use but won't be reachable from Linear. No @mention alias maps to it.
+- **No agent marked `isDefault`:** Agent sessions and assignment triage will fail with `"No defaultAgentId"` error.
 
 ### 8. Verify
 
@@ -327,6 +432,7 @@ POST /linear/webhook
   +-- AgentSessionEvent.prompted --> Resume pipeline (user approved plan)
   +-- AppUserNotification        --> Direct agent response to mention/assignment
   +-- Comment.create             --> Route @mention to role-based agent
+  +-- Issue.create               --> Auto-triage new issues (estimate, labels, priority)
   +-- Issue.update               --> Triage if assigned/delegated to app user
 ```
 
@@ -381,7 +487,7 @@ Optional settings in `openclaw.json` under the plugin entry:
 {
   "plugins": {
     "entries": {
-      "linear": {
+      "openclaw-linear": {
         "enabled": true,
         "clientId": "...",
         "clientSecret": "...",
@@ -451,7 +557,7 @@ openclaw logs | grep -i "linear\|plugin\|error"
 **Agent sessions not working:**
 - OAuth tokens require `app:assignable` and `app:mentionable` scopes
 - Personal API keys cannot create agent sessions — use OAuth
-- Re-run `openclaw auth linear oauth` to get fresh tokens
+- Re-run `openclaw openclaw-linear auth` to get fresh tokens
 
 **"No defaultAgentId" error:**
 - Set `defaultAgentId` in plugin config, OR

package/index.ts

@@ -1,5 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerLinearProvider } from "./src/auth.js";
+import { registerCli } from "./src/cli.js";
 import { createLinearTools } from "./src/tools.js";
 import { handleLinearWebhook } from "./src/webhook.js";
 import { handleOAuthCallback } from "./src/oauth-callback.js";
@@ -20,6 +21,11 @@ export default function register(api: OpenClawPluginApi) {
   // Register Linear as an auth provider (OAuth flow with agent scopes)
   registerLinearProvider(api);
 
+  // Register CLI commands: openclaw openclaw-linear auth|status
+  api.registerCli(({ program }) => registerCli(program, api), {
+    commands: ["openclaw-linear"],
+  });
+
   // Register Linear tools for the agent
   api.registerTool((ctx) => {
     return createLinearTools(api, ctx);

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "linear",
+  "id": "openclaw-linear",
   "name": "Linear Agent",
   "description": "Linear integration with OAuth support, agent pipeline, and webhook-driven AI agent lifecycle",
   "version": "0.2.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/auth.ts

@@ -4,11 +4,11 @@ import type {
   ProviderAuthResult
 } from "openclaw/plugin-sdk";
 
-const LINEAR_OAUTH_AUTH_URL = "https://linear.app/oauth/authorize";
-const LINEAR_OAUTH_TOKEN_URL = "https://api.linear.app/oauth/token";
+export const LINEAR_OAUTH_AUTH_URL = "https://linear.app/oauth/authorize";
+export const LINEAR_OAUTH_TOKEN_URL = "https://api.linear.app/oauth/token";
 
 // Agent scopes: read/write + assignable (appear in assignment menus) + mentionable (respond to @mentions)
-const LINEAR_AGENT_SCOPES = "read,write,app:assignable,app:mentionable";
+export const LINEAR_AGENT_SCOPES = "read,write,app:assignable,app:mentionable";
 
 // Token refresh helper — Linear tokens expire; refresh before they do
 export async function refreshLinearToken(

package/src/cli.ts

@@ -0,0 +1,203 @@
+/**
+ * cli.ts — CLI registration for `openclaw openclaw-linear auth` and `openclaw openclaw-linear status`.
+ */
+import type { Command } from "commander";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { createInterface } from "node:readline";
+import { exec } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "./linear-api.js";
+import { LINEAR_OAUTH_AUTH_URL, LINEAR_OAUTH_TOKEN_URL, LINEAR_AGENT_SCOPES } from "./auth.js";
+
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function openBrowser(url: string): void {
+  const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+  exec(`${cmd} ${JSON.stringify(url)}`, () => {});
+}
+
+export function registerCli(program: Command, api: OpenClawPluginApi): void {
+  const linear = program
+    .command("openclaw-linear")
+    .description("Linear plugin — auth and status");
+
+  // --- openclaw openclaw-linear auth ---
+  linear
+    .command("auth")
+    .description("Run Linear OAuth flow to authorize the agent")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const clientId = (pluginConfig?.clientId as string) ?? process.env.LINEAR_CLIENT_ID;
+      const clientSecret = (pluginConfig?.clientSecret as string) ?? process.env.LINEAR_CLIENT_SECRET;
+
+      if (!clientId || !clientSecret) {
+        console.error("Error: Linear client ID and secret must be configured.");
+        console.error("Set LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET env vars, or add clientId/clientSecret to plugin config.");
+        process.exitCode = 1;
+        return;
+      }
+
+      const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT ?? "18789";
+      const redirectUri = (pluginConfig?.redirectUri as string)
+        ?? process.env.LINEAR_REDIRECT_URI
+        ?? `http://localhost:${gatewayPort}/linear/oauth/callback`;
+
+      const state = Math.random().toString(36).substring(7);
+      const authUrl = `${LINEAR_OAUTH_AUTH_URL}?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code&scope=${encodeURIComponent(LINEAR_AGENT_SCOPES)}&state=${state}&actor=app`;
+
+      console.log("\nOpening Linear OAuth authorization page...\n");
+      console.log(`  ${authUrl}\n`);
+      openBrowser(authUrl);
+
+      const code = await prompt("Paste the authorization code from Linear: ");
+      if (!code) {
+        console.error("No code provided. Aborting.");
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log("Exchanging code for token...");
+
+      const response = await fetch(LINEAR_OAUTH_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          client_id: clientId,
+          client_secret: clientSecret,
+          redirect_uri: redirectUri,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        console.error(`OAuth token exchange failed (${response.status}): ${error}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const tokens = await response.json();
+
+      // Store in auth profile store
+      let store: any = { version: 1, profiles: {} };
+      try {
+        const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+        store = JSON.parse(raw);
+      } catch {
+        // Fresh store
+      }
+
+      store.profiles = store.profiles ?? {};
+      store.profiles["linear:default"] = {
+        type: "oauth",
+        provider: "linear",
+        accessToken: tokens.access_token,
+        access: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? null,
+        refresh: tokens.refresh_token ?? null,
+        expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+        expires: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+        scope: tokens.scope,
+      };
+
+      writeFileSync(AUTH_PROFILES_PATH, JSON.stringify(store, null, 2), "utf8");
+
+      const expiresIn = tokens.expires_in ? `${Math.round(tokens.expires_in / 3600)}h` : "unknown";
+      console.log(`\nAuthorized! Token stored in auth profile store.`);
+      console.log(`  Scopes:  ${tokens.scope ?? "unknown"}`);
+      console.log(`  Expires: ${expiresIn}`);
+      console.log(`\nRestart the gateway to pick up the new token.`);
+    });
+
+  // --- openclaw openclaw-linear status ---
+  linear
+    .command("status")
+    .description("Show current Linear auth and connection status")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const tokenInfo = resolveLinearToken(pluginConfig);
+
+      console.log("\nLinear Auth Status");
+      console.log("─".repeat(40));
+      console.log(`  Source:        ${tokenInfo.source}`);
+
+      if (!tokenInfo.accessToken) {
+        console.log(`  Token:         not found`);
+        console.log(`\nRun "openclaw openclaw-linear auth" to authorize.`);
+        return;
+      }
+
+      console.log(`  Token:         ${tokenInfo.accessToken.slice(0, 12)}...`);
+      console.log(`  Refresh token: ${tokenInfo.refreshToken ? "present" : "none"}`);
+
+      if (tokenInfo.expiresAt) {
+        const remaining = tokenInfo.expiresAt - Date.now();
+        if (remaining <= 0) {
+          console.log(`  Expires:       EXPIRED`);
+        } else {
+          const hours = Math.floor(remaining / 3_600_000);
+          const mins = Math.floor((remaining % 3_600_000) / 60_000);
+          console.log(`  Expires:       ${hours}h ${mins}m`);
+        }
+      } else {
+        console.log(`  Expires:       unknown (no expiry set)`);
+      }
+
+      // Try reading scope from profile
+      try {
+        const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+        const store = JSON.parse(raw);
+        const scope = store?.profiles?.["linear:default"]?.scope;
+        if (scope) console.log(`  Scopes:        ${scope}`);
+      } catch {}
+
+      // Verify token with API call
+      console.log("\nConnection Test");
+      console.log("─".repeat(40));
+      try {
+        const authHeader = tokenInfo.refreshToken
+          ? `Bearer ${tokenInfo.accessToken}`
+          : tokenInfo.accessToken;
+
+        const res = await fetch(LINEAR_GRAPHQL_URL, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: authHeader,
+          },
+          body: JSON.stringify({
+            query: `{ viewer { id name email } organization { name urlKey } }`,
+          }),
+        });
+
+        if (!res.ok) {
+          console.log(`  API response:  ${res.status} ${res.statusText}`);
+          return;
+        }
+
+        const payload = await res.json();
+        if (payload.errors?.length) {
+          console.log(`  API error:     ${payload.errors[0].message}`);
+          return;
+        }
+
+        const { viewer, organization } = payload.data;
+        console.log(`  API:           connected`);
+        console.log(`  User:          ${viewer.name} (${viewer.email})`);
+        console.log(`  Workspace:     ${organization.name} (${organization.urlKey})`);
+      } catch (err) {
+        console.log(`  API:           failed — ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      console.log();
+    });
+}

package/src/linear-api.ts

@@ -2,8 +2,8 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { refreshLinearToken } from "./auth.js";
 
-const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
-const AUTH_PROFILES_PATH = join(
+export const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+export const AUTH_PROFILES_PATH = join(
   process.env.HOME ?? "/home/claw",
   ".openclaw",
   "auth-profiles.json",

package/src/tools.ts

@@ -1,16 +1,16 @@
 import type { AnyAgentTool, OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
 import { jsonResult } from "openclaw/plugin-sdk";
 import { LinearClient } from "./client.js";
+import { resolveLinearToken } from "./linear-api.js";
 
 export function createLinearTools(api: OpenClawPluginApi, ctx: OpenClawPluginToolContext): AnyAgentTool[] {
   const getClient = () => {
-    // In a real implementation, we would resolve the token from auth profiles
-    // For now, we'll try to get it from environment or a known profile
-    const token = process.env.LINEAR_ACCESS_TOKEN;
-    if (!token) {
-      throw new Error("Linear access token not found. Please authenticate first.");
+    const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+    const resolved = resolveLinearToken(pluginConfig);
+    if (!resolved.accessToken) {
+      throw new Error("Linear access token not found. Run 'openclaw openclaw-linear auth' to authenticate.");
     }
-    return new LinearClient(token);
+    return new LinearClient(resolved.accessToken);
   };
   
   return [

package/src/webhook.ts

@@ -844,6 +844,215 @@ export async function handleLinearWebhook(
     return true;
   }
 
+  // ── Issue.create — auto-triage new issues ───────────────────────
+  if (payload.type === "Issue" && payload.action === "create") {
+    res.statusCode = 200;
+    res.end("ok");
+
+    const issue = payload.data;
+    if (!issue?.id) {
+      api.logger.error("Issue.create missing issue data");
+      return true;
+    }
+
+    // Dedup
+    if (wasRecentlyProcessed(`issue-create:${issue.id}`)) {
+      api.logger.info(`Issue.create ${issue.id} already processed — skipping`);
+      return true;
+    }
+
+    api.logger.info(`Issue.create: ${issue.identifier ?? issue.id} — ${issue.title ?? "(untitled)"}`);
+
+    const linearApi = createLinearApi(api);
+    if (!linearApi) {
+      api.logger.error("No Linear access token — cannot triage new issue");
+      return true;
+    }
+
+    const agentId = resolveAgentId(api);
+
+    // Dispatch triage (non-blocking)
+    void (async () => {
+      const profiles = loadAgentProfiles();
+      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
+      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
+      const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+      let agentSessionId: string | null = null;
+
+      try {
+        // Fetch enriched issue + team labels
+        let enrichedIssue: any = issue;
+        let teamLabels: Array<{ id: string; name: string }> = [];
+        try {
+          enrichedIssue = await linearApi.getIssueDetails(issue.id);
+          if (enrichedIssue?.team?.id) {
+            teamLabels = await linearApi.getTeamLabels(enrichedIssue.team.id);
+          }
+        } catch (err) {
+          api.logger.warn(`Could not fetch issue details for triage: ${err}`);
+        }
+
+        const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
+        const estimationType = enrichedIssue?.team?.issueEstimationType ?? "fibonacci";
+        const currentLabels = enrichedIssue?.labels?.nodes ?? [];
+        const currentLabelNames = currentLabels.map((l: any) => l.name).join(", ") || "None";
+        const availableLabelList = teamLabels.map((l) => `  - "${l.name}" (id: ${l.id})`).join("\n");
+
+        // Create agent session
+        const sessionResult = await linearApi.createSessionOnIssue(issue.id);
+        agentSessionId = sessionResult.sessionId;
+        if (agentSessionId) {
+          wasRecentlyProcessed(`session:${agentSessionId}`);
+          api.logger.info(`Created agent session ${agentSessionId} for Issue.create triage`);
+        }
+
+        if (agentSessionId) {
+          await linearApi.emitActivity(agentSessionId, {
+            type: "thought",
+            body: `Triaging new issue ${enrichedIssue?.identifier ?? issue.id}...`,
+          }).catch(() => {});
+        }
+
+        if (agentSessionId) {
+          await linearApi.emitActivity(agentSessionId, {
+            type: "action",
+            action: "Triaging",
+            parameter: `${enrichedIssue?.identifier ?? issue.id} — estimating, labeling`,
+          }).catch(() => {});
+        }
+
+        const message = [
+          `IMPORTANT: You are triaging a new Linear issue. You MUST respond with a JSON block containing your triage decisions, followed by your assessment as plain text.`,
+          ``,
+          `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+          `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Current Estimate:** ${enrichedIssue?.estimate ?? "None"} | **Current Labels:** ${currentLabelNames}`,
+          ``,
+          `**Description:**`,
+          description,
+          ``,
+          `## Your Triage Tasks`,
+          ``,
+          `1. **Story Points** — Estimate complexity using ${estimationType} scale (1=trivial, 2=small, 3=medium, 5=large, 8=very large, 13=epic)`,
+          `2. **Labels** — Select appropriate labels from the team's available labels`,
+          `3. **Priority** — Set priority (1=Urgent, 2=High, 3=Medium, 4=Low) if not already set`,
+          `4. **Assessment** — Brief analysis of what this issue needs`,
+          ``,
+          `## Available Labels`,
+          availableLabelList || "  (no labels configured)",
+          ``,
+          `## Response Format`,
+          ``,
+          `You MUST start your response with a JSON block, then follow with your assessment:`,
+          ``,
+          '```json',
+          `{`,
+          `  "estimate": <number>,`,
+          `  "labelIds": ["<id1>", "<id2>"],`,
+          `  "priority": <number or null>,`,
+          `  "assessment": "<one-line summary of your sizing rationale>"`,
+          `}`,
+          '```',
+          ``,
+          `Then write your full assessment as markdown below the JSON block.`,
+        ].filter(Boolean).join("\n");
+
+        const sessionId = `linear-triage-${issue.id}-${Date.now()}`;
+        const { runAgent } = await import("./agent.js");
+        const result = await runAgent({
+          api,
+          agentId,
+          sessionId,
+          message,
+          timeoutMs: 3 * 60_000,
+        });
+
+        const responseBody = result.success
+          ? result.output
+          : `I encountered an error triaging this issue. Please triage manually.`;
+
+        // Parse triage JSON and apply to issue
+        let commentBody = responseBody;
+        if (result.success) {
+          const jsonMatch = responseBody.match(/```json\s*\n?([\s\S]*?)\n?```/);
+          if (jsonMatch) {
+            try {
+              const triage = JSON.parse(jsonMatch[1]);
+              const updateInput: Record<string, unknown> = {};
+
+              if (typeof triage.estimate === "number") {
+                updateInput.estimate = triage.estimate;
+              }
+              if (Array.isArray(triage.labelIds) && triage.labelIds.length > 0) {
+                const existingIds = currentLabels.map((l: any) => l.id);
+                const allIds = [...new Set([...existingIds, ...triage.labelIds])];
+                updateInput.labelIds = allIds;
+              }
+              if (typeof triage.priority === "number" && triage.priority >= 1 && triage.priority <= 4) {
+                updateInput.priority = triage.priority;
+              }
+
+              if (Object.keys(updateInput).length > 0) {
+                await linearApi.updateIssue(issue.id, updateInput);
+                api.logger.info(`Applied triage to ${enrichedIssue?.identifier ?? issue.id}: ${JSON.stringify(updateInput)}`);
+
+                if (agentSessionId) {
+                  await linearApi.emitActivity(agentSessionId, {
+                    type: "action",
+                    action: "Applied triage",
+                    result: `estimate=${triage.estimate ?? "unchanged"}, labels=${triage.labelIds?.length ?? 0}, priority=${triage.priority ?? "unchanged"}`,
+                  }).catch(() => {});
+                }
+              }
+
+              // Strip JSON block from comment
+              commentBody = responseBody.replace(/```json\s*\n?[\s\S]*?\n?```\s*\n?/, "").trim();
+            } catch (parseErr) {
+              api.logger.warn(`Could not parse triage JSON: ${parseErr}`);
+            }
+          }
+        }
+
+        // Post branded triage comment
+        const brandingOpts = avatarUrl
+          ? { createAsUser: label, displayIconUrl: avatarUrl }
+          : undefined;
+
+        try {
+          if (brandingOpts) {
+            await linearApi.createComment(issue.id, commentBody, brandingOpts);
+          } else {
+            await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
+          }
+        } catch (brandErr) {
+          api.logger.warn(`Branded comment failed, falling back to prefix: ${brandErr}`);
+          await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
+        }
+
+        if (agentSessionId) {
+          const truncated = commentBody.length > 2000
+            ? commentBody.slice(0, 2000) + "…"
+            : commentBody;
+          await linearApi.emitActivity(agentSessionId, {
+            type: "response",
+            body: truncated,
+          }).catch(() => {});
+        }
+
+        api.logger.info(`Triage complete for ${enrichedIssue?.identifier ?? issue.id}`);
+      } catch (err) {
+        api.logger.error(`Issue.create triage error: ${err}`);
+        if (agentSessionId) {
+          await linearApi.emitActivity(agentSessionId, {
+            type: "error",
+            body: `Failed to triage: ${String(err).slice(0, 500)}`,
+          }).catch(() => {});
+        }
+      }
+    })();
+
+    return true;
+  }
+
   // ── Default: log unhandled webhook types for debugging ──────────
   api.logger.warn(`Unhandled webhook type=${payload.type} action=${payload.action} — payload: ${JSON.stringify(payload).slice(0, 500)}`);
   res.statusCode = 200;