feat: Linear integration — attach issue context from the composer

[Gigioxx]

Problem

When working on a Linear ticket, there's no way to bring the ticket's context into a session — you copy/paste the title, description, and relevant comments by hand, and nothing links the session to the issue. Tools like conductor.build solve this with a first-class issue picker.

What this adds

Settings → Integrations (new section): connect a Linear workspace with a personal API key. The row follows the existing provider-row format (brand icon + status dot, Connected badge, "Connected as {user} · {org}"). Connect validates against Linear's API; malformed keys (lin_api_ prefix check) fail fast client-side.

Composer picker: a Linear button next to the model picker (rendered only when connected) opens a search popover. Opening it lists recently updated issues ("Recent"); typing switches to Linear's issue search. Selecting an issue attaches it as a chip; chips persist with the draft across reloads.

Prompt context: at send, each attached issue is serialized into the message as a <linear_issue> block (identifier, title, URL, state, priority/assignee/labels when present, description, up to 8 recent comments) with an explicit untrusted-content note and a 12k-char cap.

Design notes

• No new dependency — 3 read-only RPCs (linear.getStatus/searchIssues/getIssue) call Linear's GraphQL API directly through the existing Effect HttpClient pattern (modeled on BitbucketApi). All three are registered in RPC_REQUIRED_SCOPE (read scope).
• Key storage: the API key is written to ServerSecretStore — never to settings.json (the file holds only apiKeySet: true); legacy plaintext keys migrate to the secret store on server start. redactServerSettingsForClient blanks the key on every client-facing path; the UI reads connection state via linear.getStatus only.
• Prompt-injection hardening: Linear-authored text is sanitized so literal <linear_issue>/</linear_issue> delimiters in issue descriptions/comments cannot escape the untrusted block (defanged to ‹linear_issue…).
• Bounded persistence: payloads are truncated server-side (description 3000 chars, 8×800-char comments) and re-clamped client-side before landing in the localStorage-backed draft store, matching the element-context invariant.
• The composer plumbing mirrors the existing elementContexts pattern at every touchpoint (draft slice, persisted schema, chips, append-at-send), so no new mechanisms were introduced.

Verification

• tsgo --noEmit clean in contracts, server, client-runtime, web
• Server suite: 1423 passed | 7 skipped (includes a new secret-persistence test mirroring the provider-secret test)
• Web suite: 1335 passed (new: serializer tests incl. injection defusal, draft-store round-trip + clamp-on-add)
• Manual: connect/disconnect/reconnect cycles, invalid-key error state, picker recents + search, chip persistence across reload, <linear_issue> block in the outgoing message, plaintext-key migration verified on a real settings.json

Screen.Recording.2026-07-18.at.4.12.18.AM.mov

https://claude.ai/code/session_0128WBqER3f7gKnf13iUGcgD

---

Note

Medium Risk
Touches secret storage and non-atomic settings/secret updates for API keys, plus outbound prompt content from an external API; mitigated by rollback, redaction, and sanitization tests.

Overview
Adds a Linear integration so users can connect a workspace and attach issues to chat prompts without copy-pasting.

Server & contracts: New LinearApi calls Linear’s GraphQL API for getStatus, searchIssues, and getIssue, exposed as three read-scoped WebSocket RPCs. Shared types and errors live in @t3tools/contracts; the web app gets matching query atoms via @t3tools/client-runtime/state/linear.

API key handling: settings.json only keeps linear.apiKeySet; the real key is written to ServerSecretStore, with migration from legacy plaintext keys on startup and on settings reload. Updates defer secret commits until after the settings file write and roll back the linear placeholder if the secret write fails; unreadable secrets degrade to disconnected instead of failing all settings reads.

Settings UI: New Integrations section (/settings/integrations) to connect/disconnect with prefix validation and post-save status refetch.

Composer: When connected, a footer Linear picker searches or lists recent issues, fetches details, and adds removable chips. Drafts persist linearIssues like element context; on send, issues append as a bounded <linear_issue> block with an untrusted-context note and delimiter sanitization. Send failures restore attached issues; plan-implementation sends ignore linear context in v1.

