@kana-ai/edgar-ext-slack 0.1.4 → 0.1.6
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/README.md +36 -25
- package/dist/src/api/client.d.ts +1 -1
- package/dist/src/api/client.js +4 -2
- package/dist/src/api/tags.d.ts +5 -0
- package/dist/src/api/tags.js +100 -0
- package/dist/src/inbound/route.d.ts +3 -1
- package/dist/src/inbound/route.js +100 -16
- package/dist/src/outbound/layout.d.ts +38 -12
- package/dist/src/outbound/layout.js +330 -63
- package/dist/src/outbound/messages.d.ts +17 -3
- package/dist/src/outbound/messages.js +42 -2
- package/dist/src/outbound/places.d.ts +11 -6
- package/dist/src/outbound/places.js +94 -26
- package/dist/src/outbound/progress.js +346 -84
- package/dist/src/outbound/tools.js +2 -3
- package/dist/src/outbound/words.d.ts +56 -8
- package/dist/src/outbound/words.js +126 -13
- package/dist/src/schemas/config.d.ts +1 -0
- package/dist/src/schemas/config.js +5 -1
- package/dist/src/schemas/events.d.ts +66 -3
- package/dist/src/schemas/events.js +65 -5
- package/dist/src/schemas/slack.d.ts +19 -2
- package/dist/src/schemas/slack.js +19 -4
- package/edgar-extension.json +1 -1
- package/package.json +3 -3
- package/schemas/config.json +9 -1
package/README.md
CHANGED
|
@@ -6,17 +6,17 @@ The full guide, with the app setup, each setting, each tool and its examples, is
|
|
|
6
6
|
|
|
7
7
|
## Parts
|
|
8
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 (`ENG-42`, 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
|
|
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
|
-
| The link reader | Reads a Slack thread that a card or its comments link (`read_link`, for `*.slack.com`) into the run's inbox, as `/tmp/inbox/links.md`: its newest 50 messages, oldest first, quoted as the service quotes a linked thread. Only a thread in `channel` or in a public channel is read, because everyone who reads the run may see it; a thread in a private channel, a DM or a group DM is a `forbidden` failure, which the inbox shows in one line. A Slack link that is not a message's permalink, such as a file, is not read.
|
|
19
|
-
| Chat files | A file that a person shares in a chat, such as a screenshot or a log, goes with the chat (`chatFiles`, for `files.slack.com`). The engine fetches it into the run's inbox, as it fetches a card's attachments: with the same byte caps, with secrets masked in a text file, and with `SLACK_BOT_TOKEN` as its bearer token, sent only to `files.slack.com`. A chat reads text and log files, JSON, XML, YAML, PDFs, and PNG, JPEG, GIF or WebP pictures; for any other file, or one Slack gives no download link for, the person gets one short reply that names it. Reading a file needs the `files:read` scope of `slack-app.json`.
|
|
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 (`ENG-42`, 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; a short thank-you gets a short reply instead. It reacts :eyes: on each message it takes (`reactions:write`), and a new chat also gets "On it: reading your message." at once. The stop button cancels the card's runs. Approve, Deny and answer buttons move the run, and Try again starts a failed or stopped run again (`ctx.runs.replay`). |
|
|
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` (as Slack formatting, with its sources, a line when it is not sure, and buttons to the card and the run), or the card that a chat opened, in that thread once, says there what each stage of the built-in `answer` workflow starts and does for the person (`edgar_said`), names each stage on the status line, ends its status, says a failed answer in one plain line, and swaps the :eyes: reaction on the person's message for :white_check_mark:, or :x: when the run did not end done. 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 it waits in a queue or 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 asks for a reply in the thread, which names the number of another option only when the question lists numbered options, 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, and a run whose every stage was skipped, as a workflow that does not apply to the card, posts nothing in the card's thread, deletes the progress message that it showed, if any, and leaves the card's first message as it is. 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
|
+
| The link reader | Reads a Slack thread that a card or its comments link (`read_link`, for `*.slack.com`) into the run's inbox, as `/tmp/inbox/links.md`: its newest 50 messages, oldest first, quoted as the service quotes a linked thread. Only a thread in `channel` or in a public channel is read, because everyone who reads the run may see it; a thread in a private channel, a DM or a group DM is a `forbidden` failure, which the inbox shows in one line. A Slack link that is not a message's permalink, such as a file, is not read. |
|
|
19
|
+
| Chat files | A file that a person shares in a chat, such as a screenshot or a log, goes with the chat (`chatFiles`, for `files.slack.com`). The engine fetches it into the run's inbox, as it fetches a card's attachments: with the same byte caps, with secrets masked in a text file, and with `SLACK_BOT_TOKEN` as its bearer token, sent only to `files.slack.com`. A chat reads text and log files, JSON, XML, YAML, PDFs, and PNG, JPEG, GIF or WebP pictures; for any other file, or one Slack gives no download link for, the person gets one short reply that names it. Reading a file needs the `files:read` scope of `slack-app.json`. |
|
|
20
20
|
|
|
21
21
|
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.
|
|
22
22
|
|
|
@@ -34,6 +34,9 @@ dm = [
|
|
|
34
34
|
"U0123ABCD",
|
|
35
35
|
"ada@example.com",
|
|
36
36
|
] # the default is empty: who gets the end note of each run in a DM, by Slack user id or email
|
|
37
|
+
tag = [
|
|
38
|
+
"Pat Doe",
|
|
39
|
+
] # not set by default: everyone may be tagged; when set, only these people are tagged, by a name of people or operators or a Slack user id, and everyone else is written as their name; [] tags nobody
|
|
37
40
|
close_on_done = false # the default: true sets the session closed after a run that is done
|
|
38
41
|
console_url = "https://edgar.example.com" # no default: when set, the progress message, an approval question and the end note link the console, such as the run's page, <console_url>/runs/<id>
|
|
39
42
|
|
|
@@ -47,25 +50,30 @@ fix = "is reading the code"
|
|
|
47
50
|
|
|
48
51
|
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. An unknown email is found at the first run, as `invalid`. The channel is checked when the service starts, as [Start check](#start-check) says.
|
|
49
52
|
|
|
53
|
+
Each message EDGAR writes in Slack, a post, a change of a message or a message only one person sees, passes `tag` just before it goes. A mention of a person whom `tag` does not name, in the text or in a block, becomes that person's name as plain text, so Slack does not notify them: their `people` or `operators` name, else the name Slack shows for them, which `users.info` gives once per process, else "someone". `tag` changes only who is notified, never who is asked, who may act or who holds a card. A `tag` name that finds no Slack user is one log line and tags nobody.
|
|
54
|
+
|
|
50
55
|
## The thread of a card and the end note
|
|
51
56
|
|
|
52
|
-
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
|
|
57
|
+
The first message about a card opens its thread, when a run of the card starts its second stage or has something a person must read: a question, an approval, a pull request, a hand-back, a decision or a failure. Once the card has a thread, each later run of the card, a run that another run started too, joins it from its first stage, so its progress shows at once. A run that ends after one stage with nothing to tell, such as a card that asks EDGAR for nothing, posts nothing in the channel. The message is the card's status and its id as a link to the card with its title, such as ":eyes: Ready for review · ENG-1 Search fails", with the status in bold; then one small line with the card's service, unless the title already names it, "On behalf of" the person who asked for the work, and "Assignee" with the card's holder; then what the card asks, in at most two lines, with its Markdown as Slack formatting, so a link such as `[label](<https://…>)` is one link, and cut only between words, so a link or a code span is never cut, with " …" at the end of a cut; then a link button to the card and to each pull request that the run opened. "On behalf of" is a Slack mention when the card came from a Slack message (the writer's user id) or when `people`, `operators` or an email finds the person's Slack user, and the plain name otherwise. The holder is shown only as a Slack mention, so EDGAR's own tracker user is never written. The message changes in place when a run of the card starts to work ("I'm on it"), when its pull request is ready ("Ready for review"), and when it ends, with the title of its end note; a run that did no work changes nothing. A card that came from Slack keeps the person's message as its first message, which EDGAR does not change. The metadata (`edgar_card`) holds the card's link, its id, its title, the newest 20 runs of the card, and what the message shows (`view`), so a change of one part keeps the others. A run finds the card's first message by the card's id, so a card that triage retitles keeps its one thread, and the message takes the new title in place. Only the card's newest run, the last that the metadata lists, or a run new to the thread, sets the link and the title, so a run that started before a retitle never brings the old title back. A first message that keeps no id is found by the card's link, up to the card's id when the tracker puts the title after it, such as `/issue/ENG-1/search-fails`. 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, and a new run by the card's id or link, in the newest 1,000 messages of the channel or the DM, read 200 at a time from the newest and only as far as the page that holds it. Slack's rate limits slow that reading down but never end it as "no thread": a page that still fails fails the event, and the engine hands it again, so a card that has a thread never gets a second one at the top of the channel. The extension keeps no other state. When the first message is no longer among those 1,000 messages, the next run of the card opens a new thread, and a note that comes late opens none.
|
|
58
|
+
|
|
59
|
+
An event that reaches the hook 15 minutes or more after it happened, as after a backlog of events or a restart, is late. A late `run_created`, `attempt_started` or `waiting_for_slot` posts nothing and calls Slack for nothing, since that progress is over. A late stage outcome or end note goes only in a thread that the card already has: a run long over never opens a new thread at the top of the channel, for example after a person deleted the card's first message. The log says so for each late end note that finds no thread.
|
|
53
60
|
|
|
54
61
|
The end note is one message with blocks and the same words as plain text, which a notification and a screen reader show:
|
|
55
62
|
|
|
56
|
-
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: "ENG-1 · api: Search fails". With no id, the title is the link. A run with no card names its workflow, or the run.
|
|
63
|
+
1. The headline: one emoji, the status in words, and the card. The card's status message ends on the same status in words as the note, such as "Ready for review", "Over to a person" or "Done"; a run that failed ends it on "Ended early". When the run names the card's id, the id is the link, and the service and the title follow: "ENG-1 · api: Search fails". With no id, the title is the link. A run with no card names its workflow, or the run.
|
|
57
64
|
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, and no greeting otherwise, so a tracker name with no Slack user is never written. 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 note has no greeting, it is still posted, and the log has one line that names the assignee, the email and the reason. Then what happened:
|
|
58
65
|
- "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".
|
|
59
66
|
- "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.
|
|
60
67
|
- "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.
|
|
61
68
|
- "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.
|
|
69
|
+
- "I've handed <card> to <person>." and the question it left, else its summary, when a stage of the run handed the card back to a person (a stage output with `to` and `previous`, as a tracker's `hand_back` gives it). The headline reads "Over to a person", never "Done".
|
|
62
70
|
- "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.
|
|
63
71
|
- "I'm holding off on <card> for now." and the summary when the proposal's `decision` is `wait`.
|
|
64
|
-
- "Heads up: someone stopped my work on <card> before I finished." when the run's outcome has the kind `cancelled`.
|
|
72
|
+
- "Heads up: someone stopped my work on <card> before I finished." when the run's outcome has the kind `cancelled`. Only a run that showed its own status message in the thread says this: a run stopped before it showed anything ends with no note and opens no thread, so a person who stops many runs at once, such as every run of a first sweep, gets no message for each. When the run's end names who stopped it (`stopped_by`), "someone" is that person, a mention when the move names a Slack person by id, by `people` or as an operator, and the small line adds "Stopped by" and the person.
|
|
65
73
|
- "I've finished <card>." and the summary in all other cases. A done run with no summary sends no note.
|
|
66
|
-
3. "Your move:" and the one thing to do, when there is one: review the pull request, reply with a number, or
|
|
67
|
-
4.
|
|
68
|
-
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.
|
|
74
|
+
3. "Your move:" and the one thing to do, when there is one: review the pull request, reply with a number, or press Try again.
|
|
75
|
+
4. One small line (a `context` block): "On behalf of" the person who asked for the work, the run time, the tokens and the cost, each when the run has it, such as "On behalf of @Grace · 4 min · 170k tokens · $1.20". When the run's end names a person whose own subscription or API key a model call ran on (`paid_by`), the line says so: "On behalf of @Grace, on their Claude subscription", or "On behalf of @Grace · on @Bo's Claude API key"; the card's first message says the same, changed in place. "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. The note never shows the run's id, and says the service and the step only once: the service in the headline, the step in the failure's words. A failure with no reason says "The run stopped before it finished, and it left no reason I can read."
|
|
76
|
+
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. A failed or a stopped run's note also has a Try again button. Only the project's operators may press it: EDGAR starts the run again for them, takes the button off the note, and says in the thread "<@person> asked me to try again, so I'm starting now."; anyone else is told, only to them, why nothing happened. No note names an `edgar` command.
|
|
69
77
|
6. For a failed run, the engine's own words in small text (a `context` block).
|
|
70
78
|
|
|
71
79
|
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).
|
|
@@ -80,23 +88,25 @@ The facts of the note come from `endNote` of `@kana-ai/edgar-sdk`, which reads t
|
|
|
80
88
|
|
|
81
89
|
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.
|
|
82
90
|
|
|
83
|
-
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.
|
|
91
|
+
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.", and the log says so.
|
|
84
92
|
|
|
85
93
|
## The progress message
|
|
86
94
|
|
|
87
|
-
Each
|
|
95
|
+
Each card keeps one status message in its thread, with the metadata `edgar_plan`, and the hook changes it in place for every run of the card: a later run takes the same message over once the run that wrote it is over, so a thread never holds a second status message. A run that starts while another run of the card still works leaves that run's message alone. In a channel or a DM, the hook posts the message at the run's second `attempt_started` event, with the first stage in it, or earlier when a done stage asks a person a question; at the first when the card already has a thread there, which the hook finds by the card's id or link without posting; in the Slack thread of a card that came from Slack, at the first. A run that ends before that leaves no line in the thread, and, when it ends `done` with nothing to tell, no note either. A run that waits in a queue posts it earlier in the Slack thread of its card, at its `waiting_for_slot` event: the first line reads "Queued" with the still hourglass, and the next line says what the run waits on, such as "1 run for ENG-12 is going, which is my limit. I'll start when one ends." for a workflow's `concurrency`, "3 triage runs are going, which is my limit." when the run's input has no value at the key, so it counts with every other such run of its workflow, or "I'm already running 4 steps at once, which is my limit." for the project's `[concurrency]`. The first stage that starts turns the same message into the plan. The `run_created` event posts nothing; for a card from Slack, it sets the session status `processing` with the card's title. In the Slack thread of a card that came from Slack, 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. In the card's own thread, whose first message already says the status and the card, the message starts with its steps, and the status is the title of its `plan` block; a message with no step line, such as a run that ended before a step did, keeps the status alone. 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`. While the run is not over, the message has a Stop button (`edgar_stop`, its value the run's id): an operator's press cancels that run with `ctx.runs.stop`, takes the button off the message, and says in the thread who stopped it; a run that is over refuses, and the person who pressed is told why. 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 the phrase of a long stage of the built-in workflows in `words.ts`, such as "is working out a plan…" for `propose`, "is writing the change…" for `implement`, "is running the checks…" for `checks` and "is reviewing the change…" for `review`, else "is on it:" and its label. Slack shows it after the app's name. Slack removes that line at the app's next message in the thread, or after 2 minutes.
|
|
88
96
|
|
|
89
97
|
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.
|
|
90
98
|
|
|
91
|
-
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
|
|
99
|
+
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 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, which says the end. A quiet run still shows its progress like any run: each stage that starts sets the moving status line of the card's thread and goes on the card's status message, which it takes over once the run that wrote it is over, so the work that a reply starts, such as working out a plan and writing the change, is never silence. When it ends done, it marks its own status message over and removes the moving line, sets no session status and posts no note. Only the top run of a chain, the run whose `trigger_key` does not start with `subrun:`, posts an end note, whatever its outcome: a run that is one step of another ends the same quiet way when it fails, is stopped or hands the card back, so a failure deep in a chain gets one note and not one for each run. A pull request that such a step opened shows on the card's status message, and in the note of the top run. Its questions, its approval questions and a decision that it needs from a person are still said, under the card's thread, because they cannot wait for the top run's end. A chain asks a person one time: when the top run ends on a decision that a step of it, or another run, already asked in the card's thread while the top run worked, as a decision note or a question with the same words, the top run posts no note for it. The failure, the decision and the pull request of a comment's run are still said too. So a reply that asks for nothing, such as thanks, gets the acknowledgement and no more.
|
|
92
100
|
|
|
93
101
|
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.
|
|
94
102
|
|
|
95
|
-
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,
|
|
103
|
+
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, and nothing at the top of the channel. The extension opens the card's thread in `channel` when the card has none there. Each other note stays in its thread. The note lists each pull request that the run opened on a line of its own, shows the merge risk in a block of its own when it is above low, and has an "Open pull request" button for each pull request beside the card's button; with several pull requests, each button names its pull request, such as "Open pull request api#3".
|
|
104
|
+
|
|
105
|
+
A question that a done stage leaves open, and a decision or hand-back note, tag the people who can act on it at its start, each once and at most five: the people of the run's `who_can_act` (the stage output's, or the newest one at the run's end), then the requester, then the assignee when Slack knows them. The engine adds to each person it matches in `[people]` (by an id in `ids`, the `email` or the name) their Slack id and email, so the hook tags `ids.slack`, else the user that `users.lookupByEmail` finds; a person with no match is written as text by name or login, never by email, with one log line. A decision note whose question is already in the card's thread (`edgar_question` of the run) posts no message there: the question gets one small line at its end, with the run time, the tokens and the cost, and its metadata gets `ended`, so the line is added one time. The run's id is never shown. A DM still gets the whole note.
|
|
96
106
|
|
|
97
|
-
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
|
|
107
|
+
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 do in plain words ("open pull request in github"), why it asks (the tool's approval policy), 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.
|
|
98
108
|
|
|
99
|
-
An approval question shows the input of the call as
|
|
109
|
+
An approval question shows the input of the call as a list of details, one field to a line, each value in code so its markup shows as written, and the approval runs that input and no other. A tool that deletes or removes something adds a warning line. The list holds at most 12 fields and 2,400 characters. When a part is left out, the question says that the details are only their 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).
|
|
100
110
|
|
|
101
111
|
When a done stage's output names a channel in `post_in`, as `classify` does when a person asks for the result in a channel ("post it in #team-backend when it's done"), the hook says once in the card's thread "I'll post the result in #team-backend when the work is done.", with the metadata `edgar_post_to`. At the end of a later run of the card that is done, it posts that run's end note in the channel, as a message of the channel and not in a thread, and changes the promise to "I posted the result in #team-backend." (`edgar_post_done`), so the result goes there once. A channel link (`<#C123|name>`) is posted to by its id, and a name by its name. When the app is not in the channel or Slack can't find it, the promise says so and how to invite the app; the run that heard the ask, and a run that did not end done, post nothing there.
|
|
102
112
|
|
|
@@ -183,12 +193,13 @@ A smoke run in a Slack developer sandbox, with the app made from `slack-app.json
|
|
|
183
193
|
- 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.
|
|
184
194
|
- shortcut: the summary is posted as one message. It is not streamed. Upgrade with partial model output from the engine.
|
|
185
195
|
- shortcut: no suggested prompts, no debounce of one call per second per thread, and no `post_on` or `plan_display` setting.
|
|
186
|
-
- shortcut: a question is found by the metadata of the newest EDGAR question in the thread, or in the newest
|
|
196
|
+
- shortcut: a question is found by the metadata of the newest EDGAR question in the thread, or in the newest 200 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.
|
|
187
197
|
- 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.
|
|
188
198
|
- 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.
|
|
189
199
|
- 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.
|
|
190
200
|
- 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.
|
|
191
201
|
- shortcut: the progress message is found by its metadata in the newest 200 replies of the thread.
|
|
192
|
-
- shortcut: the card's thread is found by the metadata of its first message in the newest
|
|
202
|
+
- shortcut: the card's thread is found by the metadata of its first message in the newest 1,000 messages of the channel or the DM, read 200 at a time and only as far as the first page that holds it, because the extension has no state that lasts across a restart. A card whose first message is further back gets a new thread, or, for a note that comes late, none. Upgrade with extension state that the engine keeps.
|
|
193
203
|
- 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.
|
|
194
204
|
- 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.
|
|
205
|
+
- shortcut: `tag` names a person by a name of `people` or `operators`, or by a Slack user id, and not by a name of the project's `[people]`, because an extension does not read `[people]`. Upgrade when the engine gives an extension the ids of `[people]`.
|
package/dist/src/api/client.d.ts
CHANGED
|
@@ -15,5 +15,5 @@ export declare const apiAccess: {
|
|
|
15
15
|
export type SlackCtx = Ctx<typeof BOT>;
|
|
16
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
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. */
|
|
18
|
+
/** Calls one Web API method with the bot token. A message passes `untagged` first, so it tags only the people `[extensions.slack] tag` allows. A secret read outside the call is a bug and throws before the request. */
|
|
19
19
|
export declare function slack<T>(ctx: SlackCtx, method: string, args: Readonly<Record<string, unknown>>, schema: z.ZodType<T>): Promise<Result<T, Failure>>;
|
package/dist/src/api/client.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { setTimeout as sleep } from "node:timers/promises";
|
|
2
2
|
import { attempt, attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, } from "@kana-ai/edgar-sdk";
|
|
3
3
|
import { limits, mapFailure } from "#api/failures";
|
|
4
|
+
import { WRITES, untagged } from "#api/tags";
|
|
4
5
|
import { answer } from "#schemas/slack";
|
|
5
6
|
/** The bot token every Web API call sends. */
|
|
6
7
|
export const BOT = "SLACK_BOT_TOKEN";
|
|
@@ -77,7 +78,8 @@ export async function call(ctx, token, method, args, schema) {
|
|
|
77
78
|
return result;
|
|
78
79
|
}
|
|
79
80
|
}
|
|
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
|
+
/** Calls one Web API method with the bot token. A message passes `untagged` first, so it tags only the people `[extensions.slack] tag` allows. A secret read outside the call is a bug and throws before the request. */
|
|
81
82
|
export async function slack(ctx, method, args, schema) {
|
|
82
|
-
|
|
83
|
+
const sent = WRITES.has(method) ? await untagged(ctx, args, slack) : args;
|
|
84
|
+
return await call(ctx, ctx.secrets.get(BOT), method, sent, schema);
|
|
83
85
|
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { SlackCtx, slack } from "#api/client";
|
|
2
|
+
/** The Web API methods that write a message a person reads. */
|
|
3
|
+
export declare const WRITES: ReadonlySet<string>;
|
|
4
|
+
/** `args` of a message with each mention of a person that `[extensions.slack] tag` does not name, in its `text` and its blocks, written as that person's plain name, so Slack notifies only the people the project allows. With no `tag`, `args` as they are. */
|
|
5
|
+
export declare function untagged(ctx: SlackCtx, args: Readonly<Record<string, unknown>>, read: typeof slack): Promise<Readonly<Record<string, unknown>>>;
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { settingsOf, userId } from "#schemas/config";
|
|
2
|
+
import { userInfo } from "#schemas/slack";
|
|
3
|
+
/** A Slack mention of a person, `<@U0123ABCD>` or `<@U0123ABCD|name>`. */
|
|
4
|
+
const MENTION = /<@([UW][A-Z0-9]{2,})(?:\|[^>]*)?>/g;
|
|
5
|
+
/** The Web API methods that write a message a person reads. */
|
|
6
|
+
export const WRITES = new Set([
|
|
7
|
+
"chat.postMessage",
|
|
8
|
+
"chat.update",
|
|
9
|
+
"chat.postEphemeral",
|
|
10
|
+
]);
|
|
11
|
+
/** The user id of each email of `people` that `users.lookupByEmail` found, and the name Slack shows for each user `users.info` answered, kept for the life of the process. */
|
|
12
|
+
const byEmail = new Map();
|
|
13
|
+
const shown = new Map();
|
|
14
|
+
/** Each string of `value`, at any depth, through `swap`. */
|
|
15
|
+
function mapped(value, swap) {
|
|
16
|
+
if (typeof value === "string")
|
|
17
|
+
return swap(value);
|
|
18
|
+
if (Array.isArray(value))
|
|
19
|
+
return value.map((item) => mapped(item, swap));
|
|
20
|
+
if (typeof value === "object" && value !== null)
|
|
21
|
+
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapped(item, swap)]));
|
|
22
|
+
return value;
|
|
23
|
+
}
|
|
24
|
+
/** The user id of a `people` value: the value itself, else the user `users.lookupByEmail` finds for the email, else none. */
|
|
25
|
+
async function userOf(ctx, given, read) {
|
|
26
|
+
if (userId.safeParse(given).success)
|
|
27
|
+
return given;
|
|
28
|
+
const known = byEmail.get(given);
|
|
29
|
+
if (known !== undefined)
|
|
30
|
+
return known;
|
|
31
|
+
const found = await read(ctx, "users.lookupByEmail", { email: given }, userInfo);
|
|
32
|
+
if (!found.ok)
|
|
33
|
+
return undefined;
|
|
34
|
+
byEmail.set(given, found.value.user.id);
|
|
35
|
+
return found.value.user.id;
|
|
36
|
+
}
|
|
37
|
+
/** The Slack user ids that `[extensions.slack] tag` names: an id itself, else the `people` entry of that name, by id or by the email `users.lookupByEmail` finds, else the `operators` entry of that name. An entry that names nobody is one log line and tags nobody. */
|
|
38
|
+
async function allowed(ctx, settings, tag, read) {
|
|
39
|
+
const users = new Set();
|
|
40
|
+
for (const entry of tag) {
|
|
41
|
+
const named = Object.hasOwn(settings.people, entry) ? settings.people[entry] : undefined;
|
|
42
|
+
const given = userId.safeParse(entry).success ? entry : named;
|
|
43
|
+
const user = (given === undefined ? undefined : await userOf(ctx, given, read)) ??
|
|
44
|
+
Object.entries(settings.operators).find(([, name]) => name === entry)?.[0];
|
|
45
|
+
if (user === undefined)
|
|
46
|
+
ctx.log(`[extensions.slack] tag names ${entry}, who has no Slack user`);
|
|
47
|
+
else
|
|
48
|
+
users.add(user);
|
|
49
|
+
}
|
|
50
|
+
return users;
|
|
51
|
+
}
|
|
52
|
+
/** The name of `user` as plain text: their `people` or `operators` name, else the name Slack shows for them, else "someone". */
|
|
53
|
+
async function plainName(ctx, settings, user, read) {
|
|
54
|
+
const named = Object.entries(settings.people).find(([, entry]) => entry === user)?.[0] ??
|
|
55
|
+
settings.operators[user] ??
|
|
56
|
+
shown.get(user);
|
|
57
|
+
if (named !== undefined)
|
|
58
|
+
return named;
|
|
59
|
+
const found = await read(ctx, "users.info", { user }, userInfo);
|
|
60
|
+
if (!found.ok) {
|
|
61
|
+
ctx.log(`users.info ${user}: ${found.error.message}, so a message names them as someone`);
|
|
62
|
+
return "someone";
|
|
63
|
+
}
|
|
64
|
+
const { profile, real_name, name } = found.value.user;
|
|
65
|
+
const said = [profile?.display_name, real_name, name].find((text) => text !== undefined && text.trim() !== "");
|
|
66
|
+
if (said === undefined)
|
|
67
|
+
return "someone";
|
|
68
|
+
shown.set(user, said);
|
|
69
|
+
return said;
|
|
70
|
+
}
|
|
71
|
+
/** `args` of a message with each mention of a person that `[extensions.slack] tag` does not name, in its `text` and its blocks, written as that person's plain name, so Slack notifies only the people the project allows. With no `tag`, `args` as they are. */
|
|
72
|
+
export async function untagged(ctx, args, read) {
|
|
73
|
+
const settings = settingsOf(ctx.config);
|
|
74
|
+
if (!settings.ok || settings.value.tag === undefined)
|
|
75
|
+
return args;
|
|
76
|
+
const found = new Set();
|
|
77
|
+
mapped([args["text"], args["blocks"]], (text) => {
|
|
78
|
+
for (const [, user = ""] of text.matchAll(MENTION))
|
|
79
|
+
found.add(user);
|
|
80
|
+
return text;
|
|
81
|
+
});
|
|
82
|
+
if (found.size === 0)
|
|
83
|
+
return args;
|
|
84
|
+
const users = await allowed(ctx, settings.value, settings.value.tag, read);
|
|
85
|
+
const names = new Map();
|
|
86
|
+
for (const user of found) {
|
|
87
|
+
if (users.has(user))
|
|
88
|
+
continue;
|
|
89
|
+
const plain = await plainName(ctx, settings.value, user, read);
|
|
90
|
+
names.set(user, plain.replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">"));
|
|
91
|
+
}
|
|
92
|
+
if (names.size === 0)
|
|
93
|
+
return args;
|
|
94
|
+
const swap = (text) => text.replaceAll(MENTION, (whole, user) => names.get(user) ?? whole);
|
|
95
|
+
return {
|
|
96
|
+
...args,
|
|
97
|
+
...("text" in args ? { text: mapped(args["text"], swap) } : {}),
|
|
98
|
+
...("blocks" in args ? { blocks: mapped(args["blocks"], swap) } : {}),
|
|
99
|
+
};
|
|
100
|
+
}
|
|
@@ -4,7 +4,7 @@ import type { z } from "zod";
|
|
|
4
4
|
import { type APP, type BOT, type SlackCtx } from "#api/client";
|
|
5
5
|
import { type Message } from "#outbound/messages";
|
|
6
6
|
import type { Config } from "#schemas/config";
|
|
7
|
-
import { userInfo } from "#schemas/slack";
|
|
7
|
+
import { type block, userInfo } from "#schemas/slack";
|
|
8
8
|
/** The service's context: the bot token for the Web API and the app token for the socket. */
|
|
9
9
|
export type ServiceCtx = Ctx<typeof BOT | typeof APP>;
|
|
10
10
|
/** The workspace EDGAR's app is in, as the envelope of an event names it. */
|
|
@@ -36,6 +36,8 @@ export declare function linked(text: string): readonly Linked[];
|
|
|
36
36
|
export declare function threadAt(ctx: SlackCtx, channel: string, ts: string): Promise<Result<readonly Message[], Failure>>;
|
|
37
37
|
/** Whether a linked thread may go on a card, which everyone who reads the card sees: only one in `own` channel or in a public channel. A failed `conversations.info` counts as not public. */
|
|
38
38
|
export declare function shareable(ctx: SlackCtx, channel: string, own: string | undefined): Promise<boolean>;
|
|
39
|
+
/** The blocks of a message with no `action` button: an `actions` block keeps its other buttons, and goes when it holds no other. */
|
|
40
|
+
export declare function withoutButton(blocks: readonly z.infer<typeof block>[], action: string): readonly z.infer<typeof block>[];
|
|
39
41
|
/** Routes one Socket Mode envelope's payload, of the inbox `delivery` when it came through the inbox. Each failure is told to the person or logged, so one bad event never stops the service. An event routed again finds what its first routing wrote by the delivery id, and is then not routed again: a stop between routing it and marking it handled does not answer a person twice. */
|
|
40
42
|
export declare function route(ctx: ServiceCtx, settings: Config, type: string, payload: unknown, delivery?: Delivery): Promise<void>;
|
|
41
43
|
export {};
|