feat(agentex): Linear gateway — invoke agents from Linear

[michael-chou359]

What

A platform-side ingress that fronts a Linear agent app and routes each @mention / assignment to the resolved agent runtime — the Linear analog of the Slack gateway (#388 / #392 / #394).

How it works

• POST /linear/events — verifies the Linear-Signature (HMAC-SHA256 over the raw body) + a webhookTimestamp freshness guard, dedups on the Linear-Delivery id, acks fast (Linear's ~10s window), and runs the turn in the background. Auth-whitelisted like /slack — Linear can't present an SGP principal, so the signature is the auth, verified in the use case.
• Normalize AgentSessionEvent (created / prompted) → the same selector-cascade + task/create-or-event/send dispatch as the Slack gateway, keyed on the agent session (task_metadata.channel = "linear").
• Reply via agentActivityCreate — a thought immediately (a session is marked unresponsive without an activity within ~10s), then a terminal response / error. The Linear API token is minted via the OAuth client_credentials grant (inherently app-actor) and re-minted reactively on a 401 — no perishable token is stored, only the static client id/secret in env.
• Removes a duplicate slack.router registration in app.py.

Identity

Runs as a dedicated bot service account (its own SGP identity), not a proxy for the invoking Linear user — consistent with the Slack gateway's identity model. Its comments/activities render as the app (actor=app).

Config (env / k8s-secret)

LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET, LINEAR_WEBHOOK_SIGNING_SECRET, LINEAR_GATEWAY_ACTING_BOT_API_KEY, LINEAR_GATEWAY_ACCOUNT_ID.

Testing

• 20 unit tests: signature verify, normalize (created / prompted / ignored), event control-flow (dev-skip / drop / dedup / ack), acting-identity fail-closed, dispatch metadata, and agentActivityCreate token-mint + 401 re-mint. All pass, ruff clean.
• Signed ingress round-trip verified over HTTP; client_credentials token mint verified against the live Linear API (app-actor confirmed via viewer).
• The full agent round-trip (posting an activity to a real session) validates post-deploy with a real @mention — a fabricated session can't be tested locally.

🤖 Generated with Claude Code

Greptile Summary

The PR adds a Linear webhook gateway that authenticates and deduplicates session events, dispatches them to Agentex runtimes under a dedicated bot identity, and returns activities through Linear’s API.

• Registers and documents POST /linear/events.
• Normalizes Linear session events and creates or resumes session-bound Agentex tasks.
• Adds OAuth token minting, reactive refresh, activity delivery, and unit coverage.
• Removes the duplicate Slack router registration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
agentex/src/domain/use_cases/linear_gateway_use_case.py	Implements signature verification, event normalization, deduplication, bot identity resolution, runtime dispatch, reply collection, and Linear activity delivery; the displayed prior findings are fixed or explicitly accepted.
agentex/src/api/routes/linear.py	Adds the thin /linear/events ingress that preserves the raw request body for signature verification.
agentex/src/api/middleware_utils.py	Whitelists the Linear route from principal authentication so webhook signature verification serves as its ingress authentication.
agentex/src/api/app.py	Registers the Linear router while removing the duplicate Slack router registration.
agentex/tests/unit/use_cases/test_linear_gateway_use_case.py	Covers authentication, normalization, control flow, acting identity, dispatch metadata, token minting, and token refresh behavior.
agentex/openapi.yaml	Documents the new Linear webhook endpoint and successful response schema.

Sequence Diagram

sequenceDiagram
    participant L as Linear
    participant R as POST /linear/events
    participant G as LinearGatewayUseCase
    participant D as Dedup Store
    participant A as Agentex Runtime
    participant API as Linear API
    L->>R: Signed AgentSessionEvent
    R->>G: Raw body, headers, payload
    G->>G: Verify HMAC and timestamp
    G->>D: Reserve delivery ID
    G-->>L: 200 acknowledgment
    G->>API: Create thought activity
    G->>A: Create/resume task and send event
    A-->>G: Agent response
    G->>API: Create response or error activity

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into mc/linear-gatew..." | Re-trigger Greptile}

[github-actions]

✱ Stainless preview builds

This PR will update the agentex-sdk SDKs with the following commit messages.

openapi

feat(api): add linear events webhook endpoint

python

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

✅ agentex-sdk-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ agentex-sdk-typescript studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

⚠️ agentex-sdk-python studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-10 16:42:36 UTC

[greptile-apps]

Concurrent Turns Mix Their Replies

If two distinct deliveries for one Linear session overlap, both turns snapshot and poll the same task without event-level correlation, causing either poller to collect the other prompt's agent messages and emit swapped, combined, or duplicated responses.

Prompt To Fix With AI

This is a comment left during a code review.
Path: agentex/src/domain/use_cases/linear_gateway_use_case.py
Line: 475-481

Comment:
**Concurrent Turns Mix Their Replies**

If two distinct deliveries for one Linear session overlap, both turns snapshot and poll the same task without event-level correlation, causing either poller to collect the other prompt's agent messages and emit swapped, combined, or duplicated responses.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[michael-chou359]

Valid but inherited — documented in 88283a5. Reply attribution is by message-id snapshot, the same interim design the Slack gateway ships with (see _collect_reply), so two prompts racing on the same session can interleave. Linear sessions are sequential in practice (prompt → wait → prompt), so the window is narrow. A real fix is event-correlated streaming, which is a cross-gateway change tracked as the shared follow-up — not something to diverge on in this PR. Added a note to the _collect_reply docstring.