feat(linear): add Linear integration, with Slack review fixes

[isadeks]

Summary

• Linear integration (v1) — label-triggered task submission from Linear issues. Webhook → HMAC-verified receiver → async processor → standard task pipeline, with channel_source='linear'. Agent updates the originating Linear issue inline (comments, state transition, reactions) via Linear's hosted MCP server + a direct GraphQL client for reactions. Live demo: https://isadeks.github.io/abca-linear-demo/ (7 agent-authored PRs merged, site deployed per merge).
• Slack review fixes (addresses PR feat(slack): add Slack integration with @mention-based task submission #42 comments) — review-feedback commits for items 1-20, handler tests for all 7 Slack Lambdas, doc sync, softened checkChannelAccess. Originally on a separate local branch; folded into this PR per your preference for a single combined review surface.
• Upstream reconciliation — merged aws-samples/main to absorb Sam's PR feat(interactive-agents): async-only background task UX + Cedar HITL design #52 (FanOutConsumer) and adjacent changes. Resolved 13 conflicts across schema additions, construct wiring, agent pipeline ordering, and a flaky-test fix. Full test suite green post-merge (CDK 1121, agent 526, CLI 76).

Response to your #42 review concerns

Being honest about what Linear addresses vs. sidesteps:

Concern	Linear integration's relationship to it
DDB Streams max 2 consumers per table — 3rd adapter hits AWS limit	Didn't solve, didn't worsen. Linear adds zero stream consumers (uses agent-side MCP for outbound). Post-#52 state: SlackNotifyFn + FanOutConsumer = exactly 2/2 at the AWS limit. Structural fix still needs to happen, not in this PR — migrating SlackNotifyFn (from #42) into FanOutConsumer as a dispatcher subscriber would drop the count back to 1 and restore headroom. We deliberately held the line and didn't add a third.
Channel-filter logic duplicated inside each consumer	Didn't solve, didn't worsen. No Linear consumer exists to duplicate filter logic in. channelSource === 'linear' appears only in linear-webhook-processor.ts (one call site, one docstring). If a fourth channel ships as a stream consumer in the future, the duplication concern returns — but the #52 dispatcher pattern is the intended long-term shape for that; future channels should subscribe to it rather than add another filter-in-each-consumer.
Dedup logic duplicated across adapters	Addressed for Linear. Webhook-level dedup lives in linear-webhook.ts only, with key ${issueId}#${action}#${webhookTimestamp} (8h TTL, exceeds Linear's 7h retry horizon). No TaskRecord-level dedup extensions.
channel_metadata accumulates lifecycle state (e.g. slack_session_msg_ts)	Genuinely sidestepped. Zero linear_*_msg_ts fields on TaskRecord. All per-issue state (comments, state id, reaction id) lives in Linear itself, accessed at runtime via MCP + GraphQL. The container is the only place that touches Linear state; nothing is stashed on the record.

Architectural notes

Why MCP-based outbound instead of a FanOutConsumer subscriber. Linear ships a first-class MCP server (https://mcp.linear.app/mcp), so the agent can update the issue from inside the container using tools — same place the work is happening, no extra Lambda hop, no duplicated state. The fanout pattern is a better fit for ephemeral notifications (Slack thread updates, email) than stateful back-and-forth with a ticket (comment threads, state transitions, reactions that need the originating issue id).

Operationally: linear-integration.ts has zero stream consumers and zero outbound Lambdas. The only Lambdas are the webhook receiver, the async processor, and linear-link (CLI account linking). Everything user-visible happens in the agent container.

WAF scope-down on /v1/linear/webhook. Linear Issue webhook payloads routinely exceed the 8 KB body-size rule in AWSManagedRulesCommonRuleSet (observed 8614 bytes in smoke). Scoped the CRS out for this one path via scopeDownStatement. The route retains HMAC verification, webhookTimestamp replay guard (60s), JSON schema validation, webhook dedup, and the priority-3 rate-limit rule. AWSManagedRulesKnownBadInputsRuleSet remains unchanged.

Auto-link on bgagent linear setup. Linear identifies the API-key owner via viewer { id }, so we look up the caller's Cognito sub from the cached id_token and write the LinearUserMapping row directly. Fail-open on auth / network errors (secrets still get stored; user is told to re-run bgagent login). This closes the "now go paste bgagent link in a comment" dance for the common single-admin case.

v1 multi-user scope. Only the API-token owner can submit tasks from Linear in v1. Tasks triggered by other Linear users are dropped by the processor with "Linear actor has no linked platform user — skipping task creation". bgagent linear link <code> is registered as a CLI command but the Linear-side code generator isn't in v1 — OAuth bot install is the proper multi-user UX and will subsume any link-code bridge, so shipping the bridge didn't seem worth it. Constraint is documented in the setup guide.

In scope / out of scope

In this PR (v1 / shipped):

• Linear webhook + processor + link handler + two mapping tables (LinearProjectMappingTable, LinearUserMappingTable) + dedup table
• LinearIntegration CDK construct (zero stream consumers, zero outbound Lambdas)
• Agent-side Linear MCP loader (configure_channel_mcp, gated on channel_source='linear')
• Agent-side 👀/✅/❌ reactions via Linear GraphQL (retire when Linear MCP ships create_reaction)
• CLI: bgagent linear setup (+ auto-link), bgagent linear link, bgagent linear list-projects, bgagent linear onboard-project (+ UUID validation)
• Prompt addendum for the Linear MCP tools (save_comment, save_issue with graceful "no matching state" fallback)
• WAF scope-down + 8h dedup TTL + flaky test_server race fix
• Slack review fixes from your PR feat(slack): add Slack integration with @mention-based task submission #42 comments + handler tests for all 7 Slack Lambdas

Out of scope (planned follow-ups):

Band	What	Why parked
v1.1	Processor posts a Linear comment + ❌ when task creation fails pre-container (guardrail block, user concurrency cap, unmapped project) — today these drop silently on the Linear side.	Observed 3 distinct silent-failure cases during smoke; all share a single ~30 LOC fix. Worth shipping as a polish pass.
v1.1	Attachment pre-fetch to S3 for Linear tickets with images / mockups.	Linear MCP has attachment size limits; PMs attach screenshots routinely.
v2	Comment-triggered retry UX (/bgagent retry in a Linear comment) for partial-PR recovery.	Needs Comment webhook subscription + slash-command parser in processor.
v2	Auto-close Linear issue on PR merge.	Open design question first — merging ≠ solution accepted; post-merge tests may reveal issues. May be better done as a user-side GitHub Action than ABCA-side infrastructure.
v3	Cancel-from-Linear terminal feedback. bgagent cancel SIGKILLs the container, so Linear-side ❌ never fires from the agent's except.	Needs an orchestrator-side Linear client.
v3	OAuth bot install + multi-workspace support — replaces personal API key, enables any Linear user in the workspace to trigger tasks.	Current v1 uses a single personal API key (single submitter). The right fix when multi-user UX becomes a priority.

Validation

• Live site: https://isadeks.github.io/abca-linear-demo/ — 7 agent-authored PRs merged and deployed during validation.
• Test counts: CDK 1121 passing (was 853 pre-merge), agent 526 passing (was 306), CLI 76 passing. All green post-merge.
• Smoke tests run on the deployed stack:
  • WAF scope-down returns 401 (Lambda HMAC reject), not 403 (WAF block)
  • Dedup TTL ≥ 7h verified, distinct webhookTimestamp keys → no delivery collapse
  • UUID validation on onboard-project rejects the Linear-URL-slug form
  • Create-with-label-at-creation happy path (ABCA-3 → ABCA-22, 15+ runs)
  • Concurrent tasks don't cross-pollinate reactions
  • Unmapped-project silent drop (documents the v1.1 gap)
  • bgagent cancel mid-run (documents the v3 gap)
  • Post-merge Linear + Slack pipelines both working
• Architectural assertions on the deployed stack:
  • aws dynamodb describe-table --query 'Table.StreamSpecification' on TaskEventsTable — 2 consumers (SlackNotifyFn + FanOutConsumer); Linear adds 0.
  • grep -rn "channelSource === 'linear'" cdk/src/handlers/ — only in linear-webhook-processor.ts.
  • TaskRecord has no linear_*_msg_ts fields.

Test plan for reviewer

1. mise //cdk:deploy — CFN diff should add only LinearIntegration/* resources on top of current aws-samples/main. Slack beyond Lambda bundle refreshes should not change.
2. Generate a Linear personal API key at https://linear.app/settings/account/security.
3. Run bgagent linear setup. It prints the webhook URL, pauses at the signing-secret prompt. Create a webhook in Linear at that URL (subscribe to Issue), copy the signing secret, return to the terminal and paste secret + API key. Auto-link fires for the token owner; success message: ✓ Linked Linear user … → platform user ….
4. bgagent linear list-projects → copy the target project UUID.
5. bgagent linear onboard-project <uuid> --repo <your-fork>/<demo-repo> --label abca.
6. Create a Linear issue with the abca label applied at creation time.
7. On the Linear issue, within ~30s: 👀 reaction, 🤖 Starting… comment, PR opens, state → In Review, 👀 swaps for ✅ when the PR URL comment is posted and the task finishes.
8. Merge the PR — site / deploy workflow runs normally.

Closes #42.

[krokoko]

Feedback from automated review:

Required before merge

#: 1
Issue: Dedup row persists after Lambda invoke failure — all Linear retries (+1m,+1h, +6h) fall within the 8h TTL, silently dropping the task forever if invoke keeps failing
Location: cdk/src/handlers/linear-webhook.ts ~L135
Fix: Delete the dedup row in the invoke-error catch block, or move the write to
after successful invocation
────────────────────────────────────────
#: 2
Issue: CLI/CDK ChannelSource type drift — CDK updated to 'api' | 'webhook' |
'slack' | 'linear' but cli/src/types.ts:30 still has 'api' | 'webhook'
Location: cli/src/types.ts
Fix: Add 'slack' | 'linear' to the CLI union

Recommended follow-ups (v1.1)

• Processor feedback on pre-container failures — when createTaskCore returns
  non-201, post a Linear comment explaining why (3 silent-failure cases observed
  during smoke)
• Escalation on persistent Linear auth failure — linear_reactions.py logs WARN
  forever on revoked tokens; add error escalation after N consecutive failures
• Replace locals().get("linear_eyes_reaction_id") with explicit
  linear_eyes_reaction_id = None initialization before the try block
• Narrow except Exception in resolve_linear_api_token to botocore errors; switch
  from print() to shell.log()
• Auto-link fallback path — if auto-link fails, the suggested bgagent linear
  link requires a code the user cannot generate in v1; clarify the
admin-assisted path

What's done well

• MCP-based outbound is the right topology — avoids the 2-consumer DDB Streams
  limit, keeps per-issue state in Linear (not channel_metadata), eliminates a
  Lambda notification hop
• Dedup key design (issueId#action#webhookTimestamp, 8h TTL) correctly exceeds
  Linear's 7h retry horizon and collapses retries while allowing distinct events
• WAF scope-down is properly scoped (EXACTLY match, not prefix) and the route
  retains HMAC + replay guard + rate limiting
• Security posture — timing-safe HMAC comparison with rotation-retry, 60s replay
  window, no secrets logged, IAM least-privilege throughout
• Slack review response is thorough — 20 items addressed with regression tests
  that fail the pre-fix code
• Test growth (CDK 853→1121, agent 306→526, CLI 76) with construct-level,
  handler-level, and integration-style coverage

[krokoko]

Just adding as a follow up: will open an issue after to use AgentCore gateway

The current approach isn't wrong — it's a conscious shortcut for v1. But as the project adds more external MCP integrations, the .mcp.json injection pattern doesn't scale. The Gateway is the project's stated integration point for external tools, and Linear should converge on it.

[isadeks]

Thanks for the thorough review — both blockers fixed in 7d652a4.

#1 — Dedup row on invoke failure. Agreed this is a silent-drop trap; the 8h TTL fully swallows Linear's +1m/+1h/+6h retry horizon. Fix was the "delete on invoke-error" shape (not "write after invoke") — keeping the write before invoke preserves the dedup guarantee for the common case where a retry races an in-flight ack. Added two regression tests: one asserts the DeleteCommand fires with the exact dedup key on invoke failure, one asserts we still return 500 (not swallow the invoke error) if the rollback itself fails. Patch: cdk/src/handlers/linear-webhook.ts ~L158-L178.

#2 — CLI ChannelSource drift. Widened cli/src/types.ts:30 to 'api' | 'webhook' | 'slack' | 'linear' and refreshed the jsdoc to mirror cdk/src/handlers/shared/types.ts. CLI compile clean, 196 CLI tests green.

v1.1 follow-ups — all five parked in our internal backlog and slotted for the v1.1 pass:

• Processor posts a Linear comment on pre-container failures (already the top v1.1 item — this is what the "parked v1.1" row in the PR body calls out)
• Escalation on persistent Linear auth failure in linear_reactions.py
• Explicit linear_eyes_reaction_id = None init instead of locals().get()
• Narrow except Exception → botocore in resolve_linear_api_token + print() → shell.log()
• Admin-assisted fallback documentation for auto-link failures

AgentCore Gateway note — acknowledged. Convergence on Gateway as the MCP integration point makes sense as the project adds more external MCPs; happy to pick that up as a follow-up once the issue lands.

Full test counts post-fix: CDK 1170 (+2 rollback tests), agent 526, CLI 196 — all green.