@cybernetyx1/atlasflow-slack 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @cybernetyx1/atlasflow-slack
+
+Slack Web API tools and persona slot bindings for AtlasFlow agents — post messages, read channel history, inspect threads, and look up users.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-slack
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+`slackTools(options)` returns the raw Slack tools for an agent. `slackBinding(options)` returns a persona binding that resolves a workspace bot token from the environment and fills the `slack` manifest slot.
+
+```ts
+import { slackTools } from "@cybernetyx1/atlasflow-slack";
+
+// Direct: pass a bot token and a default channel.
+const tools = slackTools({
+  token: process.env.SLACK_BOT_TOKEN,
+  channel: "C0123456789",
+});
+```
+
+```ts
+import { slackBinding } from "@cybernetyx1/atlasflow-slack";
+
+// Persona slot binding: resolves the token from env at runtime.
+const binding = slackBinding({ tokenEnv: "SLACK_BOT_TOKEN", slot: "slack" });
+```
+
+Also exported: `slackToolBinding`, `createSlackClient`, the `SlackApiError` class, and the `SlackToolsOptions` / `SlackEnvBindingOptions` types.
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { PersonaBindings, PersonaToolsBinding, RawTool } from '@cybernetyx1/atlasflow-runtime';
+
+interface SlackToolsOptions {
+    /** Slack bot/user token, usually xoxb-... or xoxp-.... */
+    token?: string;
+    /** Default channel used when a tool call omits channel. */
+    channel?: string;
+    /** Override for compatible Slack API hosts. Defaults to https://slack.com/api. */
+    baseUrl?: string;
+    userAgent?: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    /** Default and maximum history/replies page size. Defaults to 15 for 2025+ Slack limits. */
+    maxHistoryLimit?: number;
+}
+interface SlackEnvBindingOptions extends Omit<SlackToolsOptions, "token" | "channel"> {
+    tokenEnv?: string;
+    channel?: string;
+    channelEnv?: string;
+    /** Manifest slot satisfied by these tools. Defaults to "slack". */
+    slot?: string;
+}
+declare class SlackApiError extends Error {
+    status: number;
+    code: string;
+    details?: unknown | undefined;
+    retryAfter?: number | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined, retryAfter?: number | undefined);
+}
+interface SlackRequestOptions {
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+}
+declare function createSlackClient(options?: SlackToolsOptions): {
+    request: <T extends Record<string, unknown>>(method: string, requestOptions?: SlackRequestOptions) => Promise<T>;
+};
+declare function slackTools(options?: SlackToolsOptions): RawTool[];
+declare function slackToolBinding(options?: SlackEnvBindingOptions): PersonaToolsBinding;
+declare function slackBinding(options?: SlackEnvBindingOptions): PersonaBindings;
+
+export { SlackApiError, type SlackEnvBindingOptions, type SlackRequestOptions, type SlackToolsOptions, createSlackClient, slackBinding, slackToolBinding, slackTools };

package/dist/index.js

