@elnora-ai/linear 1.0.0 → 1.1.0

package/templates/SLA-OPS-operational.md

@@ -0,0 +1,70 @@
+# SLA-OPS: Operational Request
+
+## Quick Reference
+- **SLA:** 3-14 days
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Operational Requests
+
+## Priority to SLA Mapping
+| Priority | Resolution Timeframe |
+|----------|---------------------|
+| High | 3 days |
+| Medium | 7 days |
+| Low | 14 days |
+
+## Required Labels
+- `Type: feature`
+- `Layer: devops`
+- `Infrastructure` (if infrastructure work)
+- `Account Setup` (if account work)
+
+## Issue Template
+```markdown
+## Operational Request
+
+**Request ID:** SLA-OPS-YYYY-XXX
+**Request Date:** [YYYY-MM-DD]
+**Requestor:** [Name]
+**Priority:** [High / Medium / Low]
+**SLA Deadline:** [YYYY-MM-DD]
+
+## Request Type
+- [ ] Infrastructure provisioning
+- [ ] Account setup
+- [ ] Configuration change
+- [ ] Access modification
+- [ ] Other: ___
+
+## Request Details
+[Detailed description of what is being requested]
+
+## Business Justification
+[Why is this request needed?]
+
+## Requirements
+[Specific technical requirements]
+
+## Dependencies
+- [ ] [Dependency 1]
+- [ ] [Dependency 2]
+
+## Implementation Plan
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Verification Criteria
+- [ ] [How to verify completion]
+
+## Approvals
+- [ ] Manager approval: _________________ Date: _______
+- [ ] Technical approval (if needed): _________________ Date: _______
+
+## Completion
+- [ ] Request fulfilled
+- [ ] Requestor notified
+- [ ] Documentation updated
+
+**Completion Date:** [YYYY-MM-DD]
+**SLA Met:** [Yes / No]
+```

package/templates/agent-server-template/README.md

@@ -0,0 +1,88 @@
+# Agent webhook receiver — reference template
+
+This directory is **a template, not a running server**. The Linear plugin is a CLI; it doesn't host long-running HTTP listeners. If you want the plugin to act as a Linear agent (the `actor=app` model where users `@mention` it or assign issues to it), you need to host this receiver somewhere — copy `server.example.ts` into your own project and adapt.
+
+## What it does
+
+1. Listens for `POST /linear/webhook` from Linear.
+2. Verifies the `linear-signature` HMAC-SHA256 header against the body using your stored signing secret.
+3. On `agentSessionEvent.created`, emits a `thought` activity within 10 seconds via the plugin's CLI to ack the session.
+4. Hands off to your actual agent logic (which you write).
+
+## Where to host
+
+| Host | Notes |
+|---|---|
+| Cloudflare Workers | Linear's own `linear/linear-agent-demo` uses Workers. Edit the example to use the Fetch API runtime. |
+| Vercel / Netlify functions | Fine for low traffic. Same Fetch API edits. |
+| Fly.io / Railway / Render | Run the example mostly as-is on Node. |
+| Local + ngrok | For dev only — Linear retries 3× on failure (1 min / 1 hr / 6 hr). |
+
+## Setup
+
+```bash
+# 1. Build the plugin CLI so the template can call it.
+npm install -g @elnora-ai/linear
+
+# 2. Copy this template into your own project.
+cp -r templates/agent-server-template /path/to/your/agent-server
+
+# 3. Register the webhook with Linear.
+linear webhooks create \
+  --url https://your-public-url/linear/webhook \
+  --resource-types AgentSessionEvent \
+  --all-public-teams
+# Save the secret it returns into LINEAR_WEBHOOK_SECRET.
+
+# 4. Run the receiver.
+LINEAR_API_KEY=lin_api_... \
+LINEAR_WEBHOOK_SECRET=lin_wh_... \
+node server.example.js
+```
+
+## What you fill in
+
+The template stops after acking the session. The real agent logic — running Claude Code, opening a PR, posting back to Linear — goes in the `// TODO` block. Common patterns:
+
+- **Quick echo bot:** emit a `response` activity with whatever you want to say.
+- **Coding agent:** `child_process.spawn` your dev workflow (e.g. `claude` + a prompt that includes the issue context).
+- **Triage routing:** read the issue, decide if it's for the bot, otherwise emit a `response` and exit.
+
+Use the CLI for everything Linear-side:
+
+```bash
+linear agent-activities create <sessionId> --type thought --body "Working on it"
+linear agent-activities create <sessionId> --type response --body "Done. PR: <url>"
+linear agent-sessions update-external-url <sessionId> --add https://github.com/.../pull/42
+```
+
+## Security notes
+
+- **Always** verify the signature before reading the body. The template ships an inline `verifyLinearWebhook` helper (HMAC-SHA256 + `timingSafeEqual`) — don't bypass it.
+- **Never** commit `LINEAR_WEBHOOK_SECRET` or `LINEAR_API_KEY`. Use your host's secret store.
+- **Rotate** the webhook secret with `linear webhooks rotate-secret <id> --yes` if you suspect a leak. The new secret is shown ONCE.
+- **Respond fast.** Linear retries on non-200 or >5s. ACK within 200ms by responding `200 ok` immediately, then doing the work async.
+
+## Activity types & lifecycle
+
+| Type | Body | When to use |
+|---|---|---|
+| `thought` | text | Internal narration, including the mandatory 10s ack |
+| `action` | `{action, parameter, result}` | Tool call summary (e.g. "ran `gh pr create`") |
+| `elicitation` | text + `signal` (`select` / `auth`) | Ask the user (multi-choice or auth URL) |
+| `response` | text | Final visible answer |
+| `error` | text | Visible failure message |
+
+The session is considered "stale" after 30 minutes of inactivity but is recoverable — emit any activity to revive.
+
+## Troubleshooting
+
+- **401 in your logs**: signature mismatch. Check `LINEAR_WEBHOOK_SECRET` matches what `linear webhooks list` shows.
+- **No webhook delivered**: confirm `agentSessionEvent` is in the webhook's `resourceTypes`.
+- **"Agent unresponsive" in Linear UI**: you took longer than 10s to emit a thought. Move the ack BEFORE any expensive work.
+
+## See also
+
+- Plugin CLI: `linear webhooks --help`, `linear agent-sessions --help`, `linear agent-activities --help`
+- Linear's official agent docs: https://linear.app/developers/agents
+- Linear's reference Cloudflare-Worker demo: https://github.com/linear/linear-agent-demo

