@amykit/plugin-slack 0.5.0 → 0.7.0

package/README.md

@@ -6,11 +6,23 @@ A Slack thread per piece of work, over the Web API, as the conversation port.
 
 A plugin for [amy](https://github.com/nicolasmelo1/amy). It provides the `conversation` port.
 
+Use it when you want to follow and answer amy from Slack. It mounts the conversation port: each piece of work gets a thread in one channel, and only the operator's replies count as answers. It can also hold amy's chat. It needs a bot token, read from the environment or a file.
+
+## What it extends
+
+|  |  |
+| :-- | :-- |
+| Ports | `conversation` |
+| Actions | _none_ |
+| Operations | _none_ |
+| Commands | _none_ |
+| Events | _none_ |
+| Environment | _none_ |
+
 ## Install
 
 ```sh
-# Add @amykit/plugin-slack to amy.yaml, then install configured plugins:
-amy init --install
+amy add @amykit/plugin-slack
 ```
 
 Then name it in `~/.amy/config.yaml`:
@@ -28,8 +40,10 @@ workflows:
 plugins:
   "@amykit/plugin-slack":
     channel: <string>
+    decisionReaction: "white_check_mark"
     defaultRetryAfterSeconds: 60
     directory: "slack"
+    discussionReaction: "speech_balloon"
     maxRateLimitRetries: 5
     operator: <string>
     retentionDays: 30
@@ -39,8 +53,10 @@ plugins:
 | Setting | Type | Required | Default | What it is |
 | :-- | :-- | :-- | :-- | :-- |
 | `channel` | `string` | **yes** |  | the channel id every work thread opens in, such as C0XXXXXXX — an id, not a name |
+| `decisionReaction` | `string` | no | `white_check_mark` | the reaction, by emoji name, the operator puts on their own reply to mark it as the decision that moves the work. A reaction Slack lists only in part is read again in full with reactions.get, which needs reactions:read |
 | `defaultRetryAfterSeconds` | `number` | no | `60` | how long to wait after a 429 that carries no Retry-After; one names its own wait, and that wins |
 | `directory` | `string` | no | `slack` | where each work item's thread is remembered, relative to the state directory |
+| `discussionReaction` | `string` | no | `speech_balloon` | the reaction, by emoji name, the operator puts on their own reply to mark it as a turn in a discussion, answered in the thread while the work waits |
 | `maxRateLimitRetries` | `number` | no | `5` | how many times a call Slack rate limits (HTTP 429) is waited out and tried again before it fails |
 | `operator` | `string` | **yes** |  | the user id, such as U0XXXXXXX, whose replies are answers; everybody else's are ignored |
 | `retentionDays` | `number` | no | `30` | days a downloaded file or a thread's memory stays unused before it is pruned, 0 to keep everything. A pruned file is fetched again when its reply is read; a pruned thread means the next question opens a new one |
@@ -52,7 +68,7 @@ silently never applied.
 
 ## Where the reasoning is
 
-- [Writing a plugin](https://github.com/nicolasmelo1/amy/tree/main/docs/build/write-a-plugin.md)
+- [Writing a plugin](https://github.com/nicolasmelo1/amy/tree/main/docs/guides/write-a-plugin.md)
 - [Reference: plugins](https://github.com/nicolasmelo1/amy/tree/main/docs/reference/plugins.md)
 - [Ports and the registry](https://github.com/nicolasmelo1/amy/tree/main/docs/concepts/ports.md)
 

package/dist/SlackConversation.d.ts

@@ -1,4 +1,4 @@
-import { Conversation, Reply, ThreadRef } from "@amykit/core";
+import { Ask, ChatMessage, Conversation, Reply, ThreadRef } from "@amykit/core";
 import { SlackApi } from "./SlackApi.js";
 export interface SlackConversationOptions {
     /** A channel id, not a name. */
@@ -18,6 +18,17 @@ export interface SlackConversationOptions {
      * pruned; `0` keeps everything.
      */
     retentionDays?: number;
+    /**
+     * The reactions the operator puts on their own reply to mark what it is,
+     * by emoji name. A reply without one carries no kind, and the workflow's
+     * policy reads it.
+     */
+    marks?: {
+        decision: string;
+        discussion: string;
+    };
+    /** Inspection reads existing state but never creates or changes it. */
+    readOnly?: boolean;
     now?: () => Date;
 }
 /** What `amy doctor` prints for this plugin, one line per question. */
@@ -28,10 +39,20 @@ export interface SlackCheck {
 }
 /** Long enough for an operator's holiday, short enough that screenshots do not pile up. */
 export declare const DEFAULT_RETENTION_DAYS = 30;
+/** ✅ settles it, 💬 asks something first. */
+export declare const DEFAULT_MARKS: {
+    readonly decision: "white_check_mark";
+    readonly discussion: "speech_balloon";
+};
 export declare class SlackConversation implements Conversation {
     private readonly api;
     private readonly options;
-    private readonly threads;
+    readonly asks: true;
+    readonly threads: true;
+    readonly edit: true;
+    /** The channel: its conversations and claims are its own. */
+    get source(): string;
+    private readonly threadMap;
     private readonly filesDirectory;
     private readonly opening;
     private botUser?;
@@ -41,6 +62,7 @@ export declare class SlackConversation implements Conversation {
     post(thread: ThreadRef, message: {
         text: string;
         files?: string[];
+        ask?: Ask;
     }): Promise<string>;
     replies(thread: ThreadRef, since: string): Promise<Reply[]>;
     /**
@@ -66,6 +88,41 @@ export declare class SlackConversation implements Conversation {
         threads: number;
         files: number;
     };
+    /**
+     * The messages in the channel that reached no work, oldest first, until
+     * they are settled: a root message the operator posts, and the operator's
+     * replies in that root's thread, which is one conversation (S14). The
+     * channel is read for them first, so it is read all the time (S20).
+     */
+    chat(): Promise<ChatMessage[]>;
+    settle(id: string): Promise<void>;
+    /** Says something in a conversation's thread. */
+    say(place: string, text: string): Promise<string>;
+    revise(_place: string, id: string, text: string): Promise<void>;
+    /**
+     * Files the operator's new root messages, and their replies in the
+     * threads of conversations still going, each once. The first read starts
+     * from now: what was said in the channel before amy listened is not asked
+     * of it. A thread goes quiet a day after the operator last wrote in it.
+     */
+    private fileChat;
+    /** The chat's own state, by channel: a channel changed in the config starts afresh and never answers the old one's messages. */
+    private chatDirectory;
+    /**
+     * One conversation's replies per minute, whichever has waited longest:
+     * Slack may allow conversations.replies once a minute for the whole app, not
+     * once per thread, so the chat shares that one call rather than queueing.
+     */
+    private fileDueReplies;
+    /** The operator's root messages since the cursor, each a conversation from now on; answers the new cursor. */
+    private fileRoots;
+    /** The operator's replies in one conversation's thread, at most once a minute, until it goes quiet. */
+    private fileReplies;
+    /** One channel-wide conversations.replies allowance, shared by chat and work threads. */
+    private repliesQuota;
+    private fileChatMessage;
+    /** The operator, writing as themselves: no bot, no other person, no channel event. */
+    private isOperatorMessage;
     private clock;
     /** Where one thread's downloads live, so forgetting it takes them too. */
     private threadFiles;
@@ -79,6 +136,31 @@ export declare class SlackConversation implements Conversation {
     private dropFiles;
     /** Throttled, and never the reason a call fails: pruning is housekeeping. */
     private pruneNowAndThen;
+    private postText;
+    private postAskFallback;
+    /** Reconstruct answers from Slack every time; no accepted-answer cache survives a process. */
+    private askedReplies;
+    /** The answer this ask holds after this look, if any: the remembered one, or the first complete one seen now. */
+    private acceptedAnswer;
+    /** The first complete answer is immutable once seen, even if its reaction changes later. */
+    protected rememberedAnswer(threadTs: string, askId: string): {
+        chosen: string[];
+        messageTs: string;
+        acceptedAt?: string;
+    } | undefined;
+    /** Creates the decision once; a competing reader adopts the value written first. */
+    private rememberAnswer;
+    /** The first ask amy posted in this thread, as microseconds, if it kept one. */
+    private askedFrom;
+    /** Keeps the earliest ask's ts; a later ask leaves it where it is. */
+    private rememberAskedFrom;
+    private answerFile;
+    private answerDirectory;
+    private hasChangedAnswer;
+    private answerOf;
+    private completeReactions;
+    private explainAmbiguity;
+    private acknowledgeTaken;
     private channelChecks;
     /**
      * Exactly one process posts a root per attempt; an attempt that follows
@@ -92,9 +174,26 @@ export declare class SlackConversation implements Conversation {
      * text: two items can share a title, and a title can change.
      */
     private findRoot;
-    /** Every message in the thread after `afterMicros`, across pages. */
+    /** Every message in the thread after `afterMicros`, or from it on when `inclusive`: Slack leaves the bound out by default. */
     private threadMessages;
     private pages;
+    /**
+     * What the operator marked their reply as, by their own reaction on it and
+     * nobody else's — never by its text. Both marks read as the decision, the
+     * one that moves the work, because a person who put both meant to be done.
+     * Re-read on every look, so marking a reply after it was answered counts.
+     *
+     * Slack may list only some of a reaction's users while `count` holds them
+     * all. Only a mark whose answer could still change the kind is asked again
+     * in full, and a reply the operator may have marked is never read as
+     * unmarked: if the full list still cannot say, the read fails and says why.
+     */
+    private kindOf;
+    /** The kind these reactions say, or UNKNOWN when a list too short to tell could change it. */
+    private kindFrom;
+    /** Whether the operator put this reaction on, or UNKNOWN when Slack's list is short and leaves them out. */
+    private marked;
+    private allReactions;
     /** By author id, never by a marker in the text. */
     private isOperatorAnswer;
     /** Cached once known; a failure is not, so the next poll asks again. */

package/dist/SlackConversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SlackConversation.d.ts","sourceRoot":"","sources":["../src/SlackConversation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAY,MAAM,eAAe,CAAC;AAGnD,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgCD,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAUzC,qBAAa,iBAAkB,YAAW,YAAY;IAQlD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAA4B;gBAGzB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,wBAAwB;IAapD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAoBjD,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBrF,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAyBjE;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAWrC;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;OAIG;IACH,KAAK,CAAC,GAAG,GAAE,IAAmB,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAanE,OAAO,CAAC,KAAK;IAIb,0EAA0E;IAC1E,OAAO,CAAC,WAAW;IAInB,2EAA2E;IAC3E,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAMjB,6EAA6E;IAC7E,OAAO,CAAC,eAAe;YAWT,aAAa;IAgC3B;;;OAGG;YACW,WAAW;IAmBzB;;;;;OAKG;YACW,QAAQ;IAetB,qEAAqE;IACrE,OAAO,CAAC,cAAc;YAIR,KAAK;IAYnB,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IAOxB,wEAAwE;IACxE,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;YACW,WAAW;IAwBzB,uEAAuE;YACzD,QAAQ;CAqBvB"}
+{"version":3,"file":"SlackConversation.d.ts","sourceRoot":"","sources":["../src/SlackConversation.ts"],"names":[],"mappings":"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"}