@@ -0,0 +1,299 @@
+// src/index.ts
+import { rawTool } from "@cybernetyx1/atlasflow-runtime";
+var SlackApiError = class extends Error {
+  constructor(status, code, message, details, retryAfter) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.retryAfter = retryAfter;
+    this.name = "SlackApiError";
+  }
+  status;
+  code;
+  details;
+  retryAfter;
+};
+var DEFAULT_BASE_URL = "https://slack.com/api";
+var DEFAULT_HISTORY_LIMIT = 15;
+function stringParam(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
+  return value;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function booleanParam(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function integerParam(value, fallback, name, max) {
+  if (value === void 0 || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer`);
+  return max ? Math.min(value, max) : value;
+}
+function resolveChannel(options, args) {
+  return stringParam(args.channel ?? options.channel, "channel");
+}
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0 && v !== null && v !== ""));
+}
+function json(data) {
+  return JSON.stringify(data);
+}
+function qs(query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(stripUndefined(query ?? {}))) params.set(key, String(value));
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+function createSlackClient(options = {}) {
+  const doFetch = options.fetch ?? fetch;
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  async function request(method, requestOptions = {}) {
+    const isPost = requestOptions.body !== void 0;
+    const res = await doFetch(`${base}/${method}${qs(requestOptions.query)}`, {
+      method: isPost ? "POST" : "GET",
+      headers: {
+        accept: "application/json",
+        ...isPost ? { "content-type": "application/json" } : {},
+        "user-agent": options.userAgent ?? "atlasflow-slack",
+        ...options.token ? { authorization: `Bearer ${options.token}` } : {},
+        ...options.headers
+      },
+      body: isPost ? JSON.stringify(stripUndefined(requestOptions.body ?? {})) : void 0
+    });
+    const retryAfterRaw = res.headers.get("retry-after");
+    const retryAfter = retryAfterRaw ? Number(retryAfterRaw) : void 0;
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new SlackApiError(res.status, res.status === 429 ? "slack_rate_limited" : "slack_http_error", res.statusText, data, retryAfter);
+    }
+    if (data.ok === false) {
+      const code = typeof data.error === "string" ? data.error : "slack_error";
+      throw new SlackApiError(res.status, code, code, data);
+    }
+    return data;
+  }
+  return { request };
+}
+function slackTools(options = {}) {
+  const client = createSlackClient(options);
+  const maxHistoryLimit = options.maxHistoryLimit ?? DEFAULT_HISTORY_LIMIT;
+  return [
+    rawTool({
+      name: "slack_post_message",
+      description: "Post a message to a Slack channel, DM, or thread.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel, DM, or MPIM id. Optional when bound by the workspace."),
+          text: stringSchema("Message text."),
+          thread_ts: stringSchema("Thread timestamp for replies."),
+          mrkdwn: booleanSchema("Whether Slack should parse mrkdwn. Defaults to true."),
+          blocks: { type: "array", description: "Optional Slack Block Kit blocks." }
+        },
+        ["text"]
+      ),
+      execute: async (args) => {
+        const res = await client.request("chat.postMessage", {
+          body: {
+            channel: resolveChannel(options, args),
+            text: stringParam(args.text, "text"),
+            thread_ts: optionalString(args.thread_ts),
+            mrkdwn: booleanParam(args.mrkdwn),
+            blocks: Array.isArray(args.blocks) ? args.blocks : void 0
+          }
+        });
+        return json({ channel: res.channel, ts: res.ts, message: res.message, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_reply_to_thread",
+      description: "Reply to an existing Slack message thread.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel id. Optional when bound by the workspace."),
+          thread_ts: stringSchema("Parent message timestamp."),
+          text: stringSchema("Reply text."),
+          mrkdwn: booleanSchema("Whether Slack should parse mrkdwn. Defaults to true.")
+        },
+        ["thread_ts", "text"]
+      ),
+      execute: async (args) => {
+        const res = await client.request("chat.postMessage", {
+          body: {
+            channel: resolveChannel(options, args),
+            thread_ts: stringParam(args.thread_ts, "thread_ts"),
+            text: stringParam(args.text, "text"),
+            mrkdwn: booleanParam(args.mrkdwn)
+          }
+        });
+        return json({ channel: res.channel, ts: res.ts, message: res.message, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_list_channel_history",
+      description: "Read recent messages from a Slack conversation.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel id. Optional when bound by the workspace."),
+          limit: integerSchema("Maximum messages to return."),
+          cursor: stringSchema("Pagination cursor."),
+          oldest: stringSchema("Only messages after this timestamp."),
+          latest: stringSchema("Only messages before this timestamp."),
+          inclusive: booleanSchema("Include messages matching oldest/latest.")
+        },
+        []
+      ),
+      execute: async (args) => {
+        const limit = integerParam(args.limit, maxHistoryLimit, "limit", maxHistoryLimit);
+        const res = await client.request("conversations.history", {
+          query: {
+            channel: resolveChannel(options, args),
+            limit,
+            cursor: optionalString(args.cursor),
+            oldest: optionalString(args.oldest),
+            latest: optionalString(args.latest),
+            inclusive: booleanParam(args.inclusive)
+          }
+        });
+        return json({ messages: res.messages, has_more: res.has_more, response_metadata: res.response_metadata, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_get_thread_replies",
+      description: "Read replies in a Slack thread.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel id. Optional when bound by the workspace."),
+          thread_ts: stringSchema("Parent message timestamp."),
+          limit: integerSchema("Maximum messages to return."),
+          cursor: stringSchema("Pagination cursor.")
+        },
+        ["thread_ts"]
+      ),
+      execute: async (args) => {
+        const limit = integerParam(args.limit, maxHistoryLimit, "limit", maxHistoryLimit);
+        const res = await client.request("conversations.replies", {
+          query: {
+            channel: resolveChannel(options, args),
+            ts: stringParam(args.thread_ts, "thread_ts"),
+            limit,
+            cursor: optionalString(args.cursor)
+          }
+        });
+        return json({ messages: res.messages, has_more: res.has_more, response_metadata: res.response_metadata, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_get_channel_info",
+      description: "Fetch metadata for a Slack conversation.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel, DM, or MPIM id. Optional when bound by the workspace."),
+          include_num_members: booleanSchema("Include member count when available.")
+        },
+        []
+      ),
+      execute: async (args) => {
+        const res = await client.request("conversations.info", {
+          query: {
+            channel: resolveChannel(options, args),
+            include_num_members: booleanParam(args.include_num_members)
+          }
+        });
+        return json({ channel: res.channel, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_get_user_info",
+      description: "Fetch Slack user profile/account metadata.",
+      parameters: schema({ user: stringSchema("Slack user id.") }, ["user"]),
+      execute: async (args) => {
+        const res = await client.request("users.info", { query: { user: stringParam(args.user, "user") } });
+        return json({ user: res.user, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_open_dm",
+      description: "Open a direct-message or multi-person DM conversation.",
+      parameters: schema(
+        {
+          user: stringSchema("Single Slack user id."),
+          users: { type: "array", description: "Slack user ids for MPIM.", items: { type: "string" } },
+          return_im: booleanSchema("Return full IM object.")
+        },
+        []
+      ),
+      execute: async (args) => {
+        const users = Array.isArray(args.users) ? args.users.map((u) => stringParam(u, "users[]")).join(",") : optionalString(args.user);
+        const res = await client.request("conversations.open", {
+          body: { users: stringParam(users, "user or users"), return_im: booleanParam(args.return_im) }
+        });
+        return json({ channel: res.channel, no_op: res.no_op, already_open: res.already_open, warning: res.warning });
+      }
+    }),
+    rawTool({
+      name: "slack_add_reaction",
+      description: "Add an emoji reaction to a Slack message.",
+      parameters: schema(
+        {
+          channel: stringSchema("Channel id. Optional when bound by the workspace."),
+          timestamp: stringSchema("Message timestamp."),
+          name: stringSchema("Emoji name without surrounding colons.")
+        },
+        ["timestamp", "name"]
+      ),
+      execute: async (args) => {
+        const res = await client.request("reactions.add", {
+          body: {
+            channel: resolveChannel(options, args),
+            timestamp: stringParam(args.timestamp, "timestamp"),
+            name: stringParam(args.name, "name").replace(/^:|:$/g, "")
+          }
+        });
+        return json({ ok: res.ok, warning: res.warning });
+      }
+    })
+  ];
+}
+function slackToolBinding(options = {}) {
+  return ({ env }) => slackTools({
+    ...options,
+    token: readEnv(env, options.tokenEnv ?? "SLACK_BOT_TOKEN", false),
+    channel: options.channel ?? readEnv(env, options.channelEnv ?? "SLACK_CHANNEL_ID", false)
+  });
+}
+function slackBinding(options = {}) {
+  const slot = options.slot ?? "slack";
+  return { toolSlots: { [slot]: slackToolBinding(options) } };
+}
+function readEnv(env, name, required) {
+  const value = env[name];
+  if (typeof value === "string" && value) return value;
+  if (required) throw new Error(`${name} is required for Slack tools`);
+  return void 0;
+}
+function stringSchema(description) {
+  return { type: "string", description };
+}
+function booleanSchema(description) {
+  return { type: "boolean", description };
+}
+function integerSchema(description) {
+  return { type: "integer", minimum: 1, description };
+}
+function schema(properties, required) {
+  return {
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false
+  };
+}
+export {
+  SlackApiError,
+  createSlackClient,
+  slackBinding,
+  slackToolBinding,
+  slackTools
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cybernetyx1/atlasflow-slack",
+  "version": "0.1.0",
+  "description": "Slack Web API tools and bindings for AtlasFlow agents.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/slack"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cybernetyx1/atlasflow-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}