@kana-ai/edgar-ext-linear 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +198 -2
  3. package/dist/src/api/client.d.ts +21 -0
  4. package/dist/src/api/client.js +53 -0
  5. package/dist/src/api/failures.d.ts +11 -0
  6. package/dist/src/api/failures.js +37 -0
  7. package/dist/src/index.d.ts +3 -0
  8. package/dist/src/index.js +19 -0
  9. package/dist/src/schemas/config.d.ts +25 -0
  10. package/dist/src/schemas/config.js +37 -0
  11. package/dist/src/schemas/linear.d.ts +116 -0
  12. package/dist/src/schemas/linear.js +57 -0
  13. package/dist/src/schemas/tools.d.ts +169 -0
  14. package/dist/src/schemas/tools.js +147 -0
  15. package/dist/src/tracker/assignee.d.ts +15 -0
  16. package/dist/src/tracker/assignee.js +58 -0
  17. package/dist/src/tracker/cards.d.ts +33 -0
  18. package/dist/src/tracker/cards.js +372 -0
  19. package/dist/src/tracker/comments.d.ts +11 -0
  20. package/dist/src/tracker/comments.js +62 -0
  21. package/dist/src/tracker/description.d.ts +19 -0
  22. package/dist/src/tracker/description.js +55 -0
  23. package/dist/src/tracker/hand-back.d.ts +8 -0
  24. package/dist/src/tracker/hand-back.js +94 -0
  25. package/dist/src/tracker/port.d.ts +2 -0
  26. package/dist/src/tracker/port.js +46 -0
  27. package/dist/src/tracker/states.d.ts +21 -0
  28. package/dist/src/tracker/states.js +82 -0
  29. package/dist/src/tracker/tools.d.ts +142 -0
  30. package/dist/src/tracker/tools.js +130 -0
  31. package/dist/src/tracker/transitions.d.ts +13 -0
  32. package/dist/src/tracker/transitions.js +94 -0
  33. package/edgar-extension.json +208 -0
  34. package/package.json +41 -3
  35. package/schemas/assign.in.json +15 -0
  36. package/schemas/assign.out.json +14 -0
  37. package/schemas/batch_cards.in.json +27 -0
  38. package/schemas/batch_cards.out.json +37 -0
  39. package/schemas/close.in.json +14 -0
  40. package/schemas/close.out.json +10 -0
  41. package/schemas/comment.in.json +19 -0
  42. package/schemas/comment.out.json +10 -0
  43. package/schemas/config.json +94 -0
  44. package/schemas/count_sighting.in.json +17 -0
  45. package/schemas/count_sighting.out.json +10 -0
  46. package/schemas/create_card.in.json +108 -0
  47. package/schemas/create_card.out.json +13 -0
  48. package/schemas/find_assignee.in.json +15 -0
  49. package/schemas/find_assignee.out.json +10 -0
  50. package/schemas/find_cards.in.json +18 -0
  51. package/schemas/find_cards.out.json +33 -0
  52. package/schemas/find_description.in.json +15 -0
  53. package/schemas/find_description.out.json +10 -0
  54. package/schemas/hand_back.in.json +11 -0
  55. package/schemas/hand_back.out.json +18 -0
  56. package/schemas/move.in.json +15 -0
  57. package/schemas/move.out.json +10 -0
  58. package/schemas/release_follow_ups.in.json +15 -0
  59. package/schemas/release_follow_ups.out.json +13 -0
  60. package/schemas/restore_assignee.in.json +20 -0
  61. package/schemas/restore_assignee.out.json +10 -0
  62. package/schemas/restore_description.in.json +20 -0
  63. package/schemas/restore_description.out.json +10 -0
  64. package/schemas/update_description.in.json +15 -0
  65. package/schemas/update_description.out.json +14 -0
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 Kana.ai
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
202
+
package/README.md CHANGED
@@ -1,3 +1,199 @@
1
- # Temporary Holding Version
1
+ # @kana-ai/edgar-ext-linear
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Linear extension of EDGAR. It implements the engine's tracker port over Linear's GraphQL API, and the tools the default workflows call as `tracker__<tool>`, a name the engine gives the tracker of each card, so they run here as `linear__<tool>` for a card from Linear.
4
+
5
+ ## Tracker port
6
+
7
+ All 11 methods: `list_cards`, `card`, `comments`, `attachments`, `comment`, `move`, `set_labels`, `create_card`, `close`, `whoami` and `person`. A card's `id` is its Linear identifier, such as `ENG-12`, and its `column` is the engine state its Linear column maps to. Its `assignee` is the Linear `displayName` of the person the issue is assigned to, and a card with no assignee has no `assignee`. The display name is the name Linear shows and a person writes after `@`, so a note or a prompt can name the person; an email would put an address that a person never reads into each agent's input and each Slack note. `list_cards` takes engine states in `columns`, the way the engine's sweep sends them, asks Linear for the columns `[extensions.linear.columns]` maps them to, and answers each card with its engine state. A name that is not an engine state, such as `Todo`, makes `list_cards` answer `invalid` with that name in `cause`, before any request. For example, with `ready = "Todo"`, the request `{"columns": ["intake", "ready"], "cursor": null}` asks Linear for `Triage` and `Todo`, and a card in `Todo` comes back with `"column": "ready"`. `list_cards` reads 50 cards a page and reports `budget_remaining` from `X-RateLimit-Requests-Remaining`. `comments` sets `mentioned` when the body holds `@` and the display name of the `whoami` actor.
8
+
9
+ ## Tools
10
+
11
+ | Tool | Input | Output | Notes |
12
+ | --------------------- | --------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | `comment` | `card`, `text`, `link` (optional) | `id` | The link goes on its own line. |
14
+ | `move` | `card`, `column` | `column` | `column` is an engine state. Forward only, except that a card in `waiting_on_person` moves to any other column; a move back, to the same column, or from or to a column the mapping does not name is `skipped`. A move to any column but `waiting_on_person` takes the label `edgar:waiting` off. |
15
+ | `close` | `card`, `reason` | `state` | Moves the card to the `done` column from any column, and takes the label `edgar:waiting` off. |
16
+ | `create_card` | `spec`, `parent` (optional) | `id`, `url` | Returns the open card that already holds the block's fingerprint, and files nothing then. It raises that card's `occurrences` by one and sets its `last_seen` to the sighting's, or to now; a sighting no newer than the card's `last_seen`, as a retry is, writes nothing. A count that Linear refuses for good goes to the runtime log and the card is still the answer; a count write that can work again is a temporary failure, so the engine runs the call again. Two calls with one fingerprint run one at a time in the extension's process, so the second finds the card the first filed. |
17
+ | `count_sighting` | `card`, `seen_at` (optional) | `id` | Counts one more sighting on the card `card`: raises `occurrences` and moves `last_seen` to `seen_at`, else now, in the card's block. A sighting no newer than `last_seen` writes nothing, so a retry counts once. A card with no block is left as it is; a card that Linear does not have is `not_found`. A write that Linear refuses for good goes to the runtime log. |
18
+ | `batch_cards` | `batch`, `except`, `only` | `cards`, `skipped` | The other open cards of the table's team and scope (with `assignee_only`, only the cards of `assignee` or labelled `edgar:waiting`) whose block holds `batch` in `decided.batch`, such as the scanner cards of one repository: at most 20, each with `id`, `title`, `url` and `description`. The card `except` is left out, and so is a done or canceled card, and a card whose description holds the text but whose block does not name the batch. Read-only. With `only`, just those ids, and `skipped` lists the ids of `only` that are not open cards of the batch. |
19
+ | `find_cards` | `text`, `except` (optional) | `cards` | Searches the open cards of the table's team and scope (`project`, `title_prefix`, `labels`, and with `assignee_only` only the cards of `assignee` or labelled `edgar:waiting`) with Linear's `searchIssues`, which matches words and meaning, and answers at most 10, the best match first: `id`, `title`, `url`, `state` (the engine state, else the Linear column name) and `created_at`. A done or canceled card is left out. With `except`, that card and each card made after it are left out, so two new cards never name each other; a card `except` that Linear does not have is `not_found`. `text` holds 1 to 1,024 characters. Linear allows 30 searches a minute. Read-only. |
20
+ | `release_follow_ups` | `card`, `pull_request` | `released` | Moves each card in the `intake` column whose block has `waits_for = "<card>"` to `ready`. Follow-up cards wait in `intake`. |
21
+ | `update_description` | `card`, `description` | `id`, `previous` | Replaces the card's description and keeps its `edgar:v0` block, so the fingerprint and `waits_for` stay. `previous` is the description before the write. A description that already reads so is not written again. Side effect, undone by `restore_description`, found by `find_description`. |
22
+ | `restore_description` | `stage_output`: `id`, `previous` | `id` | Writes `previous` back as the description, with the card's current `edgar:v0` block, so a count made since stays. The engine calls it with the output of the `update_description` call that it undoes. |
23
+ | `find_description` | `card`, `description` | `id` | `done` when the description already is what `update_description` writes for that text, else `skipped`. Boot asks it about a call that did not end. |
24
+ | `assign` | `card`, `user` | `id`, `previous` | Assigns the card to the user with that email or id, to the user of `LINEAR_TOKEN` for `me`, or to nobody for an empty `user`. `previous` is the id of the assignee before the write, and an empty text when the card had none. A card that already has that assignee is not written again. A user that Linear does not have is `not_found`. Side effect, undone by `restore_assignee`, found by `find_assignee`. |
25
+ | `restore_assignee` | `stage_output`: `id`, `previous` | `id` | Sets the assignee back to the user `previous`, or to nobody for an empty `previous`. The engine calls it with the output of the `assign` call that it undoes. |
26
+ | `hand_back` | `card` | `id`, `to`, `previous` | Assigns the card to the person who asked for the work, and adds the label `edgar:waiting`. That person is the newest one in the card's history who assigned it to EDGAR's user, else the card's writer. EDGAR's user (the user of `LINEAR_TOKEN`, and `assignee`), an app and a bot are never chosen. `to` is the person's display name, and `previous` the id of the assignee before, or an empty text. A card that nobody can be given, such as a card that EDGAR filed and nobody handed over, is `skipped`. The label is the workspace's `edgar:waiting` or the one of the card's team, never another team's, which Linear refuses on the card; when neither exists, it is made in the card's team. A card that already has that person and the label is not written again. |
27
+ | `find_assignee` | `card`, `user` | `id` | `done` when the card already has the assignee that `assign` sets for that `user`, else `skipped`. Boot asks it about a call that did not end. |
28
+
29
+ A write that creates something sends an id derived from the operation id. A repeat of the same operation that fails looks that id up and returns what the first call made.
30
+
31
+ ### Replace a description
32
+
33
+ A stage replaces the text of card `ENG-12`, whose description is `Users wait 30 s.` and its block:
34
+
35
+ ```toml
36
+ [stages.describe]
37
+ tool = "linear__update_description"
38
+ input = { card = "trigger.card.id", description = "stages.analyze.output.summary" }
39
+ compensate = "linear__restore_description"
40
+ ```
41
+
42
+ The tool reads the card, writes the new text with the old block at its end, and answers:
43
+
44
+ ````json
45
+ {
46
+ "outcome": "done",
47
+ "output": { "id": "ENG-12", "previous": "Users wait 30 s.\n\n```toml edgar:v0\n..." }
48
+ }
49
+ ````
50
+
51
+ A retry after a lost answer reads the card again, finds the same text, writes nothing and answers `done` with no `previous`, because the retry cannot know what the lost call replaced. A card with no block gets the text as it is. A card that does not exist is `not_found`. If boot settles a call through `find_description`, its output has no `previous` either. An undo of a call with no `previous` writes nothing and answers `done`, so a workflow that writes the same description on each pass does not stop the undos behind it; it never empties a description and never writes the new text over itself. Known limit: after a retry whose first answer was lost, the undo leaves the new text on the card.
52
+
53
+ ### Assign a card
54
+
55
+ A stage gives card `ENG-12`, which is assigned to the user `u-ana`, to the person who reviews the change:
56
+
57
+ ```toml
58
+ [stages.hand_over]
59
+ tool = "linear__assign"
60
+ input = { card = "trigger.card.id", user = "stages.review.output.reviewer_email" }
61
+ compensate = "linear__restore_assignee"
62
+ ```
63
+
64
+ The tool reads the card, finds the user and writes the new assignee. It answers:
65
+
66
+ ```json
67
+ { "outcome": "done", "output": { "id": "ENG-12", "previous": "u-ana" } }
68
+ ```
69
+
70
+ `user` is an email, a Linear user id, `me` for the user of `LINEAR_TOKEN`, or an empty text, which takes the assignee off. A user is found one time for the life of the runtime: an email by `users`, an id by `user`, `me` by `viewer`. An email or an id that the workspace does not have is `permanent_failure(not_found)` with the message `linear: no user <user>`, and nothing is written. A card that does not exist is `not_found`. A retry after a lost answer reads the card again, finds that assignee, writes nothing and answers `done` with no `previous`. An undo of a call with no `previous` writes nothing. An undo with an empty `previous` takes the assignee off, because the card had none before the call. Known limit: after a retry whose first answer was lost, the undo leaves the new assignee on the card.
71
+
72
+ With `assignee_only = true`, a card that this tool assigns to another user leaves EDGAR's scope at the next sweep, and the engine stops the run that works on it, with its work kept. Use that to hand a card over to a person. Do not use it in the middle of a workflow that must go on.
73
+
74
+ ## The card block
75
+
76
+ A card carries one fenced block in its description:
77
+
78
+ ````md
79
+ ```toml edgar:v0
80
+ kind = "defect"
81
+ service = "api"
82
+ fingerprint = "0123456789abcdef"
83
+ first_seen = 2026-11-01T08:00:00Z
84
+ waits_for = "ENG-7"
85
+ ```
86
+ ````
87
+
88
+ `kind` is required. The block and card schemas come from `@kana-ai/edgar-contracts/card`, which the demo and GitHub extensions also use. The extension reads and writes the block with the card block helpers of `@kana-ai/edgar-sdk`. `card` answers `not_found` for an issue that Linear has archived or put in the trash, because Linear still reads such an issue by its id. A fingerprint of 16 or more hex characters is lowercased and cut to 16. A block that is not TOML or fails the schema makes `card` answer `invalid` with the line or the fields in `cause`; `list_cards` gives that card `block = null`.
89
+
90
+ ## Configuration
91
+
92
+ ```toml
93
+ [extensions.linear]
94
+ team = "ENG" # the team key
95
+ project = "Platform" # optional
96
+ title_prefix = "[edgar]" # optional
97
+ labels = ["edgar"] # optional
98
+ assigned = ["Backlog"] # optional: columns where a card assigned to `assignee` counts as intake
99
+ assignee = "edgar@shop.example" # optional: a Linear user id, an email, or "me"; the default is "me", the user of LINEAR_TOKEN
100
+ assignee_only = true # optional, default false: only the cards assigned to `assignee` are in scope
101
+
102
+ [extensions.linear.columns] # every engine state, required
103
+ intake = "Triage"
104
+ ready = "Todo"
105
+ working = "In Progress"
106
+ in_review = "In Review"
107
+ waiting_on_person = "Waiting"
108
+ in_testing = "Testing"
109
+ done = "Done"
110
+ cancelled = "Canceled"
111
+ ```
112
+
113
+ - `project`: EDGAR picks only the cards in this project, by name or URL key, and files its own cards there.
114
+ - `title_prefix`: EDGAR picks only the cards whose title starts with this text, and adds it to the cards it files.
115
+ - `labels`: EDGAR picks only the cards that carry every label in the list, and adds them to the cards it files.
116
+
117
+ With none of the three set and `assignee_only` off, EDGAR picks every card of the team in the mapped columns.
118
+
119
+ - `assignee_only`: with `true`, a card is in scope only while it is assigned to `assignee`, in every mapped column. Set it when the team in `team` also holds cards that people work on, so that EDGAR takes only the cards that someone gave to its user. The default is `false`. The value is a boolean, and `edgar check` refuses any other value. The user is `assignee`, so the smallest setting is `assignee_only = true` with no `assignee`, which takes the cards assigned to the user of `LINEAR_TOKEN`.
120
+ - The listing filters in Linear: `list_cards` adds `assignee: { id: { eq: <user> } }` to the filter of every column, so a card of another user, or of nobody, is never read.
121
+ - A card that carries the label `edgar:waiting` is in scope too, whoever holds it. `hand_back` adds the label when it gives a card to a person, so the person's reply on the card is still read and starts the work again. `move` out of `waiting_on_person` and `close` take it off. A card that a person moves or closes in Linear keeps it. The listing asks for `or: [{ assignee }, { labels: edgar:waiting }]` inside its `and` list.
122
+ - A card that a person assigns to another user, or to nobody, leaves the scope the same way a card that leaves the board does. The next listing does not have it, the engine then asks `card` for it, and `card` answers `not_found` with the message `linear: card <id> is not assigned to the user of [extensions.linear] assignee`. The engine stores the card as closed and stops each run that was open on it, with the work kept. A card that is assigned back is a card again at the next sweep.
123
+ - A card that EDGAR files (`create_card`, as a tool and as the tracker method that the feeders of EDGAR's own service use) is assigned to `assignee` when it is made. Without that, a feeder's card would be assigned to nobody and would never be in scope. With `assignee_only` off, EDGAR assigns a new card to nobody, as before.
124
+ - `create_card` still returns the open card that holds the fingerprint, whoever it is assigned to. If a person took that card, EDGAR files no second card and does not take the card back.
125
+ - When the user cannot be read (the token is refused, or Linear limits the rate), `list_cards` and `card` answer that failure. They never answer `not_found` for it, so no card closes because of a failed read.
126
+
127
+ - `assigned` and `assignee`: a card assigned to `assignee` in a column of `assigned` is a card in `intake`. The sweep's `list_cards` for `intake` asks for it in the same query, it reads as `intake`, and `move` takes it forward from there, so a person hands a card to EDGAR by assigning it, in any of these columns. A column of `assigned` cannot be a column of `columns`. `assignee` is found once for the life of the runtime: an email by `users`, an id by `user`, and `me` or no value by `viewer`. An email or an id that no user of the workspace has is a permanent `invalid` that names it. With `assigned` empty and `assignee_only` off, the defaults, nothing is asked.
128
+
129
+ ## Secret
130
+
131
+ `LINEAR_TOKEN`: a personal API key (`lin_api_...`, sent bare) or an OAuth token (sent as `Bearer`). It reaches only `api.linear.app`.
132
+
133
+ ### What the key must be able to do
134
+
135
+ Make the key in Linear, Settings, Security & access, Personal API keys. A key with only Read lets EDGAR sweep and read cards, and every write fails. Give it the Write permission and access to the team in `[extensions.linear] team`. `edgar check` prints this text with `X004` when the project has no source for the key.
136
+
137
+ | Write | Linear operation | Scope it needs |
138
+ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------- |
139
+ | `comment`, the tracker's `comment` | `CommentCreate` | `comments:create` or `write` |
140
+ | `create_card`, the tracker's `create_card` | `IssueCreate` | `issues:create` or `write` |
141
+ | `move`, `close`, `set_labels`, `release_follow_ups`, `update_description`, `restore_description`, `assign`, `restore_assignee`, `hand_back` | `IssueUpdate` | `write` |
142
+ | `hand_back`, when the workspace has no label `edgar:waiting` | `IssueLabelCreate` | `write` |
143
+
144
+ Linear's API has no read of a key's scopes: its GraphQL schema has no scopes field for a personal key, and `integrationHasScopes` is for integrations only. A dry write is not used. So no check can tell a read-only key before its first write. That write fails `permanent_failure(forbidden)`, the engine does not retry it, the outbox records `outbox_failed` and an `alert`, and the message names the scope:
145
+
146
+ ```json
147
+ {
148
+ "outcome": "permanent_failure",
149
+ "kind": "forbidden",
150
+ "message": "linear CommentCreate: forbidden: the LINEAR_TOKEN key needs the comments:create or write scope",
151
+ "cause": "400 FORBIDDEN Invalid scope: write or comments:create required"
152
+ }
153
+ ```
154
+
155
+ ## Errors
156
+
157
+ One table in `src/api/failures.ts` maps each answer to an outcome, with the HTTP status, the raw code and the first error's message (at most 200 characters) in `cause`. The message is data for people; no code reads it. The first error's `extensions.code` wins: `RATELIMITED` `rate_limited`, `AUTHENTICATION_ERROR` `unauthenticated`, `FORBIDDEN` `forbidden`, `NOT_FOUND` `not_found`, `INVALID_INPUT` and `GRAPHQL_VALIDATION_FAILED` `invalid`. With no known code, HTTP 400 is `invalid`, 401 `unauthenticated`, 403 `forbidden`, 429 `rate_limited`, 5xx and network errors `provider_unavailable`, and anything else `tool_error`. A read of a missing id answers `not_found`. A `forbidden` answer to a write names the scope that the write needs, from the table in "What the key must be able to do". A rate limit waits for `Retry-After`, then `X-RateLimit-Requests-Reset`, then one minute.
158
+
159
+ ## Limits
160
+
161
+ Each answer's `X-RateLimit-Requests-Limit`, `-Remaining` and `-Reset`, and `X-RateLimit-Complexity-Limit`, `-Remaining` and `-Reset` (Unix milliseconds), are read with the SDK's `linear` scheme. The window with the smallest share left is reported for the source `api.linear.app`, with the window `requests` or `complexity`, on a success and on a failure. A `Retry-After` makes the limit used up until the time it names. The operator sees the source on the console's Limits page and on `GET /api/limits`. While `api.linear.app` has none left, EDGAR does not start a stage whose tool has `network:api.linear.app`, and records `waited_for_limit` until the reset.
162
+
163
+ ## Build and test
164
+
165
+ ```sh
166
+ pnpm build # writes edgar-extension.json and schemas/
167
+ pnpm test # unit tests with a mock Linear, no network
168
+ ```
169
+
170
+ `edgar-extension.json` and `schemas/` are committed: a change to them in a diff is a change to what a person approves.
171
+
172
+ ## Validation
173
+
174
+ Run on 2026-11-11 from the repository root, after `assignee_only` and `assign`:
175
+
176
+ | Command | Exit code |
177
+ | ---------------------------------------------------------- | ----------------- |
178
+ | `pnpm --filter @kana-ai/edgar-ext-linear run check-types` | 0 |
179
+ | `pnpm --filter @kana-ai/edgar-ext-linear run lint` | 0 |
180
+ | `pnpm --filter @kana-ai/edgar-ext-linear run format:check` | 0 |
181
+ | `pnpm --filter @kana-ai/edgar-ext-linear run test` | 0, 67 tests pass |
182
+ | `pnpm --filter @kana-ai/edgar-ext-linear run build`, twice | 0, the same bytes |
183
+
184
+ ## Shortcuts
185
+
186
+ - shortcut: the fingerprint and `waits_for` searches match the exact TOML line EDGAR writes, such as `waits_for = "ENG-7"`. A block a person reformats is not found. Upgrade to a label or a custom field if people edit blocks by hand.
187
+ - shortcut: the follow-up search reads 50 cards, `comments` 100 and `attachments` 50, with no further pages. Upgrade to cursors when a card exceeds them.
188
+ - shortcut: labels are found by name across the workspace, first match wins, and a missing label is refused, not created.
189
+ - shortcut: `close` does not post `reason`.
190
+ - shortcut: `card` checks `assignee_only` and not `project`, `title_prefix` or `labels`. A card that leaves one of those three is still a card for `card`, and the sweep's alert names it. Upgrade when a project moves cards out of its scope while EDGAR works on them.
191
+ - shortcut: `comment`, `move`, `close`, `set_labels`, `update_description`, `assign` and `release_follow_ups` do not check the scope of the card they write to. The engine stops the run of a card that left the scope at the next sweep, so a write can still reach such a card for one sweep.
192
+ - shortcut: `assign` and `[extensions.linear] assignee` take an id as Linear's `user(id:)` reads it, and the Linear names of the assignee writes (`assigneeId` on `IssueCreateInput` and `IssueUpdateInput`, `null` for nobody) are from Linear's GraphQL reference, with no recorded answer. Check them against recorded answers before release.
193
+ - shortcut: `hand_back` reads the first 50 entries of the card's history in the order Linear gives them, so an older hand-over of a card with a longer history is not seen, and the Linear names it reads (`history` with `actor`, `toAssignee` and `createdAt`, `creator`, `User.app`, `issueLabelCreate`) are from Linear's GraphQL reference, with no recorded answer. Check them against recorded answers before release.
194
+ - shortcut: nothing takes `edgar:waiting` off a card. A card that keeps it stays in scope with `assignee_only` after the person's reply. Upgrade when a card must leave the scope again after it was handed back.
195
+ - shortcut: a sighting with no `last_seen` is counted at the time of the call, so a retried `create_card` whose first answer was lost counts it twice. A feed that sets `last_seen` is counted once.
196
+ - shortcut: the count is read and written with no version check, because Linear's `IssueUpdate` takes none. Two sightings at the same moment can both write the same count, and a person's edit of the description between the read and the write is lost. Upgrade when Linear offers a conditional write.
197
+ - shortcut: `budget_remaining` is 0 when Linear sends no rate-limit header, so the sweep slows down rather than speeds up.
198
+ - shortcut: a mention is read as `@<display name>` in the body; no recorded Linear mention sample exists yet. Upgrade when one is recorded.
199
+ - shortcut: error codes other than `RATELIMITED` follow the mapping table; Linear's pages document no others. Check them against recorded answers before release.
@@ -0,0 +1,21 @@
1
+ import { type Ctx, type Err, type Failure, type Ok } from "@kana-ai/edgar-sdk";
2
+ import type { z } from "zod";
3
+ /** The secret every Linear call sends. */
4
+ export declare const TOKEN = "LINEAR_TOKEN";
5
+ /** The host every Linear call goes to. */
6
+ export declare const HOST: "api.linear.app";
7
+ /** The secret and the capability of the tracker and of each tool, which all call the API. */
8
+ export declare const apiAccess: {
9
+ readonly secrets: readonly ["LINEAR_TOKEN"];
10
+ readonly capabilities: readonly ["network:api.linear.app"];
11
+ };
12
+ /** A tool context that holds the Linear token. */
13
+ export type LinearCtx = Ctx<typeof TOKEN>;
14
+ /** The answer of one Linear call: the parsed `data` and the requests left in the window, or the failure it maps to. */
15
+ export type Reply<T> = (Ok<T> & {
16
+ readonly remaining: number;
17
+ }) | Err<Failure>;
18
+ /** A UUID derived from the operation id, sent as the id of what a write creates so a repeat cannot create twice. */
19
+ export declare function keyOf(operationId: string): string;
20
+ /** Sends one named GraphQL operation to Linear with the call's `LINEAR_TOKEN` and parses `data` with `schema`; each answer's rate limit goes on the call's outcome. A secret read outside the call is a bug and throws before the request. */
21
+ export declare function linear<T>(ctx: LinearCtx, query: string, variables: Readonly<Record<string, unknown>>, schema: z.ZodType<T>): Promise<Reply<T>>;
@@ -0,0 +1,53 @@
1
+ import { createHash } from "node:crypto";
2
+ import { attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, unwrapOr, } from "@kana-ai/edgar-sdk";
3
+ import { limits, mapFailure } from "#api/failures";
4
+ import { envelope } from "#schemas/linear";
5
+ /** The secret every Linear call sends. */
6
+ export const TOKEN = "LINEAR_TOKEN";
7
+ /** The host every Linear call goes to. */
8
+ export const HOST = limits.source;
9
+ /** The secret and the capability of the tracker and of each tool, which all call the API. */
10
+ export const apiAccess = { secrets: [TOKEN], capabilities: [`network:${HOST}`] };
11
+ /** A UUID derived from the operation id, sent as the id of what a write creates so a repeat cannot create twice. */
12
+ export function keyOf(operationId) {
13
+ const h = createHash("sha256").update(operationId).digest("hex");
14
+ const variant = ((Number.parseInt(h.charAt(16), 16) & 3) | 8).toString(16);
15
+ return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
16
+ }
17
+ function authorization(token) {
18
+ return token.startsWith("lin_api_") ? token : `Bearer ${token}`;
19
+ }
20
+ /** Sends one named GraphQL operation to Linear with the call's `LINEAR_TOKEN` and parses `data` with `schema`; each answer's rate limit goes on the call's outcome. A secret read outside the call is a bug and throws before the request. */
21
+ export async function linear(ctx, query, variables, schema) {
22
+ const context = `linear ${/^\s*(?:query|mutation)\s+(\w+)/.exec(query)?.[1] ?? "operation"}`;
23
+ const headers = {
24
+ authorization: authorization(ctx.secrets.get(TOKEN)),
25
+ "content-type": "application/json",
26
+ };
27
+ const sent = await attemptAsync(async () => await fetch(`https://${HOST}/graphql`, {
28
+ method: "POST",
29
+ signal: ctx.signal,
30
+ headers,
31
+ body: JSON.stringify({ query, variables }),
32
+ }), (caught) => fetchFailure(caught, ctx.signal, context));
33
+ if (!sent.ok)
34
+ return sent;
35
+ const response = sent.value;
36
+ reportLimit(ctx, limitFromHeaders(response.headers, limits.scheme, HOST));
37
+ const json = unwrapOr(await attemptAsync(async () => await response.json(), () => null), null);
38
+ const body = envelope.safeParse(json);
39
+ const errors = body.success ? (body.data.errors ?? []) : [];
40
+ if (!response.ok || errors.length > 0) {
41
+ return err(mapFailure(response.status, response.headers, errors, context));
42
+ }
43
+ const parsed = schema.safeParse(body.success ? body.data.data : undefined);
44
+ if (parsed.success) {
45
+ const remaining = Number(response.headers.get("x-ratelimit-requests-remaining"));
46
+ return {
47
+ ...ok(parsed.data),
48
+ remaining: Number.isFinite(remaining) ? Math.max(0, Math.floor(remaining)) : 0,
49
+ };
50
+ }
51
+ const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
52
+ return err(failure("tool_error", `${context}: unexpected answer`, { cause: `fields: ${fields}` }));
53
+ }
@@ -0,0 +1,11 @@
1
+ import { type Failure } from "@kana-ai/edgar-sdk";
2
+ import type { GraphqlError } from "#schemas/linear";
3
+ /** Linear reports its request and complexity limits in `x-ratelimit-{requests,complexity}-*` on every answer of its API host. */
4
+ export declare const limits: {
5
+ readonly scheme: "linear";
6
+ readonly source: "api.linear.app";
7
+ };
8
+ /** The scope a Linear key needs for each write the extension sends. Linear has no read of a key's scopes, so a `forbidden` write names its scope in the message, and the README names them all. */
9
+ export declare const writeScopes: Map<string, string>;
10
+ /** Maps a Linear error answer to a failure: the first error's code wins over the HTTP status, and `cause` keeps both raw with Linear's message. A `forbidden` write says the scope the key needs. */
11
+ export declare function mapFailure(status: number, headers: Headers, errors: readonly GraphqlError[], context: string, now?: number): Failure;
@@ -0,0 +1,37 @@
1
+ import { vendorFailure } from "@kana-ai/edgar-sdk";
2
+ /** Linear reports its request and complexity limits in `x-ratelimit-{requests,complexity}-*` on every answer of its API host. */
3
+ export const limits = { scheme: "linear", source: "api.linear.app" };
4
+ const statusKinds = new Map([
5
+ [400, "invalid"],
6
+ [401, "unauthenticated"],
7
+ [403, "forbidden"],
8
+ [429, "rate_limited"],
9
+ ]);
10
+ const codeKinds = new Map([
11
+ ["RATELIMITED", "rate_limited"],
12
+ ["AUTHENTICATION_ERROR", "unauthenticated"],
13
+ ["FORBIDDEN", "forbidden"],
14
+ ["NOT_FOUND", "not_found"],
15
+ ["INVALID_INPUT", "invalid"],
16
+ ["GRAPHQL_VALIDATION_FAILED", "invalid"],
17
+ ]);
18
+ /** The scope a Linear key needs for each write the extension sends. Linear has no read of a key's scopes, so a `forbidden` write names its scope in the message, and the README names them all. */
19
+ export const writeScopes = new Map([
20
+ ["CommentCreate", "comments:create or write"],
21
+ ["IssueCreate", "issues:create or write"],
22
+ ["IssueUpdate", "write"],
23
+ ]);
24
+ /** Maps a Linear error answer to a failure: the first error's code wins over the HTTP status, and `cause` keeps both raw with Linear's message. A `forbidden` write says the scope the key needs. */
25
+ export function mapFailure(status, headers, errors, context, now = Date.now()) {
26
+ const code = errors[0]?.extensions?.code;
27
+ const kind = (code === undefined ? undefined : codeKinds.get(code)) ??
28
+ (status >= 500 ? "provider_unavailable" : statusKinds.get(status)) ??
29
+ "tool_error";
30
+ const said = errors[0]?.message?.slice(0, 200) ?? "";
31
+ const cause = `${String(status)} ${code ?? ""} ${said}`.replace(/\s+/g, " ").trim();
32
+ const failed = vendorFailure(kind, context, cause, headers, limits, now);
33
+ const scope = writeScopes.get(context.replace(/^linear /, ""));
34
+ return kind === "forbidden" && scope !== undefined
35
+ ? { ...failed, message: `${failed.message}: the LINEAR_TOKEN key needs the ${scope} scope` }
36
+ : failed;
37
+ }
@@ -0,0 +1,3 @@
1
+ /** The Linear extension: the tracker port and the tools the default workflows call. */
2
+ declare const _default: import("@kana-ai/edgar-sdk").Extension;
3
+ export default _default;
@@ -0,0 +1,19 @@
1
+ import { defineExtension } from "@kana-ai/edgar-sdk";
2
+ import { HOST, TOKEN, apiAccess } from "#api/client";
3
+ import { config } from "#schemas/config";
4
+ import { tracker } from "#tracker/port";
5
+ import { tools } from "#tracker/tools";
6
+ /** The Linear extension: the tracker port and the tools the default workflows call. */
7
+ export default defineExtension({
8
+ name: "linear",
9
+ config,
10
+ secrets: {
11
+ [TOKEN]: {
12
+ hosts: [HOST],
13
+ help: "Make a personal API key in Linear, Settings, Security & access, with the Write permission (comments, moves, closes and descriptions need it) and access to the team in [extensions.linear] team.",
14
+ },
15
+ },
16
+ capabilities: [...apiAccess.capabilities],
17
+ tools,
18
+ tracker,
19
+ });
@@ -0,0 +1,25 @@
1
+ import { z } from "zod";
2
+ /** The extension's `[extensions.linear]` table: the team key, the optional card scope, the Linear column of each engine state, the columns where a card assigned to `assignee` counts as intake, and the switch that keeps every card of another assignee out. */
3
+ export declare const config: z.ZodObject<{
4
+ team: z.ZodString;
5
+ project: z.ZodOptional<z.ZodString>;
6
+ title_prefix: z.ZodOptional<z.ZodString>;
7
+ labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
8
+ columns: z.ZodObject<{
9
+ intake: z.ZodString;
10
+ ready: z.ZodString;
11
+ working: z.ZodString;
12
+ in_review: z.ZodString;
13
+ waiting_on_person: z.ZodString;
14
+ in_testing: z.ZodString;
15
+ done: z.ZodString;
16
+ cancelled: z.ZodString;
17
+ }, z.core.$strict>;
18
+ assignee: z.ZodOptional<z.ZodString>;
19
+ assignee_only: z.ZodDefault<z.ZodBoolean>;
20
+ assigned: z.ZodDefault<z.ZodArray<z.ZodString>>;
21
+ }, z.core.$strict>;
22
+ /** The parsed `[extensions.linear]` table. */
23
+ export type Config = z.infer<typeof config>;
24
+ /** An engine state the table maps to a column. */
25
+ export type State = keyof Config["columns"];