^{Reviewed by Cursor Bugbot for commit 8f24593. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Linear integration to attach issue context from the composer

• Adds server-side LinearApi service with getStatus, searchIssues, and getIssue operations backed by the Linear GraphQL API, exposed as three new WebSocket RPC methods (linearGetStatus, linearSearchIssues, linearGetIssue).
• Stores the Linear API key in the secret store rather than settings.json; migrates any plaintext key found on disk at startup and rolls back the settings file if the secret write fails.
• Extends the composer draft store with a linearIssues slice supporting add (with deduplication and field clamping), remove, replace, and clear; issues are persisted and hydrated across sessions.
• Adds a ComposerLinearIssuePicker popover with debounced search and a ComposerPendingLinearIssues chip list to the ChatComposer; attached issues are serialized into a <linear_issue> block appended to the outgoing prompt in ChatViewContent.
• Adds an /settings/integrations route and IntegrationsSettings page where users can connect or disconnect Linear by entering a personal API key (validated against the lin_api_ prefix).
• Risk: Linear API key handling adds secret-store reads to every getSettings and streamChanges call; failures are silenced and degrade to a disconnected state rather than surfacing errors.

^{Macroscope summarized 8f24593.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 77bd62c1-3d3b-4dbe-ad35-e3a1f3077908

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a substantial new Linear integration feature with new API endpoints, UI components, settings page, and modifications to the message send path. New features of this scope require human review. Additionally, there's an unresolved bug report about Linear context potentially being omitted during send.

^{You can customize Macroscope's approvability policy. Learn more.}

[Gigioxx]

Addressed all six review findings in 32d0177:

• Send failure drops Linear chips (Bugbot): the failed-send restore path now snapshots and restores attached issues like the other contexts, and the emptiness guard includes them (new setLinearIssueContexts store action, with a round-trip test).
• Search without key guard (Bugbot): searchIssues/getIssue now fail with "Linear is not connected." on an empty key instead of sending a blank Authorization header.
• Auto-title ignores Linear chips (Bugbot): text-less first sends now seed the thread title from the first attached issue (IDENTIFIER title).
• Picker swallows search errors (Macroscope): RPC failures now show "Couldn't load Linear issues" instead of a misleading empty state.
• Secret written before settings persist (Macroscope, High): the secret-store mutation is now planned and committed only after writeSettingsAtomically succeeds, so a failed persist can't strand the previous key — covered by a new write-failure test (serverSettings.test.ts).
• Persisted id collision after reload (Macroscope): draft context ids now carry a random suffix (li_<counter>_<rand36>); the analogous pattern in elementContext.ts was left untouched as pre-existing code.

Suites after the fixes: server 1424 passed | 7 skipped, web 1337 passed; typechecks clean across contracts/server/client-runtime/web.

[Gigioxx]

Addressed the two follow-up findings in efffbae:

• Picker drops selection on getIssue failure (Macroscope): the popover now stays open with a "Loading issue details…" state until the fetch resolves; on failure it shows a retryable error instead of silently discarding the selection, with a double-select guard while one attach is in flight.
• Settings file written before secret store (Bugbot): since the two stores share no transaction, the fix is compensation rather than ordering — if the secret commit fails after the file write, updateSettings rolls settings.json (and the in-memory cache) back to the prior persisted state and surfaces the original error. Covered by an inverse write-failure test (secrets dir read-only → file must not retain apiKeySet: true).

Server suite: 1425 passed | 7 skipped; web suite green; typechecks clean.

[Gigioxx]

Addressed the latest round in 51a5559:

• Stale attach callbacks (Bugbot + Macroscope): the issue-attach fetch now uses a request-id counter mirroring the search path — closing the popover or selecting again invalidates any in-flight getIssue, so a canceled/superseded selection can never attach late or close a newer picker session.
• Combined-patch rollback divergence (Macroscope): the secret-commit-failure rollback now reverts only the linear placeholder ({ ...next, linear: current.linear }, re-normalized) instead of the whole previous settings object, so provider env-var secrets written earlier in the same patch stay consistent with their persisted placeholders. The pre-existing provider-secret flow is intentionally untouched.

Server 1425 passed | 7 skipped, web green, typechecks clean.

[macroscopeapp]

Effect Service Conventions: one finding in the new Linear service. See the inline comment on LinearApiError.

^{Posted via Macroscope — Effect Service Conventions}

[Gigioxx]

Latest round addressed in the newest commit:

• streamChanges catch scope (Macroscope, High): fixed at the source — materializeLinearApiKey now degrades to disconnected (with a warning) on a secret-store read failure instead of failing, so provider-secret materialization survives linear-only errors and getSettings (which had no catch at all) can no longer break over a linear problem. Its error channel is removed from the type. Covered by a new unreadable-secret test.
• LinearApiError conventions (Effect Service Conventions): single class kept, but message is now a getter derived from structured reason/status/detail/issueId fields; cause carries only real underlying failures — sentinel strings removed.
• Stale search after close (Macroscope): searchRequestRef is invalidated in the popover close branch, mirroring the attach-request invalidation.

Server 1426 passed | 7 skipped, web 1337 passed, typechecks clean.

[macroscopeapp]

One Effect service-convention issue remains around LinearApiError. The earlier feedback moved the message out of a stored Schema.String, but the revised shape still models several semantically distinct failures through a single reason discriminator whose values pick the user-facing message via a switch, and it copies raw wire payloads into a caller-visible detail field. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[Gigioxx]

Addressed both Effect Service Conventions follow-ups in c287754:

• Split the discriminated error: LinearApiError is now a Schema.Union of seven per-condition tagged classes (LinearNotConnectedError, LinearRequestError, LinearHttpError, LinearGraphqlError, LinearResponseDecodeError, LinearEmptyResponseError, LinearIssueNotFoundError), each deriving message from its own structured fields — mirroring BitbucketApiError's union + type alias + Schema.is guard exactly.
• No wire payloads in message-visible fields: detail is gone; the HTTP response body and the GraphQL errors array live only in cause, with status/issueId as the normalized diagnostics.

Typechecks clean across contracts/server/web; server suite 1426 passed | 7 skipped.

[Gigioxx]

Fixed the truncation off-by-suffix in the latest commit: truncate now reserves space for the … [truncated] marker (length derived from the constant), so descriptions/comments stay within the 3000/800 limits. The client-side truncateString already reserved correctly and is unchanged. Server suite 1426 passed | 7 skipped.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d243eed. Configure here.}

[cursor]

Send omits Linear context

Medium Severity

getSendContext reads linearIssues from render state while terminal and element attachments use refs synced for send. A send that runs before the imperative handle picks up the latest draft can omit attached issues from the outgoing message even though chips remain in the draft store until cleared.

 

^{Reviewed by Cursor Bugbot for commit d243eed. Configure here.}

[Gigioxx]

Addressed the latest Bugbot round in e29e269:

• Connect pending never clears + Transient status failure misreported: both traced to the same gap — the resolve effect only settled on a status.data identity change, and a failed refetch keeps the previous success value with the same identity (only error flips non-null). The effect now also settles when the refetch errors: pending always clears, connect failures surface "Invalid API key or connection failed" (which covers both an invalid key — itself an errored refetch via HTTP 401 — and a transient network failure) with the key still in the input for an easy retry, and a disconnect whose follow-up status read fails clears pending without a spurious error since the disconnect itself persisted.
• Watcher skips Linear key migration: the plaintext-key migration now runs after every watcher-driven settings reload as well as at startup, so a plaintext linear.apiKey reintroduced on disk mid-run (hand edit, backup restore, older client) is moved into the secret store promptly instead of lingering until the next restart. Added a test covering the migration seam (plaintext on disk → file rewritten with the placeholder, secret store holds the key).
• Send omits Linear context: not changed — linearIssues intentionally follows the same pattern as the two other draft-store-backed context types read right beside it (previewAnnotations, reviewComments): read from render state and included in the imperative-handle deps, so the handle is fresh every commit. The refs exist only for the pre-store context types that the send/restore path mutates imperatively. Attaching and sending are separate user events, so a send can't observe a pre-commit handle.

Verification: server suite 1431 passed | 7 skipped; web suite 1349 passed; all typechecks clean.

[Gigioxx]

Fixed the environment-switch state leak in 8f24593. The row is now keyed on the primary environment id, so switching environments remounts it — this resets not just the typed key, error, and pending state the finding calls out, but also the settle refs (latestDataRef/refreshedFromRef/resolveArmedRef), which an effect-based reset would have missed and which could otherwise let an armed in-flight connect resolve against the wrong environment's status. A persist already in flight when the switch happens still lands on the correct environment, since the handler captured its environment id at call time. Web suite 1349 passed, typecheck clean.