package/templates/agent-server-template/server.example.ts

@@ -0,0 +1,185 @@
+/**
+ * Reference webhook receiver for Linear's agent framework.
+ *
+ * This is a TEMPLATE — it ships with the plugin so operators can run their
+ * own agent receiver wherever they want (Cloudflare Worker, Vercel function,
+ * Fly machine, etc.). The plugin itself is a CLI; it does not host this
+ * server for you.
+ *
+ *   1. Register a webhook in Linear pointing at this server's URL:
+ *        linear webhooks create \
+ *          --url https://your-host/linear/webhook \
+ *          --resource-types AgentSessionEvent \
+ *          --all-public-teams
+ *      (Linear will return a signing secret — store as LINEAR_WEBHOOK_SECRET.)
+ *
+ *   2. Run this server with both env vars set:
+ *        LINEAR_API_KEY=lin_api_... \
+ *        LINEAR_WEBHOOK_SECRET=lin_wh_... \
+ *        node server.example.js
+ *
+ *   3. Linear delivers `agentSessionEvent` POSTs to /linear/webhook. We
+ *      verify the signature, then must emit a `thought` activity within
+ *      10 seconds to acknowledge.
+ *
+ * The activity-create call shells out to the plugin's CLI so you don't end
+ * up with two implementations. The signature verifier is inlined below so
+ * this file works after `cp -r` out of the plugin tree — no relative
+ * imports back into the plugin source.
+ */
+
+import http from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Verify a Linear webhook payload's HMAC-SHA256 signature AND its replay
+ * window. Mirrors the implementation in the plugin's webhook-verify util —
+ * kept inline so this template stands alone after copy.
+ *
+ * Replay protection: when `timestamp` (the `webhookTimestamp` field from the
+ * parsed body, Unix ms) is provided, payloads older than `maxAgeMs` are
+ * rejected. Without this, an attacker who captures a valid signed request
+ * can replay it forever.
+ */
+// Linear recommends 60 s — see https://linear.app/developers/webhooks
+const DEFAULT_WEBHOOK_MAX_AGE_MS = 60 * 1000;
+
+function verifyLinearWebhook(opts: {
+  rawBody: string | Buffer;
+  signature: string;
+  secret: string;
+  timestamp?: number;
+  maxAgeMs?: number;
+}): boolean {
+  if (!opts.signature || !opts.secret) return false;
+  const body = typeof opts.rawBody === "string" ? Buffer.from(opts.rawBody, "utf-8") : opts.rawBody;
+  const expectedHex = createHmac("sha256", opts.secret).update(body).digest("hex");
+  const expected = Buffer.from(expectedHex, "hex");
+  let received: Buffer;
+  try {
+    received = Buffer.from(opts.signature, "hex");
+  } catch {
+    return false;
+  }
+  if (received.length !== expected.length) return false;
+  if (!timingSafeEqual(received, expected)) return false;
+
+  if (typeof opts.timestamp === "number") {
+    if (!Number.isFinite(opts.timestamp)) return false;
+    const maxAgeMs = opts.maxAgeMs ?? DEFAULT_WEBHOOK_MAX_AGE_MS;
+    if (Math.abs(Date.now() - opts.timestamp) > maxAgeMs) return false;
+  }
+  return true;
+}
+
+const PORT = Number(process.env.PORT ?? 8787);
+const SECRET = process.env.LINEAR_WEBHOOK_SECRET;
+const CLI_PATH = process.env.LINEAR_CLI_PATH ?? "../../cli/bin/linear.js";
+
+if (!SECRET) {
+  console.error("LINEAR_WEBHOOK_SECRET not set — refusing to start.");
+  process.exit(1);
+}
+if (!process.env.LINEAR_API_KEY) {
+  console.error("LINEAR_API_KEY not set — refusing to start.");
+  process.exit(1);
+}
+
+interface AgentSessionEvent {
+  type: "AgentSessionEvent";
+  action: "created" | "prompted";
+  agentSession?: { id: string; type?: string };
+  promptContext?: string;
+}
+
+async function readBody(req: http.IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** Emit a thought activity via the CLI (one process per call — fine for ack). */
+async function emitThought(sessionId: string, body: string): Promise<void> {
+  await execFileAsync("node", [
+    CLI_PATH,
+    "agent-activities", "create", sessionId,
+    "--type", "thought",
+    "--body", body,
+  ]);
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.method !== "POST" || req.url !== "/linear/webhook") {
+    res.writeHead(404);
+    res.end();
+    return;
+  }
+  const signature = req.headers["linear-signature"];
+  if (typeof signature !== "string") {
+    res.writeHead(400);
+    res.end("Missing linear-signature header");
+    return;
+  }
+  const rawBody = await readBody(req);
+  // HMAC-verify on the raw bytes BEFORE touching JSON.parse — never let
+  // unverified input reach the parser. Replay-window check happens after,
+  // once we trust the body enough to read webhookTimestamp out of it.
+  if (!verifyLinearWebhook({ rawBody, signature, secret: SECRET })) {
+    res.writeHead(401);
+    res.end("Invalid signature");
+    return;
+  }
+  let parsedForTimestamp: { webhookTimestamp?: number } = {};
+  try {
+    parsedForTimestamp = JSON.parse(rawBody.toString("utf-8"));
+  } catch {
+    res.writeHead(400);
+    res.end("Body is not valid JSON");
+    return;
+  }
+  const timestamp = parsedForTimestamp.webhookTimestamp;
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+    res.writeHead(401);
+    res.end("Missing or invalid webhookTimestamp");
+    return;
+  }
+  if (Math.abs(Date.now() - timestamp) > DEFAULT_WEBHOOK_MAX_AGE_MS) {
+    res.writeHead(401);
+    res.end("Expired payload");
+    return;
+  }
+  // ACK Linear within 5s — non-200 triggers a retry and counts against agent
+  // responsiveness. Do work async after responding.
+  res.writeHead(200);
+  res.end("ok");
+
+  const payload = JSON.parse(rawBody.toString("utf-8")) as AgentSessionEvent;
+  if (payload.type !== "AgentSessionEvent") return;
+  if (payload.action !== "created") return;
+  const sessionId = payload.agentSession?.id;
+  if (!sessionId) return;
+
+  // Linear requires a thought within 10s — emit immediately then start work.
+  try {
+    await emitThought(sessionId, "Got it — picking this up now.");
+  } catch (e) {
+    console.error("Failed to emit ack thought:", e);
+    return;
+  }
+
+  // TODO: kick off whatever the agent actually does. Examples:
+  //  - Run /linear-work as a subprocess (background coding agent)
+  //  - Trigger your own task queue
+  //  - Update the issue with progress via `linear issues update`
+  console.log(`[agent] session ${sessionId} acknowledged`);
+});
+
+server.listen(PORT, () => {
+  console.log(`Linear agent webhook receiver listening on :${PORT}/linear/webhook`);
+});