Add Linear plugin: tasks, webhook app, MCP server

[cosmicBboy]

Adds plugins/linear (flyteplugins-linear), a Linear integration for Flyte 2.

What's included

Read/write from tasks — LinearClient, an async GraphQL client covering teams, workflow states, issues (by TEAM-123 identifier or UUID), comments, and issue creation/updates. GraphQL errors are raised as LinearAPIError. Credentials come from a mounted flyte.Secret (LINEAR_API_KEY).

React to Linear events — LinearAppEnvironment serves a setup/management dashboard (/) with end-to-end setup instructions (API key creation, flyte create secret commands, Linear webhook config) and status/verify endpoints, plus an HMAC-verified webhook receiver (/webhook, X-Linear-Signature) that normalizes payloads into LinearEvent objects, applies an optional team allowlist, and dispatches to on_event handlers (Issue.create, Comment.update, ...). launch_task launches runs idempotently via dedupe labels, so webhook redeliveries never launch duplicate runs.

MCP server for agents on Flyte — the read/write surface doubles as MCP tools via build_mcp_server / linear_mcp_app_env. Read-only by default; pass read_only=False for issue creation, updates, and commenting. Tool annotations come from the registry. Event ingestion is intentionally not an MCP tool — that stays with the app environment.

Tests

57 tests covering the GraphQL client (respx-mocked), webhook signature verification and event normalization, the MCP tool registry/server, dispatch idempotency, and the app dashboard/receiver endpoints.

Examples

• examples/triage_issue.py — read/label/comment tasks
• examples/react_to_linear_events.py — webhook app launching idempotent runs
• examples/linear_mcp_server.py — MCP server for agents

Review pass

A follow-up commit fixes issues found while reviewing this branch.

Correctness

• dedupe_key now folds in the entity's updatedAt. Keyed on the entity alone, every Issue.update after the first collapsed onto the first one's key and never launched a run — the dedupe check treats a succeeded run as blocking, so this was permanent.
• team_id is resolved from the nested issue on Comment/Reaction payloads, which carry it only there. Without this the team_ids allowlist could not attribute any non-Issue event.

Robustness and security

• ⚠️ Behavior change: the team_ids allowlist now fails closed. Events it cannot attribute to a team are skipped rather than dispatched, matching the GitHub and Slack plugins. Previously an event with no team id bypassed the allowlist entirely.
• graphql() retries 429 with a clamped Retry-After, and logs its retries like the other plugins' clients do.
• Signatures compare as bytes. hmac.compare_digest raises TypeError on str operands containing non-ASCII, and the signature header is attacker-controlled: ASGI servers hand Starlette raw header bytes which it decodes as latin-1, so a crafted header turned a clean 401 into a 500.

Dashboard and docs

• The recent-events table read the 25 oldest events instead of the newest — [:25] on a deque that appends on the right — so it froze after the first 25 events.
• Allowlist values are HTML-escaped like every other interpolated value.
• The _dispatch module docstring said "Slack retries on non-2xx" (copy-paste from the Slack plugin).

5 new tests cover these.

Follow-up: async launching and label-only idempotency

launch_task no longer blocks the app's event loop. It and blocking_run are now async-first, wrapped with flyte's @syncify, so handlers await launch_task.aio(...). Previously the synchronous call stalled the whole event loop for the duration of two control-plane round-trips plus a launch — with every other in-flight webhook queued behind it, against sender timeouts measured in seconds. The synchronous form still works for scripts. A regression test asserts four concurrent launches overlap; against the old blocking call it measures 0.81s instead of 0.42s and fails.

Idempotency is now purely label-based. The run-name allocation is gone — it probed up to 32 candidate names via Run.get before launching under the winner. That raced with concurrent launches, silently capped how many runs one dedupe key could ever have, and treated a name as an identity it never was. Runs now carry only the dedupe=<key> label and the control plane assigns the name. run_name_for, RUN_NAME_MAX, and the prefix / run_name_base arguments are removed.

The dedupe key is explicitly caller-supplied. dedupe_key() is a sensible default, not a requirement — any string chooses a different idempotency scope.

The module docstring is also honest about the residual race: the label check is a read followed by a launch, so two simultaneous deliveries of one event can both launch. Redeliveries are seconds to minutes apart and dedupe reliably; closing the concurrent case needs a compare-and-set the control plane does not expose.

Follow-up: sync and async call forms on LinearClient

The 10 client methods are wrapped with flyte's @syncify, so each has two call forms — matching how the SDK itself exposes Run.listall, flyte.run, and flyte.serve:

# async: in `async def` tasks, webhook handlers, MCP tools
async with LinearClient() as client:
    result = await client.some_method.aio(...)

# blocking: in plain `def` tasks and scripts
with LinearClient() as client:          # note: `with`, not `async with`
    result = client.some_method(...)

__enter__/__exit__ were added so the blocking form is usable at all. They run __aenter__/__aexit__ on syncify's background loop — the same loop the syncified methods run on — so the httpx.AsyncClient is created and used on a single loop rather than straddling two.

Two call sites had to move to .aio() for correctness, not just style. Internal self. calls would otherwise deadlock, since syncify raises on a blocking call made from its own loop thread. And the MCP tool bridge (await getattr(client, name)(...)) would raise TypeError: object dict can't be used in 'await' expression on the returned value — and, had it not raised, would have stalled the MCP server's event loop for the duration of every tool call. Measured: 0 event-loop ticks during one blocking call.

The dynamic sync_*-method alternative was rejected: it works at runtime but both mypy and ty report "LinearClient" has no attribute "sync_..." and fall back to Any, so every typed caller breaks. @syncify in place resolves to SyncFunction[[...], ...] in both checkers. The package's mypy error count is unchanged at 12, all pre-existing, none in _client.py.

Tests, examples, and READMEs use .aio() on async paths and document both forms, including when not to reach for the blocking one.

Follow-up: typed event constants

on_event no longer needs hand-copied strings:

from flyteplugins.linear import events

@app_env.on_event(events.Issue.CREATE)
async def handle(event): ...

flyteplugins.linear.events adds 8 classes / 32 constants, following the ActionPhase pattern in flyte.models — str enums grouped by event type, so a member drops in wherever a pattern string is accepted and a typo fails at import rather than by silently never matching. events.Issue.ANY matches every action on the entity; events.Issue.CREATE matches one. Raw strings still work, for events the constants do not cover yet.

The enum base pins __str__/__format__ to str's. Without that, Python 3.11+ renders members as Class.MEMBER rather than the wire value — which would have leaked enum names into the dashboard and /api/status, since handler patterns flow into both.

Tests assert the constants equal what the parser actually produces (through the app's own _matches), that every ANY is the bare type its actions prefix, and that no value appears in two classes.

Follow-up: an end-to-end Testing guide

The README now ends with a numbered walkthrough against a real account, ordered so each step fails in isolation — exercise the client standalone before involving the platform, deploy the launched task before the app that looks it up, run it directly before any webhook is in play. Then wire up the provider, trigger a real event, and check the four places evidence lands: the provider's delivery log, /api/events, flyte get runs, and the resource itself. It ends with a troubleshooting table mapping each symptom to its cause, since 401, 503, and "200 but no run" are three different failures.

It also walks through the idempotency behaviour by hand, which is the part unit tests can only simulate.

Verified mechanically rather than by eye: every referenced example path resolves, every flyte create secret name matches the actual _config.py default, every flyte deploy <file> <env> names a real TaskEnvironment, every flyte run task is defined, and every example file still executes.