@eliya-oss/agent-slack 0.1.0

package/.agents/cli-api.md

@@ -0,0 +1,295 @@
+# Agent Slack CLI API
+
+Technical contract derived from `.agents/prd/001-agent-readable-slack-interface.md`. Product behavior changes belong in PRD first.
+
+Working binary name: `slk`.
+
+Goal: OAuth into Slack, expose everything Slack Web API permissions allow, and give agents stable commands for reading channels, threads, files, users, and search context.
+
+Non-goal for v0: agent-side summarization. The CLI returns clean context; agents summarize it.
+
+## Design Rules
+
+- Noun-verb commands: `slk conversation history`, `slk thread get`, `slk api call`.
+- JSON is always available with `--json`; non-TTY stdout defaults to JSON.
+- Data goes to stdout. Progress, warnings, and errors go to stderr.
+- Every command supports `--help --json`; every group supports `describe --json`.
+- Large reads support `--cursor`, `--limit`, `--all`, and `--format ndjson`.
+- Raw Slack Web API access is first-class through `slk api call`.
+- Read commands are safe by default. Any future write/destructive command needs `--yes`; `api call` blocks known write methods unless `--allow-write`.
+
+## Global Flags
+
+```bash
+slk [--profile NAME] [--team TEAM_ID] [--token user|bot|admin|app]
+    [--json] [--format json|ndjson|table] [--fields FIELD[,FIELD...]]
+    [--limit N] [--cursor CURSOR] [--all]
+    [--include users,reactions,files,permalinks,threads]
+    [--no-cache] [--trace]
+```
+
+Defaults:
+
+- `--token user` for user-visible data.
+- `--format json` when stdout is not a TTY.
+- `--limit` uses Slack's method default unless a command defines a smaller agent-safe default.
+
+## Auth
+
+```bash
+slk auth login
+slk auth login --profile work --scopes channels:read,channels:history --user-scopes search:read.public,search:read.private
+slk auth login --oauth --client-id CLIENT_ID --client-secret CLIENT_SECRET --auth-url-out /tmp/slk-auth-url
+slk auth status
+slk auth scopes
+slk auth profiles list
+slk auth logout --profile work
+```
+
+Auth behavior:
+
+- Uses Slack OAuth v2 with a localhost callback.
+- Bot scopes go in `scope=...`; user scopes go in `user_scope=...`.
+- Stores profiles outside the project directory. The default store is `~/.config/slk/profiles.json`; set `SLK_TOKEN_STORE=keychain` on macOS to keep token secrets in Keychain and only profile metadata on disk.
+- Supports multiple profiles and workspaces.
+- `auth status --json` returns token type, team, enterprise, user/bot identity, granted scopes, and missing recommended scopes.
+
+Scope presets:
+
+```bash
+slk auth login --preset read-user
+slk auth login --preset read-bot
+slk auth login --preset assistant-search
+slk auth login --preset admin-read
+```
+
+Preset intent:
+
+- `read-user`: read what the installing user can access.
+- `read-bot`: read conversations where the bot is present.
+- `assistant-search`: use Slack's Real-time Search API for agent context retrieval.
+- `admin-read`: Enterprise Grid admin read surfaces when installed by an org admin.
+
+Important Slack boundary: there is no token that means "read all Slack." Slack only returns data allowed by the granted scopes, token type, workspace/org install, channel membership, and Slack plan/admin policy.
+
+## Core Read Commands
+
+### Workspaces and identity
+
+```bash
+slk auth test
+slk team get
+slk team profile get
+slk enterprise get
+```
+
+### Users
+
+```bash
+slk user list [--all]
+slk user get USER_ID
+slk user lookup --email EMAIL
+slk user presence get USER_ID
+slk usergroups list
+slk usergroups users list USERGROUP_ID
+```
+
+### Conversations
+
+```bash
+slk conversation list --types public_channel,private_channel,mpim,im [--all]
+slk conversation get CHANNEL_ID
+slk conversation members CHANNEL_ID [--all]
+slk conversation history CHANNEL_ID [--oldest TS] [--latest TS] [--all]
+slk conversation context CHANNEL_ID [--since 24h] [--include users,reactions,files,threads]
+```
+
+`conversation context` is the agent-friendly form: normalized messages, hydrated users, thread refs, file refs, reactions, and permalinks in one deterministic payload.
+
+### Threads and messages
+
+```bash
+slk thread get --channel CHANNEL_ID --ts MESSAGE_TS [--include users,reactions,files,permalinks]
+slk message get --channel CHANNEL_ID --ts MESSAGE_TS
+slk message permalink --channel CHANNEL_ID --ts MESSAGE_TS
+```
+
+`message get` wraps the Slack history/replies calls needed to fetch one timestamp.
+
+### Search
+
+```bash
+slk search context --query QUERY [--channel-types public_channel,private_channel,mpim,im] [--content-types messages,files,channels]
+slk search messages --query QUERY
+slk search files --query QUERY
+```
+
+Prefer `search context` for agents. It maps to Slack's Real-time Search API where available. `search messages` and `search files` are legacy-compatible convenience commands.
+
+### Files and attached context
+
+```bash
+slk file list [--channel CHANNEL_ID] [--user USER_ID] [--all]
+slk file get FILE_ID
+slk file download FILE_ID --out PATH
+slk file comments list FILE_ID
+```
+
+### Other readable Slack surfaces
+
+```bash
+slk reaction get --channel CHANNEL_ID --ts MESSAGE_TS
+slk pin list CHANNEL_ID
+slk bookmark list CHANNEL_ID
+slk canvas list [--channel CHANNEL_ID]
+slk canvas get CANVAS_ID
+slk list list [--channel CHANNEL_ID]
+slk list get LIST_ID
+slk emoji list
+slk reminder list
+slk star list
+slk dnd status [USER_ID]
+```
+
+## Generic Web API Escape Hatch
+
+This is what gives full Web API coverage.
+
+```bash
+slk api methods list [--family conversations]
+slk api method describe conversations.history
+slk api call conversations.history --payload '{"channel":"C123","limit":50}'
+slk api call conversations.history --payload @payload.json
+cat payload.json | slk api call conversations.history -
+```
+
+Rules:
+
+- `--payload`, `@file`, and `-` pass raw JSON matching Slack's API fields.
+- Convenience flags may be added later, but raw payload always wins coverage.
+- `--raw` returns Slack's exact response body.
+- Without `--raw`, responses use the CLI envelope below.
+- `--all --format ndjson` streams item records for cursor-paginated methods.
+- Known write/admin-mutating methods require `--allow-write --yes`.
+
+## Output Contract
+
+Default JSON envelope:
+
+```json
+{
+  "ok": true,
+  "method": "conversations.history",
+  "team_id": "T123",
+  "enterprise_id": null,
+  "profile": "work",
+  "data": {},
+  "paging": {
+    "next_cursor": null,
+    "has_more": false
+  },
+  "warnings": []
+}
+```
+
+NDJSON streaming record:
+
+```json
+{"ok":true,"type":"slack.message","team_id":"T123","channel_id":"C123","ts":"1710000000.000100","data":{}}
+```
+
+Structured error on stderr:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "rate_limited",
+    "title": "Slack rate limit reached",
+    "slack_error": "ratelimited",
+    "retriable": true,
+    "retry_after_seconds": 60,
+    "suggestion": "Retry after the provided delay or use --limit with a smaller page size.",
+    "trace_id": "slk_..."
+  }
+}
+```
+
+Exit codes:
+
+- `0`: success
+- `1`: runtime/API failure
+- `2`: usage or validation error
+- `3`: not found
+- `4`: auth or permission denied
+- `5`: conflict or invalid Slack state
+- `6`: rate limited
+
+Rate-limit behavior:
+
+- Honor Slack `Retry-After` headers.
+- Return exit code `6` with `retry_after_seconds` when Slack throttles.
+- `conversation history`, `thread get`, and `api call conversations.replies` must support resumable pagination.
+- Commercial non-Marketplace apps can have much stricter `conversations.history` and `conversations.replies` limits than internal or Marketplace apps.
+
+## Schema Introspection
+
+```bash
+slk describe --json
+slk conversation describe --json
+slk conversation history --help --json
+slk api method describe conversations.replies --json
+```
+
+Schema output includes:
+
+- command description and examples
+- positional args and flags
+- raw payload schema when known
+- required Slack method/scopes
+- output schema
+- pagination behavior
+- safety classification: `read`, `write`, `destructive`, or `admin`
+
+## Agent Workflows
+
+Read a thread:
+
+```bash
+slk thread get --channel C123 --ts 1710000000.000100 --include users,reactions,files,permalinks --json
+```
+
+Prepare channel-summary input:
+
+```bash
+slk conversation context C123 --since 24h --include users,reactions,files,threads --format ndjson
+```
+
+Search before reading:
+
+```bash
+slk search context --query "latest on project atlas" --content-types messages,files --json
+```
+
+Call a new Slack method before the CLI has a wrapper:
+
+```bash
+slk api call some.newMethod --payload @request.json --json
+```
+
+## Build Order
+
+1. Auth profiles, keychain storage, and `auth test/status/scopes`.
+2. Generic `api call`, raw payload input, JSON envelope, structured errors.
+3. `describe --json` and generated method catalog.
+4. Conversation, thread, user, file, and search convenience commands.
+5. Agent context commands with hydration and NDJSON streaming.
+6. Admin/read-extra surfaces and write-gated API calls.
+
+## References
+
+- Agent Surface CLI design: https://agentsurface.dev/docs/cli-design
+- Agent Surface schema introspection: https://agentsurface.dev/docs/cli-design/schema-introspection
+- Slack OAuth: https://docs.slack.dev/authentication/installing-with-oauth
+- Slack Web API methods: https://docs.slack.dev/reference/methods/
+- Slack Real-time Search API: https://docs.slack.dev/apis/web-api/real-time-search-api

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @eliya-oss/agent-slack
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release of the Slack agent CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-slack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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,39 @@
+<div align="center">
+
+# Agent Slack
+
+Slack context for AI agents, exposed through the `slk` CLI.
+
+```bash
+npm install -g @eliya-oss/agent-slack
+```
+
+<img src="./assets/terminal.svg" alt="Agent Slack terminal screenshot" width="820">
+
+</div>
+
+## Usage
+
+```bash
+slk auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --json
+slk conversation history C123 --limit 50 --json
+slk thread get --channel C123 --ts 1710000000.000100 --include users,permalinks --json
+slk conversation context C123 --include users,threads,permalinks --format ndjson
+slk api call conversations.info --payload '{"channel":"C123"}' --json
+```
+
+## Skill
+
+```bash
+npx skills add Newbie012/agent-slack --skill agent-slack
+```
+
+## Notes
+
+Agent Slack respects Slack permissions: it only returns data allowed by the active token, scopes, channel membership, workspace policy, and Slack plan.
+
+Project docs live in `.agents/`.
+
+## License
+
+MIT

package/assets/terminal.svg

@@ -0,0 +1,32 @@
+<svg width="980" height="560" viewBox="0 0 980 560" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Agent Slack terminal screenshot</title>
+  <desc id="desc">A terminal showing Agent Slack commands that read Slack context as JSON and NDJSON.</desc>
+  <rect width="980" height="560" rx="18" fill="#111827"/>
+  <rect x="22" y="22" width="936" height="516" rx="14" fill="#0B1020" stroke="#263244"/>
+  <rect x="22" y="22" width="936" height="48" rx="14" fill="#151D2E"/>
+  <circle cx="52" cy="46" r="7" fill="#FF5F57"/>
+  <circle cx="76" cy="46" r="7" fill="#FFBD2E"/>
+  <circle cx="100" cy="46" r="7" fill="#28C840"/>
+  <text x="490" y="51" text-anchor="middle" fill="#94A3B8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">agent-slack</text>
+
+  <text x="54" y="116" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
+  <text x="78" y="116" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">npm install -g @eliya-oss/agent-slack</text>
+
+  <text x="54" y="162" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
+  <text x="78" y="162" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">slk auth status --json</text>
+  <text x="78" y="196" fill="#93C5FD" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{ "ok": true, "profile": "work", "data": { "teamId": "T123" } }</text>
+
+  <text x="54" y="250" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
+  <text x="78" y="250" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">slk conversation context C123 --include users,threads --format ndjson</text>
+  <text x="78" y="284" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{"type":"slack.message","channel_id":"C123","ts":"1710000000.000100","text":"Ship status?"}</text>
+  <text x="78" y="314" fill="#FDE68A" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{"type":"slack.message","channel_id":"C123","thread_ts":"1710000000.000100","text":"Green."}</text>
+
+  <text x="54" y="368" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
+  <text x="78" y="368" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">slk thread get --channel C123 --ts 1710000000.000100 --include users --json</text>
+  <text x="78" y="402" fill="#C4B5FD" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">{ "ok": true, "method": "conversations.replies", "data": { "messages": [ ... ] } }</text>
+
+  <text x="54" y="456" fill="#22C55E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$</text>
+  <text x="78" y="456" fill="#E5E7EB" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">slk api call conversations.info --payload '{"channel":"C123"}' --json</text>
+  <rect x="54" y="488" width="210" height="28" rx="6" fill="#122034"/>
+  <text x="70" y="508" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">stdout is parseable JSON</text>
+</svg>

package/dist/adapters/catalog/BundledMethodCatalog.js

@@ -0,0 +1,53 @@
+const methods = [
+    { method: "api.test", family: "api", summary: "Test Slack API reachability.", safety: "read", scopes: [], cursorPaginated: false },
+    { method: "auth.test", family: "auth", summary: "Test authentication.", safety: "read", scopes: [], cursorPaginated: false },
+    { method: "team.info", family: "team", summary: "Workspace info.", safety: "read", scopes: ["team:read"], cursorPaginated: false },
+    { method: "team.profile.get", family: "team", summary: "Workspace profile fields.", safety: "read", scopes: ["users.profile:read"], cursorPaginated: false },
+    { method: "conversations.list", family: "conversations", summary: "List conversations.", safety: "read", scopes: ["channels:read", "groups:read", "im:read", "mpim:read"], itemKey: "channels", cursorPaginated: true },
+    { method: "conversations.info", family: "conversations", summary: "Conversation info.", safety: "read", scopes: ["channels:read", "groups:read", "im:read", "mpim:read"], cursorPaginated: false },
+    { method: "conversations.members", family: "conversations", summary: "Conversation members.", safety: "read", scopes: ["channels:read", "groups:read", "im:read", "mpim:read"], itemKey: "members", cursorPaginated: true },
+    { method: "conversations.history", family: "conversations", summary: "Conversation history.", safety: "read", scopes: ["channels:history", "groups:history", "im:history", "mpim:history"], itemKey: "messages", cursorPaginated: true },
+    { method: "conversations.replies", family: "conversations", summary: "Thread replies.", safety: "read", scopes: ["channels:history", "groups:history", "im:history", "mpim:history"], itemKey: "messages", cursorPaginated: true },
+    { method: "chat.getPermalink", family: "chat", summary: "Message permalink.", safety: "read", scopes: [], cursorPaginated: false },
+    { method: "users.list", family: "users", summary: "List users.", safety: "read", scopes: ["users:read"], itemKey: "members", cursorPaginated: true },
+    { method: "users.info", family: "users", summary: "User info.", safety: "read", scopes: ["users:read"], cursorPaginated: false },
+    { method: "users.lookupByEmail", family: "users", summary: "Find user by email.", safety: "read", scopes: ["users:read.email"], cursorPaginated: false },
+    { method: "users.getPresence", family: "users", summary: "User presence.", safety: "read", scopes: ["users:read"], cursorPaginated: false },
+    { method: "usergroups.list", family: "usergroups", summary: "List user groups.", safety: "read", scopes: ["usergroups:read"], itemKey: "usergroups", cursorPaginated: false },
+    { method: "usergroups.users.list", family: "usergroups", summary: "List users in a user group.", safety: "read", scopes: ["usergroups:read"], itemKey: "users", cursorPaginated: false },
+    { method: "files.list", family: "files", summary: "List files.", safety: "read", scopes: ["files:read"], itemKey: "files", cursorPaginated: true },
+    { method: "files.info", family: "files", summary: "File info.", safety: "read", scopes: ["files:read"], cursorPaginated: false },
+    { method: "reactions.get", family: "reactions", summary: "Message reactions.", safety: "read", scopes: ["reactions:read"], cursorPaginated: false },
+    { method: "pins.list", family: "pins", summary: "Pinned items.", safety: "read", scopes: ["pins:read"], itemKey: "items", cursorPaginated: false },
+    { method: "bookmarks.list", family: "bookmarks", summary: "Channel bookmarks.", safety: "read", scopes: ["bookmarks:read"], itemKey: "bookmarks", cursorPaginated: false },
+    { method: "emoji.list", family: "emoji", summary: "Workspace emoji.", safety: "read", scopes: ["emoji:read"], cursorPaginated: false },
+    { method: "dnd.info", family: "dnd", summary: "DND status.", safety: "read", scopes: ["dnd:read"], cursorPaginated: false },
+    { method: "search.messages", family: "search", summary: "Legacy message search.", safety: "read", scopes: ["search:read.public", "search:read.private"], itemKey: "matches", cursorPaginated: false },
+    { method: "search.files", family: "search", summary: "Legacy file search.", safety: "read", scopes: ["search:read.files"], itemKey: "matches", cursorPaginated: false },
+    { method: "assistant.search.context", family: "assistant", summary: "Real-time Search API context.", safety: "read", scopes: ["search:read.public", "search:read.private"], itemKey: "results", cursorPaginated: false },
+    { method: "chat.postMessage", family: "chat", summary: "Post message.", safety: "write", scopes: ["chat:write"], cursorPaginated: false },
+    { method: "chat.delete", family: "chat", summary: "Delete message.", safety: "destructive", scopes: ["chat:write"], cursorPaginated: false },
+    { method: "files.delete", family: "files", summary: "Delete file.", safety: "destructive", scopes: ["files:write"], cursorPaginated: false }
+];
+const unsafePrefixes = ["admin.", "chat.post", "chat.update", "chat.delete", "files.delete", "conversations.archive", "conversations.kick"];
+export class BundledMethodCatalog {
+    listMethods(family) {
+        return family === undefined ? methods : methods.filter((method) => method.family === family);
+    }
+    describeMethod(method) {
+        return methods.find((item) => item.method === method) ?? null;
+    }
+    safetyFor(method) {
+        const found = this.describeMethod(method);
+        if (found !== null) {
+            return found.safety;
+        }
+        if (unsafePrefixes.some((prefix) => method.startsWith(prefix))) {
+            return method.startsWith("admin.") ? "admin" : "write";
+        }
+        return "unknown";
+    }
+    itemKeyFor(method) {
+        return this.describeMethod(method)?.itemKey ?? null;
+    }
+}

package/dist/adapters/http-file-downloader/HttpFileDownloader.js

@@ -0,0 +1,20 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { SlackApiFailed } from "../../domain/errors.js";
+export class HttpFileDownloader {
+    async download(input) {
+        const response = await fetch(input.url, {
+            headers: { authorization: `Bearer ${input.token}` }
+        });
+        if (!response.ok) {
+            throw new SlackApiFailed(`Slack file download failed with HTTP ${response.status}`, {
+                status: response.status,
+                url: input.url
+            });
+        }
+        const data = Buffer.from(await response.arrayBuffer());
+        await mkdir(dirname(input.outPath), { recursive: true });
+        await writeFile(input.outPath, data, { mode: 0o600 });
+        return { path: input.outPath, bytes: data.byteLength };
+    }
+}

package/dist/adapters/keychain/KeychainTokenStore.js

@@ -0,0 +1,152 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { UsageError } from "../../domain/errors.js";
+import { ProfileName, Scope } from "../../domain/ids.js";
+const execFileAsync = promisify(execFile);
+export class KeychainTokenStore {
+    filePath;
+    secrets;
+    constructor(filePath, secrets = new MacOSSecurityKeychainSecrets()) {
+        this.filePath = filePath;
+        this.secrets = secrets;
+    }
+    static fromEnv(env = process.env) {
+        const configDir = env.SLK_CONFIG_DIR ?? join(env.HOME ?? process.cwd(), ".config", "slk");
+        return new KeychainTokenStore(join(configDir, "profiles.keychain.json"));
+    }
+    async getProfile(name) {
+        const stored = (await this.readProfiles()).find((profile) => profile.name === name);
+        return stored === undefined ? null : this.hydrate(stored);
+    }
+    async setProfile(profile) {
+        const profiles = await this.readProfiles();
+        const previous = profiles.find((item) => item.name === profile.name);
+        const stored = await this.dehydrate(profile);
+        await this.deleteRemovedTokenAccounts(previous, stored);
+        await this.writeProfiles([stored, ...profiles.filter((item) => item.name !== profile.name)]);
+    }
+    async listProfiles() {
+        const profiles = await this.readProfiles();
+        return Promise.all(profiles.map((profile) => this.hydrate(profile)));
+    }
+    async deleteProfile(name) {
+        const profiles = await this.readProfiles();
+        const found = profiles.find((profile) => profile.name === name);
+        if (found === undefined) {
+            return false;
+        }
+        await Promise.all(Object.values(found.tokenAccounts).map((account) => account === undefined ? Promise.resolve() : this.secrets.delete(account)));
+        const next = profiles.filter((profile) => profile.name !== name);
+        if (next.length === 0) {
+            await rm(this.filePath, { force: true });
+        }
+        else {
+            await this.writeProfiles(next);
+        }
+        return true;
+    }
+    async dehydrate(profile) {
+        const tokenAccounts = {};
+        for (const field of tokenFields) {
+            const token = profile[field];
+            if (token !== undefined) {
+                const account = accountFor(profile.name, field);
+                await this.secrets.set(account, token);
+                tokenAccounts[field] = account;
+            }
+        }
+        return {
+            name: profile.name,
+            tokenType: profile.tokenType,
+            scopes: profile.scopes,
+            tokenAccounts,
+            ...(profile.teamId === undefined ? {} : { teamId: profile.teamId }),
+            ...(profile.enterpriseId === undefined ? {} : { enterpriseId: profile.enterpriseId }),
+            ...(profile.userId === undefined ? {} : { userId: profile.userId }),
+            ...(profile.botId === undefined ? {} : { botId: profile.botId })
+        };
+    }
+    async hydrate(profile) {
+        const tokens = Object.fromEntries(await Promise.all(tokenFields.map(async (field) => {
+            const account = profile.tokenAccounts[field];
+            return [field, account === undefined ? undefined : await this.secrets.get(account)];
+        })));
+        return {
+            name: ProfileName.make(profile.name),
+            tokenType: profile.tokenType,
+            scopes: profile.scopes.map(Scope.make),
+            ...(profile.teamId === undefined ? {} : { teamId: profile.teamId }),
+            ...(profile.enterpriseId === undefined ? {} : { enterpriseId: profile.enterpriseId }),
+            ...(profile.userId === undefined ? {} : { userId: profile.userId }),
+            ...(profile.botId === undefined ? {} : { botId: profile.botId }),
+            ...(tokens.botToken == null ? {} : { botToken: tokens.botToken }),
+            ...(tokens.userToken == null ? {} : { userToken: tokens.userToken }),
+            ...(tokens.adminToken == null ? {} : { adminToken: tokens.adminToken }),
+            ...(tokens.appToken == null ? {} : { appToken: tokens.appToken })
+        };
+    }
+    async deleteRemovedTokenAccounts(previous, next) {
+        if (previous === undefined) {
+            return;
+        }
+        const nextAccounts = new Set(Object.values(next.tokenAccounts));
+        await Promise.all(Object.values(previous.tokenAccounts).map((account) => {
+            if (account === undefined || nextAccounts.has(account)) {
+                return Promise.resolve();
+            }
+            return this.secrets.delete(account);
+        }));
+    }
+    async readProfiles() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            return parsed.profiles ?? [];
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async writeProfiles(profiles) {
+        await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        await writeFile(this.filePath, JSON.stringify({ profiles }, null, 2), { mode: 0o600 });
+    }
+}
+class MacOSSecurityKeychainSecrets {
+    service = "agent-slack";
+    async get(account) {
+        this.assertDarwin();
+        try {
+            const { stdout } = await execFileAsync("security", ["find-generic-password", "-s", this.service, "-a", account, "-w"]);
+            return stdout.trimEnd();
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(account, value) {
+        this.assertDarwin();
+        await execFileAsync("security", ["add-generic-password", "-s", this.service, "-a", account, "-w", value, "-U"]);
+    }
+    async delete(account) {
+        this.assertDarwin();
+        try {
+            await execFileAsync("security", ["delete-generic-password", "-s", this.service, "-a", account]);
+        }
+        catch {
+            // Deleting a missing keychain item is idempotent for TokenStore semantics.
+        }
+    }
+    assertDarwin() {
+        if (process.platform !== "darwin") {
+            throw new UsageError("Keychain token storage is only supported on macOS in this adapter");
+        }
+    }
+}
+const tokenFields = ["botToken", "userToken", "adminToken", "appToken"];
+const accountFor = (profileName, field) => `profile:${profileName}:${field}`;

package/dist/adapters/live.js

@@ -0,0 +1,13 @@
+import { BundledMethodCatalog } from "./catalog/BundledMethodCatalog.js";
+import { HttpFileDownloader } from "./http-file-downloader/HttpFileDownloader.js";
+import { KeychainTokenStore } from "./keychain/KeychainTokenStore.js";
+import { NodeLocalhostOAuthFlow } from "./localhost-oauth/NodeLocalhostOAuthFlow.js";
+import { FileTokenStore } from "./profile-file/FileTokenStore.js";
+import { SlackSdkWebApi } from "./slack-sdk/SlackSdkWebApi.js";
+export const createLiveServices = (env = process.env) => ({
+    tokenStore: env.SLK_TOKEN_STORE === "keychain" ? KeychainTokenStore.fromEnv(env) : FileTokenStore.fromEnv(env),
+    oauthFlow: NodeLocalhostOAuthFlow.fromEnv(env),
+    fileDownloader: new HttpFileDownloader(),
+    slackWebApi: new SlackSdkWebApi(env.SLK_SLACK_API_BASE_URL === undefined ? {} : { slackApiUrl: env.SLK_SLACK_API_BASE_URL }),
+    methodCatalog: new BundledMethodCatalog()
+});