Repository navigation
feat(team-relay): Linear issue feed on the existing event rails - #69
Conversation
Emits the same event shape webhook-server.mjs produces, so Linear issues reach CodeWatch the way GitHub PRs already do and no consumer needs a special case. Polls rather than taking a webhook, deliberately: a webhook needs a stable public URL, and this fleet's tunnel URL rotates on every restart, so the hook would die silently at each rotation and nobody would notice until issues stopped arriving. Polling owns its liveness and a failed poll shows up in the log at once. Issue tracking does not need sub-minute latency. Read-only by construction: it holds a key and never calls a mutation. The token is read from a file (~/.config/linear.token by default), never from config or argv, because the precommand gate has echoed a command into the room and leaked a key exactly that way. A path is safe to commit; a key is not. Missing token disables the feed instead of failing the relay, since most installs have no Linear at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ThinkOffApp
left a comment
There was a problem hiding this comment.
Adversarial review findings:
-
Blocking: the poller is not wired into the live relay or CLI. This PR adds
src/team-relay/linear-poller.mjsand tests only; no import orstartLinearPoller(...)call appears insrc/team-relay/webhook-server.mjs,src/team-relay/index.mjs, or the CLI. A merged PR would pass its unit tests but emit no Linear events in production. -
The created-versus-updated heuristic is not reliable.
createdAt === updatedAtis an implementation detail, and Linear can assign distinct timestamps during creation. Conversely, an update can preserve or normalize timestamps in ways that make equality misleading. Query the issue event/activity or use a persisted seen-id cursor if the distinction matters. -
actor.loginis populated from assignee, then creator. Neither is the actor who changed the issue. The emitted event can attribute a Petrus assignment or creator to the person who performed a later edit. The query needs the actual activity actor, or the event contract should call this field something else.
The cursor retry behavior looks sound for consumer exceptions, and missing-token disablement is reasonable. I would fix the production wiring before merge and add tests for the timestamp and actor semantics.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c38c5550f7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| return { cursor, count: nodes.length }; | ||
| } | ||
|
|
||
| export function startLinearPoller(config = {}, onEvent) { |
There was a problem hiding this comment.
Wire the poller into a production entry point
The new poller is unreachable in every production path: a repo-wide reference search finds startLinearPoller only in this module and its test, while ide-agent-kit serve starts only startWebhookServer and src/team-relay/index.mjs does not export the poller. Consequently, placing a Linear token at the documented default path never starts polling, so this feature emits no events until it is integrated with a long-running command and the event queue.
Useful? React with 👍 / 👎.
| return { | ||
| trace_id: randomUUID(), | ||
| source: 'linear', |
There was a problem hiding this comment.
Preserve the issue ID in normalized events
Add event_id: issue.id to this object. schemas/event.normalized.json requires event_id as the inbound event's idempotency key, and every existing normalized adapter supplies it; omitting it makes Linear events violate that contract and leaves downstream processing unable to identify or deduplicate retries of the same issue update.
Useful? React with 👍 / 👎.
| issues( | ||
| filter: { updatedAt: { gt: $since } } | ||
| orderBy: updatedAt | ||
| first: $first | ||
| ) { |
There was a problem hiding this comment.
Page before advancing the timestamp cursor
When more than first matching issues exist, this query discards the connection's pagination information and pollOnce advances directly to the greatest returned updatedAt. For example, if 51 issues from a bulk operation share timestamp T, the first 50 are emitted, the cursor becomes T, and the next poll's updatedAt > T filter permanently excludes the remaining issue; consume all pages with an after cursor before advancing the time cursor.
Useful? React with 👍 / 👎.
ThinkOffApp
left a comment
There was a problem hiding this comment.
Adversarial review: request changes before merge.
-
src/team-relay/linear-poller.mjs:36sendsAuthorization: Bearer ${token}, but this code and the PR describelinear.tokenas a personal API key. Linear's API docs require personal keys asAuthorization: <API_KEY>;Beareris for OAuth access tokens. As written, the documented/default installation will get 401s on every poll. Either send the personal key raw or make the credential type explicit and test both paths. The claimed live smoke test should be reproduced with the exact token-file path and header. -
src/team-relay/linear-poller.mjs:123-125uses only a timestamp cursor with a strictupdatedAt > sincefilter. If more than 50 issues share the page-boundary timestamp, or two issues have the same timestamp as the last emitted issue, the next poll skips the remainder forever. Use a stable(updatedAt, id)cursor or ensure pagination includes timestamp ties, and add a regression test.
The created-vs-updated equality heuristic is acceptable only if the API contract guarantees identical creation timestamps; please add a fixture/test for a newly-created issue whose timestamps differ in precision or document that invariant. CI is green, but these runtime cases are not covered.
…erve Both found by @codexmb reviewing #69, and both were real. 1. actor.login was taken from assignee then creator, neither of which is who made the change. An issue assigned to Petrus and edited by an agent was attributed to Petrus, and 'who did what' is the entire reason this feed exists. Linear's issue history would carry the true actor but comes back empty for issues created through an API token, so it cannot be relied on. A created issue now credits its creator, which is genuinely the actor. An update reports 'unknown' rather than a plausible lie, and assignee and creator travel in the payload labelled as what they actually are. 2. startLinearPoller was exported and called by nothing. Merging as it stood would have shipped a feed that emitted no events. It is now started from alongside the webhook server, sharing the same onEvent, and a test asserts the wiring so this cannot silently regress. Also covered: the cursor stays put when a consumer throws, so the issue is retried rather than lost. 11 tests, all passing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Follow-up after 1e93472: the personal-key header and live wiring findings are fixed. The timestamp cursor issue remains: The current 18.x check is still running; 20.x and 22.x pass. |
Found by @codexmb on #69. The cursor is a timestamp and the filter is strictly updatedAt > cursor, so stopping at a page boundary excluded any issue sharing that last timestamp from the NEXT poll as well. Those issues were lost permanently, not merely delayed: one bulk edit touching more than a page of issues in the same second would silently drop the remainder. pollOnce now follows pageInfo.hasNextPage to exhaustion, so the cursor only lands past a timestamp whose issues have all been emitted. maxPages is a runaway guard rather than a limit; if it trips the cursor holds at the last fully-emitted position and the next tick resumes instead of skipping. Adds regression tests for the tied-boundary case, the maxPages guard, and the created-vs-updated timestamp invariant. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Puts Linear issues on the rails GitHub PRs already ride, so they reach CodeWatch without any consumer needing a special case.
What it does
startLinearPoller(config, onEvent)emits the same event shapewebhook-server.mjsproduces:{trace_id, source, kind, timestamp, actor, refs, payload}. Kinds arelinear.issue.createdandlinear.issue.updated.Why polling, not a webhook
A webhook needs a stable public URL. This fleet reaches the outside through a tunnel whose URL rotates on every restart, so the hook would die silently at each rotation and nobody would notice until issues quietly stopped arriving — we already live with that failure mode elsewhere. Polling owns its own liveness: no inbound URL, nothing to re-point, and a failed poll is in the log immediately. Issue tracking does not need sub-minute latency, so the trade costs nothing that matters.
Safety
~/.config/linear.tokenby default). The precommand gate has echoed a command into the room and leaked a key exactly that way. A path is safe to commit; a key is not.Verification
node --test test/linear-poller.test.mjs).updated; THI-16/18/19 ascreated).webhook.test.mjssuite still passes (4/4).Not included
Chaining a Linear state change to a PR merge. That is a write action against GitHub and wants an explicit decision plus gating (linked PR, mergeable, CI green, explicit "Merge approved" state) — deliberately out of scope here.
🤖 Generated with Claude Code