@eliya-oss/agent-slack 0.1.12 → 0.1.14

package/.agents/cli-api.md

@@ -22,7 +22,8 @@ Non-goal for v0: agent-side summarization. The CLI returns clean context; agents
 ## Global Flags
 
 ```bash
-agent-slack [--profile NAME] [--team TEAM_ID] [--token user|bot|admin|app]
+agent-slack [--version] [--help]
+    [--profile NAME] [--team TEAM_ID] [--token user|bot|admin|app]
     [--json] [--format json|ndjson|table] [--pretty] [--full]
     [--fields FIELD[,FIELD...]]
     [--limit N] [--cursor CURSOR] [--all]
@@ -35,6 +36,7 @@ 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.
+- `--version` prints the CLI version as a bare line and exits `0`. `--help` prints the command catalog.
 
 ## Auth
 
@@ -116,6 +118,8 @@ agent-slack conversation context CHANNEL_ID [--since 24h] [--include users,threa
 
 `conversation context` returns normalized messages, hydrated users, thread refs, file refs, reactions, and permalinks in one deterministic payload for agents.
 
+`conversation list`, `conversation history`, and `conversation context` accept `--all` to auto-paginate every page, plus `--types`/`--limit` where relevant. These flags are advertised in `describe --json` and `<command> --help` so agents can discover them; without `--all` a large list returns only the first page with `paging.has_more: true`.
+
 ### Threads and messages
 
 ```bash
@@ -205,8 +209,9 @@ normalization and returns the raw Slack objects.
   `tz`, and team fields.
 - **file**: `id`, `name`, `mimetype`, `size`, and `permalink` when present.
   Drops thumbnails and private URLs.
-- **conversation**: `id`, `name`, `is_private`, `is_archived`, `topic`,
-  `purpose`, `num_members` when present.
+- **conversation**: `id`, `name`, `is_private`, `is_archived`, `is_member`,
+  `topic`, `purpose`, `num_members` when present. `is_member` is kept as an
+  explicit boolean so an agent can tell membership from a list.
 - `conversation context` dedupes thread roots already present in `messages` and
   hydrates every unique author, including those who appear only in replies.
 
@@ -240,6 +245,17 @@ NDJSON streaming record:
 {"ok":true,"type":"slack.message","team_id":"T123","channel_id":"C123","ts":"1710000000.000100","data":{}}
 ```
 
+NDJSON enrichment records: when `--include` is combined with `--format ndjson`,
+the hydration maps that `--json` returns under `data.users`/`data.threads`/`data.permalinks`
+are streamed as typed records after the message lines, so the streaming mode is
+not lossy. Message lines stay bare; enrichment lines carry a `type`:
+
+```json
+{"type":"slack.user","data":{"id":"U123","name":"ada","real_name":"Ada"}}
+{"type":"slack.thread","data":{"ts":"1710000000.000100","replies":[]}}
+{"type":"slack.permalink","data":{"ts":"1710000000.000100","permalink":"https://slack.com/..."}}
+```
+
 Structured error on stderr:
 
 ```json
@@ -287,6 +303,9 @@ Schema output includes:
 
 - command description and examples
 - positional args and flags
+- `dataKey`: the key under the response envelope's `data` that holds the
+  command's primary payload (for example `conversation list` reports
+  `dataKey: "channels"`, so the array is at `data.channels`, not `data`)
 - payload schema when known
 - required Slack method/scopes
 - output schema

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @eliya-oss/agent-slack
 
+## 0.1.14
+
+### Patch Changes
+
+- d856e3b: Two agent-facing discoverability improvements.
+
+  - `describe --json` and `<command> --help --json` now report a `dataKey` for each command: the key under the response envelope's `data` that holds the primary payload (for example `conversation list` reports `dataKey: "channels"`, so results are at `data.channels`). Agents no longer have to probe the response shape.
+  - Conversation results now keep `is_member` as an explicit boolean, so an agent can tell which channels the active token has joined directly from `conversation list`.
+
+## 0.1.13
+
+### Patch Changes
+
+- 48d5879: Three CLI fixes for agents.
+
+  - `agent-slack --version` now prints the version and exits 0 instead of raising a usage error.
+  - `conversation list`, `conversation history`, and `conversation context` now advertise their pagination flags (`--all`, `--types`, `--limit`) in `describe --json` and `--help`, so agents can discover `--all` instead of only getting the first page.
+  - `--include users,threads,permalinks` now works with `--format ndjson`: the hydrated users, threads, and permalinks are streamed as typed records (`slack.user`, `slack.thread`, `slack.permalink`) after the message lines. Previously they were only present with `--json` and silently dropped in ndjson.
+
 ## 0.1.12
 
 ### Patch Changes

