@kana-ai/edgar-ext-slack 0.0.0-stage → 0.1.1
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.
- package/LICENSE +202 -0
- package/README.md +172 -2
- package/dist/src/api/client.d.ts +19 -0
- package/dist/src/api/client.js +83 -0
- package/dist/src/api/failures.d.ts +8 -0
- package/dist/src/api/failures.js +50 -0
- package/dist/src/inbound/route.d.ts +9 -0
- package/dist/src/inbound/route.js +486 -0
- package/dist/src/inbound/signature.d.ts +3 -0
- package/dist/src/inbound/signature.js +21 -0
- package/dist/src/inbound/socket.d.ts +15 -0
- package/dist/src/inbound/socket.js +131 -0
- package/dist/src/index.d.ts +3 -0
- package/dist/src/index.js +30 -0
- package/dist/src/outbound/layout.d.ts +42 -0
- package/dist/src/outbound/layout.js +301 -0
- package/dist/src/outbound/messages.d.ts +38 -0
- package/dist/src/outbound/messages.js +123 -0
- package/dist/src/outbound/places.d.ts +35 -0
- package/dist/src/outbound/places.js +114 -0
- package/dist/src/outbound/progress.d.ts +2 -0
- package/dist/src/outbound/progress.js +484 -0
- package/dist/src/outbound/tools.d.ts +63 -0
- package/dist/src/outbound/tools.js +175 -0
- package/dist/src/outbound/words.d.ts +129 -0
- package/dist/src/outbound/words.js +259 -0
- package/dist/src/schemas/config.d.ts +35 -0
- package/dist/src/schemas/config.js +37 -0
- package/dist/src/schemas/events.d.ts +126 -0
- package/dist/src/schemas/events.js +77 -0
- package/dist/src/schemas/slack.d.ts +132 -0
- package/dist/src/schemas/slack.js +89 -0
- package/dist/src/schemas/tools.d.ts +71 -0
- package/dist/src/schemas/tools.js +49 -0
- package/edgar-extension.json +107 -0
- package/package.json +42 -3
- package/schemas/ask.in.json +34 -0
- package/schemas/ask.out.json +13 -0
- package/schemas/config.json +122 -0
- package/schemas/delete_message.in.json +15 -0
- package/schemas/delete_message.out.json +10 -0
- package/schemas/dm.in.json +36 -0
- package/schemas/dm.out.json +15 -0
- package/schemas/find_message.in.json +12 -0
- package/schemas/find_message.out.json +15 -0
- package/schemas/post_summary.in.json +43 -0
- package/schemas/post_summary.out.json +15 -0
- package/slack-app.json +57 -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,173 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kana-ai/edgar-ext-slack
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Slack extension of EDGAR. A person sends EDGAR a direct message (DM) or mentions it in a channel. EDGAR answers a question in the message's thread, puts a message that names a card on that card, and opens a card from a message that asks for work. While EDGAR works on the card, the thread of the message shows each stage, asks for approvals, and takes answers. The tools post a summary, send a DM, ask a person a question, and delete or find a message that EDGAR posted. No default workflow calls them: a stage of the project's own workflow calls each as `slack__<tool>`, and the hook and the service work with no stage at all.
|
|
4
|
+
|
|
5
|
+
The full guide, with the app setup, each setting, each tool and its examples, is [the Slack page](/docs/reference/slack.md).
|
|
6
|
+
|
|
7
|
+
## Parts
|
|
8
|
+
|
|
9
|
+
| Part | What it does |
|
|
10
|
+
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| The service | Keeps one Socket Mode connection to Slack while `edgar start` runs. A DM or a mention that names a card (`EDG-2422`, or its tracker link) goes on that card and binds its thread to it; any other is a chat (`ctx.runs.chat`), which the built-in `chat` workflow answers in the thread, or opens a card for when it asks for work. A reply answers the newest question that waits; with no question, a reply in the thread of a card, or of the card that the thread is bound to, goes on the card as that person's comment with the thread as its place (`ctx.cards.reply`), with the thread's messages since EDGAR's last one and each Slack thread that it links from the same channel or a public one (a private one is left out, and the person is told). EDGAR says so, and says once when it is still on an earlier reply. The stop button cancels the card's runs. Approve, Deny and answer buttons move the run. |
|
|
12
|
+
| The hook `progress` | Takes the run events of every run. A run that a person's words in Slack started (`relayed` on its `run_created`) posts a stage's answer `text`, or the card that a chat opened, in that thread once, ends its status, and says a failed answer in one plain line. Each card has one thread. A card that came from Slack uses the thread of its message. Any other card gets a thread in `channel`, or in the DM of the first `dm` entry when `channel` is not set: its first message links the card, and each run of the card, a rerun too, replies in it. Each run keeps one progress message in the thread from the moment its first stage starts, and its approvals go there; a stage that ends `done` with a `question` in its output, such as a proposal that went on with the option it recommends, posts the question once there, greets the assignee, and says that a reply with the number of another option changes the work, with the metadata `edgar_question` and the run and the stage; a run that ends with no stage, such as a run that a card's event started and that had nothing to do, posts none. A card from Slack also gets the session status (`processing` at the run's start and at each stage's start, `suspended` for an approval, `active` or `closed` at the end). When a run ends, the end note goes in the card's thread, and in the card's thread in the DM of each `dm` entry. A run with no card, such as a scheduled watch, gets no thread and no progress message, and gets an end note only when it does not end `done`. |
|
|
13
|
+
| The tool `post_summary` | Posts a run's summary as a person writes it: one sentence with the card and what was done, plain paragraphs, then what to check. Side effect, undone by `delete_message`, found by `find_message`. |
|
|
14
|
+
| The tool `dm` | Sends a DM to a person, by Slack user id or by email. Side effect, undone by `delete_message`, found by `find_message`. |
|
|
15
|
+
| The tool `ask` | Posts a question with answer buttons, or asks for a reply, and returns `waiting` until a person answers. Side effect with no undo: a person may already have read the question. |
|
|
16
|
+
| The tool `delete_message` | Deletes a message that EDGAR posted. A message that is already gone is `done` with `deleted: false`. |
|
|
17
|
+
| The tool `find_message` | Finds the message of a `post_summary` or `dm` call by the operation id in its metadata. `skipped` when there is none. |
|
|
18
|
+
|
|
19
|
+
The text of `post_summary` (`did`, `paragraphs`, `check`), of `dm`, of an `ask` question and of an answer shown back comes from a model, which often copies it from a card or a log. The extension makes `&`, `<` and `>` plain in that text, so it cannot notify a channel (`<!channel>`, `<@U…>`) or show a link whose label hides its address. A plain address still becomes a link in Slack. Known limit: a tool cannot post a link with a label of its own; the card link of `post_summary` is built by the extension. A question that passes the 3,000 characters of a Slack section once its markup is plain is cut on a whole character and ends with `…`. In the other direction, the text of a message from Slack is read back as the person wrote it before it reaches a card or an answer: no mention, a link as its address, and `&`, `<`, `>` as their characters.
|
|
20
|
+
|
|
21
|
+
## Configuration
|
|
22
|
+
|
|
23
|
+
```toml
|
|
24
|
+
[extensions.slack]
|
|
25
|
+
inbound = "socket" # "socket" (the default) or "events" (the service only waits; see Shortcuts)
|
|
26
|
+
open_card_on = ["dm", "mention"] # the default: a DM and a mention both open a card
|
|
27
|
+
card_column = "intake" # the default: the engine state of a new card
|
|
28
|
+
context_messages = 20 # the default: the thread's newest messages copied onto the card, 0 to 100
|
|
29
|
+
allow = { domains = ["example.com"], guests = false } # optional: who may open a card
|
|
30
|
+
operators = { U0123ABCD = "ada" } # the default is empty: the Slack users who may answer, approve, deny and stop
|
|
31
|
+
channel = "C0123ABCD" # optional: where post_summary posts when the call names no channel, where a run whose card did not come from Slack opens its thread, and where the note of a run that opened a pull request is shown
|
|
32
|
+
dm = [
|
|
33
|
+
"U0123ABCD",
|
|
34
|
+
"ada@example.com",
|
|
35
|
+
] # the default is empty: who gets the end note of each run in a DM, by Slack user id or email
|
|
36
|
+
close_on_done = false # the default: true sets the session closed after a run that is done
|
|
37
|
+
console_url = "https://edgar.example.com" # no default: when set, the end note links the run's page, <console_url>/runs/<id>
|
|
38
|
+
|
|
39
|
+
[extensions.slack.people] # the default is empty: who the end note and an approval question mention, and who gets a decision note in a DM, by the assignee's name as the tracker gives it
|
|
40
|
+
"Pat Doe" = "U0123ABCD"
|
|
41
|
+
"Bea Stone" = "bea@example.com"
|
|
42
|
+
|
|
43
|
+
[extensions.slack.status] # the default is empty: the phrase of a stage while it works, by stage name
|
|
44
|
+
fix = "is reading the code"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
A `dm` email is found with `users.lookupByEmail`, which needs the `users:read.email` scope of `slack-app.json`, once per process. An email that no person of the workspace has makes the end of each run a permanent `invalid` that names the email, and the engine raises an alert. A `dm` entry that is neither a user id nor an email fails the config schema, which `edgar check` prints. `edgar check` runs no extension code, so it cannot find an unknown email or a channel that does not exist; Slack answers those at the first run, as `invalid` and `not_found`.
|
|
48
|
+
|
|
49
|
+
## The thread of a card and the end note
|
|
50
|
+
|
|
51
|
+
The first message about a card opens its thread. The message is the card's title as a link to the card, and its metadata (`edgar_card`) holds the card's link and the newest 20 runs of the card. Each later run of the card adds its number to that metadata and replies in the same thread. Each message of a run finds the thread again by its run number, in the newest 100 messages of the channel or the DM. The extension keeps no other state. When the first message is no longer among those 100 messages, the next run of the card opens a new thread.
|
|
52
|
+
|
|
53
|
+
The end note is one message with blocks and the same words as plain text, which a notification and a screen reader show:
|
|
54
|
+
|
|
55
|
+
1. The headline: one emoji, the status in words, and the card. When the run names the card's id, the id is the link, and the service and the title follow: "EDG-1 · api: Search fails". With no id, the title is the link. A run with no card names its workflow, or the run.
|
|
56
|
+
2. One or two sentences. They greet the assignee ("Hey <assignee>,") when the card is assigned: a Slack mention, `<@U0123ABCD>`, when the extension finds their Slack user, else the name as the tracker gives it. The extension uses the first of these: the `people` entry whose key is the assignee's name, the `operators` entry whose name is the assignee's name, and the assignee itself when it is an email address. An email is found with `users.lookupByEmail`, once per process. When an email finds no user, the lookup fails, or the answer is not a Slack user id, the greeting has the plain name, the note is still posted, and the log has one line that names the assignee, the email and the reason. Then what happened:
|
|
57
|
+
- "I've opened a pull request for <card>." or "I've opened <n> pull requests for <card>.", then the proposal's summary and, for a risk above low, the merge risk and its reason. A run of the built-in `remediate` says this at the moment its review wait (`wait_review`) starts, with no summary: see "The note that a pull request is ready".
|
|
58
|
+
- "The pull request for <card> is merged.", then "<logins> approved it." and "The merge commit is `<7 characters>`." when the run read them. The note has no "Your move" and no word of the proposal, which was written before the pull request.
|
|
59
|
+
- "The pull request for <card> is approved, and it isn't merged yet.", "A reviewer asked for changes on the pull request for <card>." or "The pull request for <card> was closed with no merge.", when the run ended with that decision of its reviewers.
|
|
60
|
+
- "I need your call on <card>." and the proposal's summary when the proposal's `decision` is `escalate` or `handoff`, then one numbered line for each of the proposal's `options`. With no such proposal, a run that ends on a question, such as triage's question when a card is unclear, says "I need your call on <card>." with the question.
|
|
61
|
+
- "I couldn't finish <card>, and I didn't open a pull request." when the run did not end `done`, then the failure in plain words when the engine's failure word is a known one, else the engine's message.
|
|
62
|
+
- "I'm holding off on <card> for now." and the summary when the proposal's `decision` is `wait`.
|
|
63
|
+
- "Heads up: someone stopped my work on <card> before I finished." when the run's outcome has the kind `cancelled`.
|
|
64
|
+
- "I've finished <card>." and the summary in all other cases. A done run with no summary sends no note.
|
|
65
|
+
3. "Your move:" and the one thing to do, when there is one: review the pull request, reply with a number, or run `edgar run replay <run>`.
|
|
66
|
+
4. The facts in two columns (`fields`): service, step, run time, tokens, cost, assignee and run, each when the run has it. "Run time" is the time from the start of this run to its end, with each wait in it. "Tokens" counts the model calls of the run and of the runs that its stages started, and a run with no model token has no such fact.
|
|
67
|
+
5. One link button for each place to act: the card, each pull request (three at most), and the run's page, `<console_url>/runs/<run>`, when `console_url` is set. With no link at all, small text says "No link for this one. You can see it with `edgar runs <run>`."
|
|
68
|
+
6. For a failed run, the engine's own words in small text (a `context` block).
|
|
69
|
+
|
|
70
|
+
A failed run of a schedule whose run just before it failed with the same failure kind sends no note, and the first run of that schedule that works again sends one. For each message as a person sees it, and the table of the emoji, see [the Slack page](/docs/reference/slack.md#what-a-person-sees-in-slack).
|
|
71
|
+
|
|
72
|
+
All the words that EDGAR says in Slack are in one module, `src/outbound/words.ts`: the emoji of each status, the label of each built-in stage, and the text of each note, question and acknowledgement. `src/outbound/layout.ts` builds the blocks and the plain text from them, and calls no API. When Slack refuses the blocks of a message as not valid, `src/outbound/messages.ts` sends the same message again with its text and no block, and the log says so.
|
|
73
|
+
|
|
74
|
+
Set `console_url` only to an address that the readers of the note can open. It has no default, because the console's own address, `http://127.0.0.1:7401`, opens only on the host that runs EDGAR.
|
|
75
|
+
|
|
76
|
+
The facts of the note come from `endNote` of `@kana-ai/edgar-sdk`, which reads the `end` record of the `run_outcome` event. The mail extensions write the lines of the same note. The note also has the metadata `edgar_end` with the run, so a delivery that the engine sends again posts no second note.
|
|
77
|
+
|
|
78
|
+
### The note that a pull request is ready
|
|
79
|
+
|
|
80
|
+
The note "Ready for review" tells people that they can act, so the hook posts it when the stage `wait_review` starts to wait, and not at the end of the run, which can be days later. It goes to the same places as an end note, mentions the assignee the same way, links the card and the pull request, and has the metadata `edgar_ready` with the run. A run posts it one time: a delivery that the engine sends again finds it and posts nothing, and a run that ends with its pull request still open, for example because its card was taken by a person, does not say it again. A run of a workflow with no stage of that name posts it at its end, as before. The end note then says what happened: merged, approved, changes asked, or closed.
|
|
81
|
+
|
|
82
|
+
An event whose `outcome` `endNote` cannot read still ends the progress message and the session status. Its note is the one line "Run 7 is over, but I couldn't read how it ended. You can check it with `edgar runs 7`.", and the log says so.
|
|
83
|
+
|
|
84
|
+
## The progress message
|
|
85
|
+
|
|
86
|
+
Each run with a card keeps one message in the card's thread, with the metadata `edgar_plan`, and the hook changes it in place. The hook posts it at the run's first `attempt_started` event, not at `run_created`, so a run that ends before any stage starts leaves no line in the thread, and, when it ends `done`, no note either. The `run_created` event only lists the run on the card's first message and, for a card from Slack, sets the session status `processing` with the card's title. Its first line is the status and the card, in a `context` block, so that Slack shows its text and its emoji small; the plain text of the message keeps the same line. Then it has one line for each stage that started, in the order of the starts: the emoji of its state and its label. A stage is added at its `attempt_started` event, so a stage that the run skips or never reaches is never shown, and an outcome `skipped` removes its line. A stage of the built-in workflows has a label in `words.ts`; another stage reads as its name in words. A stage that waits reads "Waiting for CI", "Waiting for a review" or "Waiting for you"; another wait reads "Waiting:" and the label. More than three done steps fold into one line, "<n> steps done". A done stage whose output has the `state` and the `review_state` of a pull request says what people decided in place of its label, on a line of its own beside the folded steps: "The pull request is approved", "The pull request is approved and merged", "The pull request is merged", "A reviewer asked for changes" or "The pull request was closed with no merge". The last line links the run's page, when `console_url` is set, and each pull request that a stage answered with `url` and `number`. In Slack the steps are a `plan` block, and the stage that runs also sets the moving status line of the thread with `assistant.threads.setStatus`: the stage's phrase from `status`, else "is on it:" and its label. Slack removes that line at the app's next message in the thread, or after 2 minutes.
|
|
87
|
+
|
|
88
|
+
The hook's process ends after some minutes with no work, so the hook keeps nothing that it cannot read again: the progress message holds its own state in its metadata, and the card and the trigger of a run that the process did not see start are read from the run's first event with `runs.read`, which the hook holds the capability `runs:read` for. A run that does not read is one line in the log, and its messages name no card.
|
|
89
|
+
|
|
90
|
+
A reply in the thread of a card, with no question that waits, goes on the card, and the person gets "Got it, thanks. I've put your reply on the card and I'm reading it now." A mention of EDGAR in the thread of a card is such a reply and opens no second card. A reply with a file goes on the card as its words, and the note says that EDGAR cannot open files from Slack yet; a file with no word goes on no card, and the person is told. From the moment the service takes the reply, the thread shows the moving status line "<app name> is reading your reply…", set with `assistant.threads.setStatus` under the scope `assistant:write`. The service sets the status before it writes on the card and again after its note, because a message of the app ends the status. The status ends at EDGAR's next message in the thread, or after 2 minutes when EDGAR posts nothing more, which is Slack's own limit. A reply that the card did not take gets the reason, and its status is removed. A status call that fails is written to the log with Slack's error and never stops the reply. A run that a person's comment started shows no progress message, and says nothing when it ends done: its answer is the comment that it writes or the run that it starts. A run that a stage of another run started (its `run_created` event has a `trigger_key` that starts with `subrun:`) is quiet in the same way, because it is one step of that run. Its approval question, its failure, its decision and its pull request are still said, under the card's thread. So a reply that asks for nothing, such as thanks, gets the acknowledgement and no more.
|
|
91
|
+
|
|
92
|
+
A note that asks for a decision also goes to the DM of the card's assignee, in the card's thread there, when the extension finds their Slack user: a mention notifies a person only in a conversation that the person is in. An assignee who is also in `dm` gets the note once. A DM that Slack refuses is one line in the log, and the other notes are still posted.
|
|
93
|
+
|
|
94
|
+
The note of a run that opened a pull request also goes to `channel`, when it is set: as a reply in the card's thread there, sent with `reply_broadcast`, so the channel itself shows it. The extension opens the card's thread in `channel` when the card has none there. Each other note stays in its thread.
|
|
95
|
+
|
|
96
|
+
An approval question greets the assignee as the end note does. The hook reads the assignee from the `approval_requested` event itself. The question says what EDGAR wants to run in plain words ("open pull request (github)"), what each button does, and has the link buttons "Open the card" and "See the run" beside Approve and Deny. The tool's own name and the run are in small text.
|
|
97
|
+
|
|
98
|
+
An approval question shows the input of the call as JSON in a code block, and the approval runs that input and no other. The block holds at most 2,400 characters. When the input is longer, the question says that the block is only its start and names the console page **Needs a person**, as a link when `console_url` is set. For the full text of the question, see [the Slack page](/docs/reference/slack.md#approve-and-deny).
|
|
99
|
+
|
|
100
|
+
Each value in `operators` must also be a name in `[roles] operator`, because the engine checks the person on each move. A person who is not an operator and answers, presses a button or stops work is told so, only to them. While `operators` is empty, that message gives their Slack user id and the line to add, so a new project's first press shows how to set it up.
|
|
101
|
+
|
|
102
|
+
## Secrets
|
|
103
|
+
|
|
104
|
+
- `SLACK_BOT_TOKEN`: the bot token (`xoxb-`) of the installed app. Every Web API call sends it. It reaches `slack.com` and `*.slack.com`, such as `files.slack.com`.
|
|
105
|
+
- `SLACK_APP_TOKEN`: an app-level token (`xapp-`) with `connections:write`. Only the service sends it, to open the Socket Mode connection. It reaches `slack.com` and `*.slack.com`.
|
|
106
|
+
|
|
107
|
+
Both secrets list `*.slack.com`, because the engine gives a service only the `network:` hosts its secrets list, and the Socket Mode address is `wss-primary.slack.com`. A project that approved an earlier manifest runs `edgar extensions approve slack` again. A connection that closes within 5 seconds of opening is written to the log with its close code, and the next one waits 1 s, then 2 s, up to a minute.
|
|
108
|
+
|
|
109
|
+
Create the app from `slack-app.json` in this folder. The [Slack page](/docs/reference/slack.md#create-the-slack-app) gives each step.
|
|
110
|
+
|
|
111
|
+
## Errors
|
|
112
|
+
|
|
113
|
+
One table in `src/api/failures.ts` maps each answer to an outcome. Slack's `error` string wins over the HTTP status. `cause` keeps the status, the raw `error`, and the scope that a `missing_scope` needs.
|
|
114
|
+
|
|
115
|
+
| Slack `error` | Kind | Outcome |
|
|
116
|
+
| ------------------------------------------------------------------------------------------------- | ---------------------- | --------- |
|
|
117
|
+
| `ratelimited`, or HTTP 429 | `rate_limited` | temporary |
|
|
118
|
+
| `invalid_auth`, `not_authed`, `account_inactive`, `token_revoked`, `token_expired` | `unauthenticated` | permanent |
|
|
119
|
+
| `channel_not_found`, `message_not_found`, `thread_not_found`, `user_not_found`, `users_not_found` | `not_found` | permanent |
|
|
120
|
+
| `missing_scope`, `not_in_channel`, `cant_delete_message`, `restricted_action` | `forbidden` | permanent |
|
|
121
|
+
| `invalid_arguments`, `invalid_blocks`, `invalid_metadata_format`, `msg_too_long`, `no_text` | `invalid` | permanent |
|
|
122
|
+
| `internal_error`, `fatal_error`, `service_unavailable`, `request_timeout`, or HTTP 5xx | `provider_unavailable` | temporary |
|
|
123
|
+
| Any other `error` | `tool_error` | permanent |
|
|
124
|
+
|
|
125
|
+
An answer with `ok: true` but a shape that the schema does not accept is a `tool_error` that names the fields.
|
|
126
|
+
|
|
127
|
+
## Limits
|
|
128
|
+
|
|
129
|
+
Slack reports a rate limit only as HTTP 429 with `Retry-After`. Each answer is read with the SDK's `retry_after` scheme and reported for the source `slack.com`. A 429 whose `Retry-After` is 30 seconds or less waits and tries again, two times at most. A longer one goes back to the engine as `rate_limited` with `retry_after`. The operator sees the source on the console's Limits page and on `GET /api/limits`.
|
|
130
|
+
|
|
131
|
+
## Build and test
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
pnpm build # writes edgar-extension.json and schemas/
|
|
135
|
+
pnpm test # unit tests with a mock Slack, no network
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`edgar-extension.json` and `schemas/` are committed: a change to them in a diff is a change to what a person approves.
|
|
139
|
+
|
|
140
|
+
## Validation
|
|
141
|
+
|
|
142
|
+
Run on 2026-11-10 from the repository root:
|
|
143
|
+
|
|
144
|
+
| Command | Exit code |
|
|
145
|
+
| --------------------------------------------------------- | ---------------- |
|
|
146
|
+
| `pnpm --filter @kana-ai/edgar-ext-slack run check-types` | 0 |
|
|
147
|
+
| `pnpm --filter @kana-ai/edgar-ext-slack run lint` | 0 |
|
|
148
|
+
| `pnpm --filter @kana-ai/edgar-ext-slack run format:check` | 0 |
|
|
149
|
+
| `pnpm --filter @kana-ai/edgar-ext-slack run test` | 0, 61 tests pass |
|
|
150
|
+
|
|
151
|
+
A smoke run in a Slack developer sandbox, with the app made from `slack-app.json`:
|
|
152
|
+
|
|
153
|
+
- `edgar check` in a project with `demo` and `slack` enabled gave `0 errors`.
|
|
154
|
+
- `edgar start` started the service, and the service opened a Socket Mode connection and received `hello`.
|
|
155
|
+
- The `dm` tool sent a DM and answered `done` with the channel and the `ts`. The `progress` hook posted one progress message in that DM's thread and changed it in place for each event. Each `agents.sessions.setStatus` call answered `ok`.
|
|
156
|
+
- `apps.connections.open` is a POST, because Slack answers a GET with `insecure_request`. The socket test fails when it is a GET.
|
|
157
|
+
- A DM in the main box reached the service, which asked for a card with the origin of the DM thread and posted its thank-you reply in that thread.
|
|
158
|
+
- The smoke run did not cover a card that the engine opens from a real DM, or a real press on the stop button.
|
|
159
|
+
|
|
160
|
+
## Shortcuts
|
|
161
|
+
|
|
162
|
+
- shortcut: `inbound = "events"` is accepted, and the service then only waits. The engine has no webhook receiver for Slack yet. Upgrade with the webhook receiver; `src/inbound/signature.ts` already checks the v0 signature.
|
|
163
|
+
- shortcut: the summary is posted as one message. It is not streamed. Upgrade with partial model output from the engine.
|
|
164
|
+
- shortcut: no suggested prompts, no debounce of one call per second per thread, and no `post_on` or `plan_display` setting.
|
|
165
|
+
- shortcut: a question is found by the metadata of the newest EDGAR question in the thread, or in the newest 100 messages of a DM. An answered question is marked `edgar_answered`. A question whose wait ended, by a timeout or the run's end, stays marked `edgar_ask` until someone replies or presses a button: the engine then refuses the answer, and the question is marked `edgar_closed` with a line that says so. In a thread, the person is told that the reply went to no card and that a mention opens one; in a DM, the message opens a card.
|
|
166
|
+
- shortcut: a plain reply in a thread with no waiting question and no message of a run of EDGAR's goes to no card, and nobody is told, because each message in a channel that mentions EDGAR also comes as a plain message. Upgrade: read the app's user id from the event's `authorizations` and tell a plain reply in a thread that holds an EDGAR plan.
|
|
167
|
+
- shortcut: in a channel, a message in the main box never answers a question, because it does not say which question it answers. Only a reply in the question's thread does.
|
|
168
|
+
- shortcut: the label of a stage and the name of a wait come from a table of the built-in stages in `src/outbound/words.ts`, because no run event carries the order of the stages, a label, or what a wait waits on. Upgrade when the `run_created` event carries the plan with a label for each stage.
|
|
169
|
+
- shortcut: the moving status line of a thread lasts 2 minutes at most, which is Slack's limit, because the hook runs only when an event comes. Upgrade with an event from the engine while a stage works.
|
|
170
|
+
- shortcut: the progress message is found by its metadata in the newest 200 replies of the thread.
|
|
171
|
+
- shortcut: the card's thread is found by the metadata of its first message in the newest 100 messages of the channel or the DM, because the extension has no state that lasts across a restart. A busy channel, or a card idle for a long time, gets a new thread. Upgrade with extension state that the engine keeps.
|
|
172
|
+
- shortcut: an approval question goes to the card's thread only, and not to the DM of the assignee, because only an operator can answer it and a second set of buttons would stay after the first answer.
|
|
173
|
+
- shortcut: the end note mentions an assignee only when `people` or `operators` names them, or when the tracker gives an email as the name, because the card holds the name that the tracker shows and no email. Upgrade when the card holds the assignee's email, which `users.lookupByEmail` turns into a user id with no `people` entry.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import type { z } from "zod";
|
|
3
|
+
/** The bot token every Web API call sends. */
|
|
4
|
+
export declare const BOT = "SLACK_BOT_TOKEN";
|
|
5
|
+
/** The app-level token that only opens the Socket Mode connection. */
|
|
6
|
+
export declare const APP = "SLACK_APP_TOKEN";
|
|
7
|
+
/** The Web API host. */
|
|
8
|
+
export declare const HOST: "slack.com";
|
|
9
|
+
/** The secret and the capability of each tool and of the progress hook. */
|
|
10
|
+
export declare const apiAccess: {
|
|
11
|
+
readonly secrets: readonly ["SLACK_BOT_TOKEN"];
|
|
12
|
+
readonly capabilities: readonly ["network:slack.com"];
|
|
13
|
+
};
|
|
14
|
+
/** A context that holds the bot token. */
|
|
15
|
+
export type SlackCtx = Ctx<typeof BOT>;
|
|
16
|
+
/** Calls one Web API method with `token` and parses the answer with `schema`. A 429 whose `Retry-After` is at most 30 s waits and tries again, twice at most; a longer one comes back as `rate_limited` with `retry_after`. */
|
|
17
|
+
export declare function call<T>(ctx: Ctx<string>, token: string, method: string, args: Readonly<Record<string, unknown>>, schema: z.ZodType<T>): Promise<Result<T, Failure>>;
|
|
18
|
+
/** Calls one Web API method with the bot token. A secret read outside the call is a bug and throws before the request. */
|
|
19
|
+
export declare function slack<T>(ctx: SlackCtx, method: string, args: Readonly<Record<string, unknown>>, schema: z.ZodType<T>): Promise<Result<T, Failure>>;
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { setTimeout as sleep } from "node:timers/promises";
|
|
2
|
+
import { attempt, attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, } from "@kana-ai/edgar-sdk";
|
|
3
|
+
import { limits, mapFailure } from "#api/failures";
|
|
4
|
+
import { answer } from "#schemas/slack";
|
|
5
|
+
/** The bot token every Web API call sends. */
|
|
6
|
+
export const BOT = "SLACK_BOT_TOKEN";
|
|
7
|
+
/** The app-level token that only opens the Socket Mode connection. */
|
|
8
|
+
export const APP = "SLACK_APP_TOKEN";
|
|
9
|
+
/** The Web API host. */
|
|
10
|
+
export const HOST = limits.source;
|
|
11
|
+
/** The secret and the capability of each tool and of the progress hook. */
|
|
12
|
+
export const apiAccess = { secrets: [BOT], capabilities: [`network:${HOST}`] };
|
|
13
|
+
/** Methods that accept only form encoding; they go as a GET with a query string. `apps.connections.open` is not one: Slack answers its GET with `insecure_request`. */
|
|
14
|
+
const queried = new Set([
|
|
15
|
+
"chat.getPermalink",
|
|
16
|
+
"conversations.history",
|
|
17
|
+
"conversations.info",
|
|
18
|
+
"conversations.replies",
|
|
19
|
+
"users.info",
|
|
20
|
+
"users.lookupByEmail",
|
|
21
|
+
]);
|
|
22
|
+
/** A 429 waits for its `Retry-After` and tries again this many times, when the wait is short. */
|
|
23
|
+
const RETRIES = 2;
|
|
24
|
+
const LONGEST_WAIT_SECONDS = 30;
|
|
25
|
+
async function once(ctx, token, method, args, schema) {
|
|
26
|
+
const context = `slack ${method}`;
|
|
27
|
+
const url = new URL(`https://${HOST}/api/${method}`);
|
|
28
|
+
const read = queried.has(method);
|
|
29
|
+
if (read) {
|
|
30
|
+
for (const [name, value] of Object.entries(args)) {
|
|
31
|
+
if (value !== undefined)
|
|
32
|
+
url.searchParams.set(name, String(value));
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
const sent = await attemptAsync(async () => await fetch(url, {
|
|
36
|
+
method: read ? "GET" : "POST",
|
|
37
|
+
signal: ctx.signal,
|
|
38
|
+
headers: {
|
|
39
|
+
authorization: `Bearer ${token}`,
|
|
40
|
+
...(read ? {} : { "content-type": "application/json; charset=utf-8" }),
|
|
41
|
+
},
|
|
42
|
+
...(read ? {} : { body: JSON.stringify(args) }),
|
|
43
|
+
}), (caught) => fetchFailure(caught, ctx.signal, context));
|
|
44
|
+
if (!sent.ok)
|
|
45
|
+
return sent;
|
|
46
|
+
const response = sent.value;
|
|
47
|
+
reportLimit(ctx, limitFromHeaders(response.headers, limits.scheme, HOST));
|
|
48
|
+
const text = await attemptAsync(async () => await response.text(), (caught) => fetchFailure(caught, ctx.signal, context));
|
|
49
|
+
if (!text.ok)
|
|
50
|
+
return text;
|
|
51
|
+
const json = attempt(() => JSON.parse(text.value), () => undefined);
|
|
52
|
+
const body = answer.safeParse(json.ok ? json.value : undefined);
|
|
53
|
+
if (response.status !== 200 || !body.success || !body.data.ok) {
|
|
54
|
+
const error = body.success ? body.data.error : undefined;
|
|
55
|
+
const needed = body.success ? body.data.needed : undefined;
|
|
56
|
+
return err(mapFailure(response.status, response.headers, error, needed, context));
|
|
57
|
+
}
|
|
58
|
+
const parsed = schema.safeParse(body.data);
|
|
59
|
+
if (parsed.success)
|
|
60
|
+
return ok(parsed.data);
|
|
61
|
+
const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
|
|
62
|
+
return err(failure("tool_error", `${context}: unexpected answer`, { cause: `fields: ${fields}` }));
|
|
63
|
+
}
|
|
64
|
+
/** Calls one Web API method with `token` and parses the answer with `schema`. A 429 whose `Retry-After` is at most 30 s waits and tries again, twice at most; a longer one comes back as `rate_limited` with `retry_after`. */
|
|
65
|
+
export async function call(ctx, token, method, args, schema) {
|
|
66
|
+
for (let tried = 0;; tried += 1) {
|
|
67
|
+
const result = await once(ctx, token, method, args, schema);
|
|
68
|
+
if (result.ok || result.error.outcome !== "temporary_failure")
|
|
69
|
+
return result;
|
|
70
|
+
const wait = result.error.retry_after;
|
|
71
|
+
if (result.error.kind !== "rate_limited" || wait === undefined)
|
|
72
|
+
return result;
|
|
73
|
+
if (tried >= RETRIES || wait > LONGEST_WAIT_SECONDS)
|
|
74
|
+
return result;
|
|
75
|
+
const slept = await attemptAsync(async () => await sleep(wait * 1000, undefined, { signal: ctx.signal }), () => result);
|
|
76
|
+
if (!slept.ok)
|
|
77
|
+
return result;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
/** Calls one Web API method with the bot token. A secret read outside the call is a bug and throws before the request. */
|
|
81
|
+
export async function slack(ctx, method, args, schema) {
|
|
82
|
+
return await call(ctx, ctx.secrets.get(BOT), method, args, schema);
|
|
83
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { type Failure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
/** Slack reports a rate limit only as 429 with `Retry-After`, on its Web API host. */
|
|
3
|
+
export declare const limits: {
|
|
4
|
+
readonly scheme: "retry_after";
|
|
5
|
+
readonly source: "slack.com";
|
|
6
|
+
};
|
|
7
|
+
/** Maps a Slack error answer to a failure: the `error` string wins over the HTTP status, and `cause` keeps the status, the raw `error` and the scope a `missing_scope` needs. */
|
|
8
|
+
export declare function mapFailure(status: number, headers: Headers, error: string | undefined, needed: string | undefined, context: string, now?: number): Failure;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { vendorFailure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
/** Slack reports a rate limit only as 429 with `Retry-After`, on its Web API host. */
|
|
3
|
+
export const limits = { scheme: "retry_after", source: "slack.com" };
|
|
4
|
+
const errorKinds = new Map([
|
|
5
|
+
["ratelimited", "rate_limited"],
|
|
6
|
+
["invalid_auth", "unauthenticated"],
|
|
7
|
+
["not_authed", "unauthenticated"],
|
|
8
|
+
["account_inactive", "unauthenticated"],
|
|
9
|
+
["token_revoked", "unauthenticated"],
|
|
10
|
+
["token_expired", "unauthenticated"],
|
|
11
|
+
["channel_not_found", "not_found"],
|
|
12
|
+
["message_not_found", "not_found"],
|
|
13
|
+
["thread_not_found", "not_found"],
|
|
14
|
+
["user_not_found", "not_found"],
|
|
15
|
+
["users_not_found", "not_found"],
|
|
16
|
+
["missing_scope", "forbidden"],
|
|
17
|
+
["not_in_channel", "forbidden"],
|
|
18
|
+
["cant_delete_message", "forbidden"],
|
|
19
|
+
["restricted_action", "forbidden"],
|
|
20
|
+
["invalid_arguments", "invalid"],
|
|
21
|
+
["invalid_blocks", "invalid"],
|
|
22
|
+
["invalid_metadata_format", "invalid"],
|
|
23
|
+
["msg_too_long", "invalid"],
|
|
24
|
+
["no_text", "invalid"],
|
|
25
|
+
["internal_error", "provider_unavailable"],
|
|
26
|
+
["fatal_error", "provider_unavailable"],
|
|
27
|
+
["service_unavailable", "provider_unavailable"],
|
|
28
|
+
["request_timeout", "provider_unavailable"],
|
|
29
|
+
]);
|
|
30
|
+
function kindOf(status, error) {
|
|
31
|
+
const known = error === undefined ? undefined : errorKinds.get(error);
|
|
32
|
+
if (known !== undefined)
|
|
33
|
+
return known;
|
|
34
|
+
if (status === 429)
|
|
35
|
+
return "rate_limited";
|
|
36
|
+
if (status >= 500)
|
|
37
|
+
return "provider_unavailable";
|
|
38
|
+
if (status === 401)
|
|
39
|
+
return "unauthenticated";
|
|
40
|
+
if (status === 403)
|
|
41
|
+
return "forbidden";
|
|
42
|
+
return "tool_error";
|
|
43
|
+
}
|
|
44
|
+
/** Maps a Slack error answer to a failure: the `error` string wins over the HTTP status, and `cause` keeps the status, the raw `error` and the scope a `missing_scope` needs. */
|
|
45
|
+
export function mapFailure(status, headers, error, needed, context, now = Date.now()) {
|
|
46
|
+
const cause = [String(status), error, needed === undefined ? undefined : `needs ${needed}`]
|
|
47
|
+
.filter((part) => part !== undefined)
|
|
48
|
+
.join(" ");
|
|
49
|
+
return vendorFailure(kindOf(status, error), context, cause, headers, limits, now);
|
|
50
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type Ctx } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { type APP, type BOT } from "#api/client";
|
|
3
|
+
import type { Config } from "#schemas/config";
|
|
4
|
+
/** The service's context: the bot token for the Web API and the app token for the socket. */
|
|
5
|
+
export type ServiceCtx = Ctx<typeof BOT | typeof APP>;
|
|
6
|
+
/** The text as the person wrote it: no `<@U…>` mention, a link as its address, and `<`, `>`, `&` as their characters. Slack sends a message's text escaped, and each tool escapes what it posts, so this is the one place that reads the escape back. */
|
|
7
|
+
export declare function clean(text: string): string;
|
|
8
|
+
/** Routes one Socket Mode envelope's payload. Each failure is told to the person or logged, so one bad event never stops the service. */
|
|
9
|
+
export declare function route(ctx: ServiceCtx, settings: Config, type: string, payload: unknown): Promise<void>;
|