package/dist/main.js

@@ -25105,6 +25105,7 @@ const booleanFlags = /* @__PURE__ */ new Set([
 	"all",
 	"allow-write",
 	"help",
+	"version",
 	"json",
 	"no-color",
 	"raw",
@@ -25521,9 +25522,143 @@ const pad = (value, width) => value + " ".repeat(Math.max(0, width - value.lengt
 const widthFor = (column) => column === "text" ? 72 : 24;
 const truncate = (value, width) => value.length > width ? `${value.slice(0, Math.max(0, width - 3))}...` : value;
 //#endregion
+//#region src/output/normalize.ts
+const isRec = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const asArray = (value) => Array.isArray(value) ? value : [];
+const str = (record, key) => typeof record[key] === "string" && record[key].length > 0 ? record[key] : void 0;
+const slimFile = (input) => {
+	if (!isRec(input)) return input;
+	const out = {
+		id: input.id,
+		name: input.name
+	};
+	if (typeof input.mimetype === "string") out.mimetype = input.mimetype;
+	if (typeof input.size === "number") out.size = input.size;
+	const permalink = str(input, "permalink");
+	if (permalink) out.permalink = permalink;
+	return out;
+};
+const slimMessage = (input) => {
+	if (!isRec(input)) return input;
+	const m = input;
+	const out = {};
+	if (typeof m.user === "string") out.user = m.user;
+	else if (typeof m.bot_id === "string") out.bot_id = m.bot_id;
+	const username = str(m, "username");
+	if (username) out.username = username;
+	const subtype = str(m, "subtype");
+	if (subtype) out.subtype = subtype;
+	if (typeof m.ts === "string") out.ts = m.ts;
+	out.text = typeof m.text === "string" ? m.text : "";
+	if (typeof m.thread_ts === "string" && m.thread_ts !== m.ts) out.thread_ts = m.thread_ts;
+	if (typeof m.reply_count === "number") out.reply_count = m.reply_count;
+	const reactions = asArray(m.reactions).filter(isRec).map((r) => ({
+		name: r.name,
+		count: r.count
+	}));
+	if (reactions.length > 0) out.reactions = reactions;
+	const files = asArray(m.files).map(slimFile);
+	if (files.length > 0) out.files = files;
+	if (m.edited !== void 0 && m.edited !== null) out.edited = true;
+	return out;
+};
+const slimUser = (input) => {
+	if (!isRec(input)) return input;
+	const u = input;
+	const profile = isRec(u.profile) ? u.profile : {};
+	const out = {
+		id: u.id,
+		name: u.name
+	};
+	const real = str(profile, "display_name") ?? str(u, "real_name") ?? str(profile, "real_name");
+	if (real) out.real_name = real;
+	if (u.is_bot === true) out.is_bot = true;
+	if (u.deleted === true) out.deleted = true;
+	const title = str(profile, "title");
+	if (title) out.title = title;
+	return out;
+};
+const slimConversation = (input) => {
+	if (!isRec(input)) return input;
+	const c = input;
+	const out = {
+		id: c.id,
+		name: c.name
+	};
+	if (c.is_private === true) out.is_private = true;
+	if (c.is_archived === true) out.is_archived = true;
+	if (c.is_im === true) out.is_im = true;
+	if (c.is_mpim === true) out.is_mpim = true;
+	if (typeof c.is_member === "boolean") out.is_member = c.is_member;
+	const topic = isRec(c.topic) ? str(c.topic, "value") : void 0;
+	if (topic) out.topic = topic;
+	const purpose = isRec(c.purpose) ? str(c.purpose, "value") : void 0;
+	if (purpose) out.purpose = purpose;
+	if (typeof c.num_members === "number") out.num_members = c.num_members;
+	return out;
+};
+const slimTeam = (input) => {
+	if (!isRec(input)) return input;
+	const t = input;
+	const out = {
+		id: t.id,
+		name: t.name
+	};
+	const domain = str(t, "domain");
+	if (domain) out.domain = domain;
+	const emailDomain = str(t, "email_domain");
+	if (emailDomain) out.email_domain = emailDomain;
+	const enterpriseId = str(t, "enterprise_id");
+	if (enterpriseId) out.enterprise_id = enterpriseId;
+	const enterpriseName = str(t, "enterprise_name");
+	if (enterpriseName) out.enterprise_name = enterpriseName;
+	return out;
+};
+const stripResponseEnvelope = (response) => {
+	const { ok, response_metadata, ...rest } = response;
+	return rest;
+};
+const dataKeyFor = (method) => {
+	switch (method) {
+		case "conversations.history":
+		case "conversations.replies": return "messages";
+		case "conversations.info": return "channel";
+		case "conversations.list": return "channels";
+		case "conversations.members": return "members";
+		case "users.info":
+		case "users.lookupByEmail": return "user";
+		case "users.list": return "users";
+		case "files.info": return "file";
+		case "files.list": return "files";
+		case "team.info": return "team";
+		default: return;
+	}
+};
+const normalizeResponse = (method, response) => {
+	if (!isRec(response)) return response;
+	const r = response;
+	switch (method) {
+		case "conversations.history":
+		case "conversations.replies": return { messages: asArray(r.messages).map(slimMessage) };
+		case "conversations.info": return { channel: slimConversation(r.channel) };
+		case "conversations.list": return { channels: asArray(r.channels).map(slimConversation) };
+		case "users.info":
+		case "users.lookupByEmail": return { user: slimUser(r.user) };
+		case "users.list": return { users: asArray(r.members).map(slimUser) };
+		case "files.info": return { file: slimFile(r.file) };
+		case "files.list": return { files: asArray(r.files).map(slimFile) };
+		case "team.info": return { team: slimTeam(r.team) };
+		case "reactions.get": return isRec(r.message) ? {
+			...stripResponseEnvelope(r),
+			message: slimMessage(r.message)
+		} : stripResponseEnvelope(r);
+		default: return stripResponseEnvelope(r);
+	}
+};
+//#endregion
 //#region src/cli/metadata.ts
 createRequire(import.meta.url);
-const packageJson = { version: "0.1.12" };
+const packageJson = { version: "0.1.14" };
 const PRIMARY_COMMAND_NAME = "agent-slack";
 const SHORT_COMMAND_NAME = "aslk";
 const COMMAND_NAMES = [PRIMARY_COMMAND_NAME, SHORT_COMMAND_NAME];
@@ -25764,6 +25899,12 @@ const commandMetadata = [
 	{
 		path: ["conversation", "list"],
 		summary: "List conversations visible to the active profile.",
+		flags: [
+			"--types",
+			"--limit",
+			"--all",
+			"--json"
+		],
 		methods: ["conversations.list"],
 		scopes: [
 			"channels:read",
@@ -25773,12 +25914,21 @@ const commandMetadata = [
 		],
 		safety: "read",
 		output: "conversation list",
-		examples: ["agent-slack conversation list --types public_channel,private_channel --json"]
+		examples: ["agent-slack conversation list --types public_channel,private_channel --json", "agent-slack conversation list --all --json"]
 	},
 	{
 		path: ["conversation", "history"],
 		summary: "Read conversation history.",
 		args: ["CHANNEL_ID"],
+		flags: [
+			"--oldest",
+			"--latest",
+			"--since",
+			"--inclusive",
+			"--limit",
+			"--all",
+			"--json"
+		],
 		methods: ["conversations.history"],
 		scopes: [
 			"channels:history",
@@ -25794,6 +25944,15 @@ const commandMetadata = [
 		path: ["conversation", "context"],
 		summary: "Build channel context for agents.",
 		args: ["CHANNEL_ID"],
+		flags: [
+			"--since",
+			"--include",
+			"--limit",
+			"--all",
+			"--full",
+			"--format",
+			"--json"
+		],
 		methods: [
 			"conversations.history",
 			"conversations.replies",
@@ -25890,7 +26049,14 @@ const commandMetadata = [
 		output: "download status",
 		examples: ["agent-slack file download F123 --out ./artifact.pdf --json"]
 	}
-];
+].map((command) => {
+	const method = command.methods?.[0];
+	const dataKey = method === void 0 ? void 0 : dataKeyFor(method);
+	return dataKey === void 0 ? command : {
+		...command,
+		dataKey
+	};
+});
 const describeAllCommands = () => ({
 	name: PRIMARY_COMMAND_NAME,
 	aliases: [SHORT_COMMAND_NAME],
@@ -25911,6 +26077,7 @@ const renderHumanHelp = (path) => {
 		command.summary,
 		"",
 		command.args === void 0 ? "" : `Usage: ${PRIMARY_COMMAND_NAME} ${command.path.join(" ")} ${command.args.join(" ")}`,
+		command.flags === void 0 ? "" : `Flags: ${command.flags.join(" ")}`,
 		command.scopes === void 0 ? "" : `Scopes: ${command.scopes.join(", ")}`,
 		"",
 		"Examples:",
@@ -25977,123 +26144,6 @@ const renderCompletion = (shell) => {
 };
 const summaryFor = (path) => commandMetadata.find((command) => command.path.join(" ") === path)?.summary.replace(/'/g, "") ?? "";
 //#endregion
-//#region src/output/normalize.ts
-const isRec = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const asArray = (value) => Array.isArray(value) ? value : [];
-const str = (record, key) => typeof record[key] === "string" && record[key].length > 0 ? record[key] : void 0;
-const slimFile = (input) => {
-	if (!isRec(input)) return input;
-	const out = {
-		id: input.id,
-		name: input.name
-	};
-	if (typeof input.mimetype === "string") out.mimetype = input.mimetype;
-	if (typeof input.size === "number") out.size = input.size;
-	const permalink = str(input, "permalink");
-	if (permalink) out.permalink = permalink;
-	return out;
-};
-const slimMessage = (input) => {
-	if (!isRec(input)) return input;
-	const m = input;
-	const out = {};
-	if (typeof m.user === "string") out.user = m.user;
-	else if (typeof m.bot_id === "string") out.bot_id = m.bot_id;
-	const username = str(m, "username");
-	if (username) out.username = username;
-	const subtype = str(m, "subtype");
-	if (subtype) out.subtype = subtype;
-	if (typeof m.ts === "string") out.ts = m.ts;
-	out.text = typeof m.text === "string" ? m.text : "";
-	if (typeof m.thread_ts === "string" && m.thread_ts !== m.ts) out.thread_ts = m.thread_ts;
-	if (typeof m.reply_count === "number") out.reply_count = m.reply_count;
-	const reactions = asArray(m.reactions).filter(isRec).map((r) => ({
-		name: r.name,
-		count: r.count
-	}));
-	if (reactions.length > 0) out.reactions = reactions;
-	const files = asArray(m.files).map(slimFile);
-	if (files.length > 0) out.files = files;
-	if (m.edited !== void 0 && m.edited !== null) out.edited = true;
-	return out;
-};
-const slimUser = (input) => {
-	if (!isRec(input)) return input;
-	const u = input;
-	const profile = isRec(u.profile) ? u.profile : {};
-	const out = {
-		id: u.id,
-		name: u.name
-	};
-	const real = str(profile, "display_name") ?? str(u, "real_name") ?? str(profile, "real_name");
-	if (real) out.real_name = real;
-	if (u.is_bot === true) out.is_bot = true;
-	if (u.deleted === true) out.deleted = true;
-	const title = str(profile, "title");
-	if (title) out.title = title;
-	return out;
-};
-const slimConversation = (input) => {
-	if (!isRec(input)) return input;
-	const c = input;
-	const out = {
-		id: c.id,
-		name: c.name
-	};
-	if (c.is_private === true) out.is_private = true;
-	if (c.is_archived === true) out.is_archived = true;
-	if (c.is_im === true) out.is_im = true;
-	if (c.is_mpim === true) out.is_mpim = true;
-	const topic = isRec(c.topic) ? str(c.topic, "value") : void 0;
-	if (topic) out.topic = topic;
-	const purpose = isRec(c.purpose) ? str(c.purpose, "value") : void 0;
-	if (purpose) out.purpose = purpose;
-	if (typeof c.num_members === "number") out.num_members = c.num_members;
-	return out;
-};
-const slimTeam = (input) => {
-	if (!isRec(input)) return input;
-	const t = input;
-	const out = {
-		id: t.id,
-		name: t.name
-	};
-	const domain = str(t, "domain");
-	if (domain) out.domain = domain;
-	const emailDomain = str(t, "email_domain");
-	if (emailDomain) out.email_domain = emailDomain;
-	const enterpriseId = str(t, "enterprise_id");
-	if (enterpriseId) out.enterprise_id = enterpriseId;
-	const enterpriseName = str(t, "enterprise_name");
-	if (enterpriseName) out.enterprise_name = enterpriseName;
-	return out;
-};
-const stripResponseEnvelope = (response) => {
-	const { ok, response_metadata, ...rest } = response;
-	return rest;
-};
-const normalizeResponse = (method, response) => {
-	if (!isRec(response)) return response;
-	const r = response;
-	switch (method) {
-		case "conversations.history":
-		case "conversations.replies": return { messages: asArray(r.messages).map(slimMessage) };
-		case "conversations.info": return { channel: slimConversation(r.channel) };
-		case "conversations.list": return { channels: asArray(r.channels).map(slimConversation) };
-		case "users.info":
-		case "users.lookupByEmail": return { user: slimUser(r.user) };
-		case "users.list": return { users: asArray(r.members).map(slimUser) };
-		case "files.info": return { file: slimFile(r.file) };
-		case "files.list": return { files: asArray(r.files).map(slimFile) };
-		case "team.info": return { team: slimTeam(r.team) };
-		case "reactions.get": return isRec(r.message) ? {
-			...stripResponseEnvelope(r),
-			message: slimMessage(r.message)
-		} : stripResponseEnvelope(r);
-		default: return stripResponseEnvelope(r);
-	}
-};
-//#endregion
 //#region src/output/projection.ts
 const projectFields = (value, fields) => {
 	if (fields === void 0 || fields.trim() === "") return value;
@@ -26249,6 +26299,12 @@ const extractItems = (services, method, response) => {
 const dispatch = async (parsed, services) => {
 	const pos = parsed.positionals;
 	const [first, second, third] = pos;
+	if (flagBoolean(parsed, "version")) return {
+		method: "version",
+		profile: null,
+		stdoutValue: null,
+		rawStdout: `${CLI_VERSION}\n`
+	};
 	if (flagBoolean(parsed, "help") && !flagBoolean(parsed, "json")) return {
 		method: "help",
 		profile: null,
@@ -26656,6 +26712,26 @@ const conversationContext = async (parsed, services) => {
 		response: history.response,
 		stdoutValue: context,
 		items: messages.map(shape),
+		enrichmentRecords: [
+			...recordsFromMap(context.users, (_, data) => ({
+				type: "slack.user",
+				data
+			})),
+			...recordsFromMap(context.threads, (ts, replies) => ({
+				type: "slack.thread",
+				data: {
+					ts,
+					replies
+				}
+			})),
+			...recordsFromMap(context.permalinks, (ts, permalink) => ({
+				type: "slack.permalink",
+				data: {
+					ts,
+					permalink
+				}
+			}))
+		],
 		...warnings.length > 0 ? { warnings } : {}
 	};
 };
@@ -26736,6 +26812,16 @@ const threadGet = async (parsed, services) => {
 		response: result.response,
 		stdoutValue: data,
 		items: rawMessages.map(shape),
+		enrichmentRecords: [...recordsFromMap(data.users, (_, user) => ({
+			type: "slack.user",
+			data: user
+		})), ...recordsFromMap(data.permalinks, (ts, permalink) => ({
+			type: "slack.permalink",
+			data: {
+				ts,
+				permalink
+			}
+		}))],
 		...warnings.length > 0 ? { warnings } : {}
 	};
 };
@@ -26844,7 +26930,7 @@ const methodCall = async (parsed, services, input, options = {}) => {
 };
 const renderDispatchResult = (parsed, result, options = {}) => {
 	if (result.rawStdout !== void 0) return result.rawStdout;
-	if (flagString(parsed, "format") === "ndjson") return toNdjson(result.items ?? []);
+	if (flagString(parsed, "format") === "ndjson") return toNdjson([...result.items ?? [], ...result.enrichmentRecords ?? []]);
 	const data = projectFields(result.stdoutValue, flagString(parsed, "fields"));
 	const envelope = successEnvelope({
 		method: result.method,
@@ -26901,6 +26987,7 @@ const stringField = (record, name) => typeof record[name] === "string" && record
 const extractArray = (value) => Array.isArray(value) ? value : [];
 const extractLooseRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 const uniqueStrings = (values) => [...new Set(values.filter((value) => value !== void 0))];
+const recordsFromMap = (value, toRecord) => Object.entries(extractLooseRecord(value)).map(([key, entry]) => toRecord(key, entry));
 //#endregion
 //#region src/application/execute.ts
 const executeCli = async (argv, services, options = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eliya-oss/agent-slack",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Slack context CLI for AI agents.",
   "type": "module",
   "bin": {