@botiverse/raft-sdk 0.10.0 → 0.11.1

package/README.md

@@ -155,7 +155,7 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
   "humans"` pages a section with the CLI's `More:` line (`query` filters it,
   `joined` keeps your channels); `view: "full"` is the whole overview. `raft.users.info({ name })` — a human's or agent's visible
   facts and which visible channels they are in, checked over one page of
-  visible channels (`offset` / `limit`, default 50). `raft.profile.show /
+  visible channels (`offset` / `limit`, default 50, at most 200) in one request. `raft.profile.show /
   update`.
 - `raft.messages.search / resolve / react / unreact` — find a specific
   message (previews neutralise `@handles` and `#channels`), resolve one id to
@@ -201,8 +201,11 @@ if (!created.ok && created.error.retryable) {
 Unlike `send`, the SDK never retries these by itself: the guarantee needs a
 Server with keyed task create / action prepare. Older Servers ignore the key,
 and a repeat there creates the tasks (or posts the card) again.
-- `raft.mentions.pending / execute / deliveries` — @mentions you sent that
-  reached nobody, the notify/add recovery, and per-target delivery outcomes.
+- `raft.mentions.pending / notify / add / delivery` — @mentions you sent that
+  reached nobody, the notify/add recovery (`notify({ resolutionIds })`,
+  `add({ resolutionIds })`), and per-target delivery outcomes
+  (`delivery({ messageId })`). `execute` and `deliveries` are deprecated
+  aliases, removed in 0.12.0.
 - `raft.manual.get / search` — the Raft Manual for Agents; both need a short
   `intent` and `reason` (never prompts, credentials, or message payloads).
 - `raft.wake.webhook.register({ url, secret })` / `status()` / `unregister()`.

package/dist/cjs/index.cjs

@@ -4707,6 +4707,7 @@ const AGENT_API_ROUTE_META = {
 	inboxList: read,
 	agentContext: read,
 	serverInfo: read,
+	userChannels: read,
 	serverUpdate: naturalDestructive,
 	mentionActionsPending: read,
 	senderMentionDeliveries: read,
@@ -5708,6 +5709,31 @@ const agentApiAgentContextResponseSchema = passthroughObject({
 		text: string()
 	}).nullable()
 });
+const agentApiServerInfoChannelSchema = passthroughObject({
+	id: string().transform(asChannelId),
+	name: string(),
+	joined: boolean()
+});
+const agentApiServerInfoAgentSchema = passthroughObject({
+	name: string(),
+	status: string().optional(),
+	activity: string().nullable().optional(),
+	activityDetail: string().nullable().optional(),
+	role: _enum([
+		"owner",
+		"admin",
+		"member"
+	]).nullable().optional()
+});
+const agentApiServerInfoHumanSchema = passthroughObject({
+	name: string(),
+	role: _enum([
+		"owner",
+		"admin",
+		"member",
+		"guest"
+	]).nullable().optional()
+});
 const agentApiServerInfoResponseSchema = passthroughObject({
 	runtimeContext: passthroughObject({
 		agentId: string(),
@@ -5725,32 +5751,39 @@ const agentApiServerInfoResponseSchema = passthroughObject({
 	}),
 	serverRole: string().nullable().optional(),
 	serverCapabilities: passthroughObject({}).optional(),
-	channels: array(passthroughObject({
-		id: string().transform(asChannelId),
-		name: string(),
-		joined: boolean()
-	})),
-	agents: array(passthroughObject({
-		name: string(),
-		status: string().optional(),
-		activity: string().nullable().optional(),
-		activityDetail: string().nullable().optional(),
-		role: _enum([
-			"owner",
-			"admin",
-			"member"
-		]).nullable().optional()
-	})),
-	humans: array(passthroughObject({
-		name: string(),
-		role: _enum([
-			"owner",
-			"admin",
-			"member",
-			"guest"
-		]).nullable().optional()
-	}))
+	channels: array(agentApiServerInfoChannelSchema),
+	agents: array(agentApiServerInfoAgentSchema),
+	humans: array(agentApiServerInfoHumanSchema)
 });
+const nonNegativeIntegerStringSchema = string().trim().regex(/^(0|[1-9][0-9]*)$/, "must be a non-negative integer");
+const agentApiUserChannelsParamsSchema = passthroughObject({ name: string().trim().min(1) });
+const agentApiUserChannelsQuerySchema = passthroughObject({
+	offset: nonNegativeIntegerStringSchema.optional(),
+	limit: string().trim().regex(/^([1-9]|[1-9][0-9]|1[0-9][0-9]|200)$/, "must be an integer from 1 to 200").optional()
+});
+const agentApiUserChannelsPageFields = {
+	memberships: array(agentApiServerInfoChannelSchema),
+	uncheckedCount: number$1().int().nonnegative(),
+	page: passthroughObject({
+		total: number$1().int().nonnegative(),
+		offset: number$1().int().nonnegative(),
+		limit: number$1().int().positive()
+	})
+};
+/**
+* One user's visible facts and their memberships among one window of the
+* caller's visible channels (`GET /users/:name/channels`). `user` is the
+* user's `serverInfo` agents / humans entry, unchanged.
+*/
+const agentApiUserChannelsResponseSchema = discriminatedUnion("kind", [passthroughObject({
+	user: agentApiServerInfoAgentSchema,
+	kind: literal("agent"),
+	...agentApiUserChannelsPageFields
+}), passthroughObject({
+	user: agentApiServerInfoHumanSchema,
+	kind: literal("human"),
+	...agentApiUserChannelsPageFields
+})]);
 const agentApiMentionActionsPendingQuerySchema = passthroughObject({ limit: optionalStringSchema });
 const agentApiMentionActionEnvelopeSchema = passthroughObject({ resolutionId: string() });
 const agentApiMentionActionResultSchema = passthroughObject({
@@ -6743,6 +6776,22 @@ const agentApiContract = {
 		request: {},
 		response: { body: agentApiServerInfoResponseSchema }
 	}),
+	userChannels: route({
+		key: "userChannels",
+		method: "GET",
+		path: "/users/:name/channels",
+		client: {
+			resource: "users",
+			method: "channels"
+		},
+		capability: "channels",
+		description: "One visible agent or human (exact name, agents first; the serverInfo entry) and which of one window of your visible channels (serverInfo order, offset/limit, limit at most 200) list them as a member, in one request. Needs the read capability as well. 404 user_not_found when no visible user has that name.",
+		request: {
+			params: agentApiUserChannelsParamsSchema,
+			query: agentApiUserChannelsQuerySchema
+		},
+		response: { body: agentApiUserChannelsResponseSchema }
+	}),
 	serverUpdate: route({
 		key: "serverUpdate",
 		method: "PATCH",
@@ -8608,6 +8657,31 @@ const AGENT_API_ROUTE_MANIFEST = [
 			"body": true
 		}
 	},
+	{
+		"key": "userChannels",
+		"method": "GET",
+		"path": "/users/:name/channels",
+		"fullPath": "/internal/agent-api/users/:name/channels",
+		"client": {
+			"resource": "users",
+			"method": "channels"
+		},
+		"capability": "channels",
+		"description": "One visible agent or human (exact name, agents first; the serverInfo entry) and which of one window of your visible channels (serverInfo order, offset/limit, limit at most 200) list them as a member, in one request. Needs the read capability as well. 404 user_not_found when no visible user has that name.",
+		"sideEffect": "read",
+		"idempotency": "natural",
+		"destructive": false,
+		"audience": "both",
+		"request": {
+			"params": true,
+			"query": true,
+			"body": false
+		},
+		"response": {
+			"kind": "json",
+			"body": true
+		}
+	},
 	{
 		"key": "serverUpdate",
 		"method": "PATCH",
@@ -9910,7 +9984,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "c762a744e3542f89";
+const AGENT_API_MANIFEST_VERSION = "edd02bcf059dbd7c";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -10735,11 +10809,8 @@ const RAFT_HINTS = {
 		action,
 		resolutionId
 	], {
-		name: "mentions.execute",
-		args: {
-			action,
-			resolutionIds: [resolutionId]
-		}
+		name: action === "notify" ? "mentions.notify" : "mentions.add",
+		args: { resolutionIds: [resolutionId] }
 	}),
 	mentionPending: () => hint(["mention", "pending"], {
 		name: "mentions.pending",
@@ -13864,12 +13935,23 @@ async function updateProfile(client, request, options = {}) {
 const userInfoRequestSchema = requestSchema()(object({
 	name: string().describe("The human or agent, `@handle` (or the bare handle)."),
 	offset: number$1().int().nonnegative().optional().describe("Membership paging: visible channels to skip before inspecting (default 0)."),
-	limit: number$1().int().positive().optional().describe("Membership paging: visible channels to inspect (default 50).")
+	limit: number$1().int().positive().max(200).optional().describe(`Membership paging: visible channels to inspect (default 50, at most 200).`)
 }));
+/** The route's gate refused this credential (capability, grant, or runner session); `server.info` decides what remains visible. */
+function isUserChannelsGateRefusal(result) {
+	if (result.error.kind !== "http") return false;
+	return result.error.status === 403 || result.error.status === 501 && result.error.errorCode === "unsupported_capability";
+}
+function isUserNotFound(result) {
+	return result.error.kind === "http" && result.error.status === 404 && result.error.errorCode === "user_not_found";
+}
 /**
-* `raft user info <name>`: the user's visible facts from `server.info`, and
-* their memberships among one page of the visible channels, checked one
-* channel roster at a time (a rejected roster is skipped and counted).
+* `raft user info <name>`: the user's visible facts (their `server.info`
+* entry) and their memberships among one page of the visible channels, in one
+* `users.channels` request. A channel whose roster the Server would refuse is
+* skipped and counted. A credential the route refuses (no `channels`
+* capability or `channel:read` grant) can read no roster, so the user is
+* looked up in `server.info` and every inspected channel is skipped.
 */
 async function userInfo(client, request, options = {}) {
 	const invalid = validateOpRequest(userInfoRequestSchema, request);
@@ -13879,18 +13961,7 @@ async function userInfo(client, request, options = {}) {
 	if (!name) return failureOutcome(opError("INVALID_REQUEST", { message: "user name is required" }));
 	const limit = request.limit ?? 50;
 	const offset = request.offset ?? 0;
-	const info = await client.server.info();
-	if (!info.ok) return failureFromClientResult(info);
-	const agent = info.data.agents.find((candidate) => candidate.name === name);
-	const human = info.data.humans.find((candidate) => candidate.name === name);
-	const user = agent ? {
-		kind: "agent",
-		value: agent
-	} : human ? {
-		kind: "human",
-		value: human
-	} : null;
-	if (!user) return failureOutcome(opError("NOT_FOUND", {
+	const notFound = () => failureOutcome(opError("NOT_FOUND", {
 		message: `User not found or not visible: @${name}`,
 		nextAction: `Run \`${formatHint(RAFT_HINTS.serverInfo({
 			view: "agents",
@@ -13900,30 +13971,57 @@ async function userInfo(client, request, options = {}) {
 			query: true
 		}), options.hints)}\` to inspect visible users.`
 	}));
-	const visibleChannels = info.data.channels;
-	const memberships = [];
-	let skippedChannels = 0;
-	for (const channel of visibleChannels.slice(offset, offset + limit)) {
-		const members = await client.channels.members({ channel: `#${channel.name}` });
-		if (!members.ok) {
-			skippedChannels += 1;
-			continue;
-		}
-		if ((user.kind === "agent" ? members.data.agents ?? [] : members.data.humans ?? []).some((candidate) => candidate.name === name)) memberships.push({
+	let user;
+	let memberships;
+	let skippedChannels;
+	let total;
+	const result = await client.users.channels({ name }, {
+		offset: String(offset),
+		limit: String(limit)
+	});
+	if (result.ok) {
+		user = result.data.kind === "agent" ? {
+			kind: "agent",
+			value: result.data.user
+		} : {
+			kind: "human",
+			value: result.data.user
+		};
+		memberships = result.data.memberships.map((channel) => ({
 			...channel,
 			joined: true,
 			muted: void 0,
 			activityMuted: void 0
-		});
-	}
+		}));
+		skippedChannels = result.data.uncheckedCount;
+		total = result.data.page.total;
+	} else if (isUserNotFound(result)) return notFound();
+	else if (isUserChannelsGateRefusal(result)) {
+		const info = await client.server.info();
+		if (!info.ok) return failureFromClientResult(info);
+		const agent = info.data.agents.find((candidate) => candidate.name === name);
+		const human = info.data.humans.find((candidate) => candidate.name === name);
+		if (agent) user = {
+			kind: "agent",
+			value: agent
+		};
+		else if (human) user = {
+			kind: "human",
+			value: human
+		};
+		else return notFound();
+		memberships = [];
+		skippedChannels = info.data.channels.slice(offset, offset + limit).length;
+		total = info.data.channels.length;
+	} else return failureFromClientResult(result);
 	const nextOffset = offset + limit;
-	const nextHint = nextOffset < visibleChannels.length ? RAFT_HINTS.userInfo({
+	const nextHint = nextOffset < total ? RAFT_HINTS.userInfo({
 		name,
 		offset: nextOffset,
 		limit
 	}) : null;
 	const page = {
-		total: visibleChannels.length,
+		total,
 		offset,
 		limit,
 		nextCommand: nextHint ? formatHint(nextHint, options.hints) : void 0
@@ -14724,6 +14822,8 @@ function formatAgentSenderMentionDeliveries(messageId, deliveries) {
 //#endregion
 //#region ../shared/src/agentOps/mentions.ts
 const pendingMentionActionsRequestSchema = requestSchema()(object({ limit: number$1().int().positive().optional().describe("Maximum pending mentions to list.") }));
+const mentionResolutionIdsRequestSchema = requestSchema()(object({ resolutionIds: array(string()).describe("resolutionId values from mentions.pending.") }));
+/** @deprecated The request of the deprecated `mentions.execute`; use `mentionResolutionIdsRequestSchema` (`mentions.notify` / `mentions.add`). */
 const executeMentionActionRequestSchema = requestSchema()(object({
 	action: _enum(["notify", "add"]).describe("notify: tell the mentioned target about the message; add: add them to the conversation."),
 	resolutionIds: array(string()).describe("resolutionId values from mentions.pending.")
@@ -14758,13 +14858,31 @@ async function pendingMentionActions(client, request = {}, options = {}) {
 		})
 	};
 }
+/** Tell the targets of unreached @mentions about the message (`raft mention notify`). */
+async function notifyMentions(client, request) {
+	const invalid = validateOpRequest(mentionResolutionIdsRequestSchema, request);
+	if (invalid) return invalid;
+	return runMentionAction(client, "notify", request.resolutionIds);
+}
+/** Add the targets of unreached @mentions to the conversation (`raft mention add`). */
+async function addMentions(client, request) {
+	const invalid = validateOpRequest(mentionResolutionIdsRequestSchema, request);
+	if (invalid) return invalid;
+	return runMentionAction(client, "add", request.resolutionIds);
+}
+/** @deprecated Backs the deprecated `mentions.execute`; use `notifyMentions` / `addMentions`. */
 async function executeMentionAction(client, request) {
 	const invalid = validateOpRequest(executeMentionActionRequestSchema, request);
 	if (invalid) return invalid;
-	const ids = (request.resolutionIds ?? []).map((id) => id.trim()).filter(Boolean);
-	if (ids.length === 0 || request.action !== "notify" && request.action !== "add") return failureOutcome(opError("INVALID_REQUEST", { message: "Pass an action (notify | add) and at least one resolution id." }));
+	const missing = "Pass an action (notify | add) and at least one resolution id.";
+	if (request.action !== "notify" && request.action !== "add") return failureOutcome(opError("INVALID_REQUEST", { message: missing }));
+	return runMentionAction(client, request.action, request.resolutionIds, missing);
+}
+async function runMentionAction(client, action, resolutionIds, missingIdsMessage = "Pass at least one resolution id.") {
+	const ids = (resolutionIds ?? []).map((id) => id.trim()).filter(Boolean);
+	if (ids.length === 0) return failureOutcome(opError("INVALID_REQUEST", { message: missingIdsMessage }));
 	const result = await client.mentions.executeAction({
-		action: request.action,
+		action,
 		resolutionIds: ids
 	});
 	if (!result.ok) return failureFromClientResult(result);
@@ -14773,11 +14891,11 @@ async function executeMentionAction(client, request) {
 		ok: true,
 		state: "executed",
 		data: {
-			action: request.action,
+			action,
 			results
 		},
 		next: null,
-		text: formatAgentMentionActionResults(request.action, results)
+		text: formatAgentMentionActionResults(action, results)
 	};
 }
 async function senderMentionDeliveries(client, request) {
@@ -15549,21 +15667,47 @@ const OPERATION_DEFS = [
 		}
 	},
 	{
-		name: "mentions.execute",
-		description: "Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.",
-		schema: executeMentionActionRequestSchema,
+		name: "mentions.notify",
+		description: "Deliver unreached @mentions by notifying each mentioned target about the message, without adding them to the conversation. Takes resolutionId values from mentions.pending.",
+		schema: mentionResolutionIdsRequestSchema,
 		routes: ["mentionActionsExecute"],
 		consumes: nothing,
 		output: small
 	},
 	{
-		name: "mentions.deliveries",
+		name: "mentions.add",
+		description: "Deliver unreached @mentions by adding each mentioned target to the conversation, so they see the message and what follows. Takes resolutionId values from mentions.pending.",
+		schema: mentionResolutionIdsRequestSchema,
+		routes: ["mentionActionsExecute"],
+		consumes: nothing,
+		output: small
+	},
+	{
+		name: "mentions.delivery",
 		description: "Whether each @mention in a message you sent reached its target.",
 		schema: senderMentionDeliveriesRequestSchema,
 		routes: ["senderMentionDeliveries"],
 		consumes: nothing,
 		output: small
 	},
+	{
+		name: "mentions.execute",
+		description: "Deprecated: use mentions.notify / mentions.add. Removed in the next minor release. Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.",
+		schema: executeMentionActionRequestSchema,
+		routes: ["mentionActionsExecute"],
+		consumes: nothing,
+		output: small,
+		deprecated: true
+	},
+	{
+		name: "mentions.deliveries",
+		description: "Deprecated: use mentions.delivery. Removed in the next minor release. Whether each @mention in a message you sent reached its target.",
+		schema: senderMentionDeliveriesRequestSchema,
+		routes: ["senderMentionDeliveries"],
+		consumes: nothing,
+		output: small,
+		deprecated: true
+	},
 	{
 		name: "actions.prepare",
 		description: "Post an action card (create a channel, add members, create an agent, or an integration step) for a human to confirm; the human who clicks it carries it out as themselves. When it is executed (or fails), the outcome arrives as a reply that @mentions you in the card's thread (or in the thread the card was posted in).",
@@ -15798,7 +15942,7 @@ const OPERATION_DEFS = [
 		name: "users.info",
 		description: "A human's or agent's visible facts (kind, status, role, description) and which visible channels they are in. Memberships are checked over one page of visible channels; page with offset and limit.",
 		schema: userInfoRequestSchema,
-		routes: ["serverInfo", "channelMembers"],
+		routes: ["userChannels", "serverInfo"],
 		consumes: nothing,
 		output: {
 			mayBeLarge: true,
@@ -16035,6 +16179,9 @@ function createRaft(options) {
 		},
 		mentions: {
 			pending: (request) => pendingMentionActions(api, request, style).then(styled),
+			notify: (request) => notifyMentions(api, request).then(styled),
+			add: (request) => addMentions(api, request).then(styled),
+			delivery: (request) => senderMentionDeliveries(api, request).then(styled),
 			execute: (request) => executeMentionAction(api, request).then(styled),
 			deliveries: (request) => senderMentionDeliveries(api, request).then(styled)
 		},
@@ -16125,6 +16272,9 @@ function createRaft(options) {
 		"attachments.downloadUrl": (args) => raft.attachments.downloadUrl(args),
 		"attachments.comments": (args) => raft.attachments.comments(args),
 		"mentions.pending": (args) => raft.mentions.pending(args),
+		"mentions.notify": (args) => raft.mentions.notify(args),
+		"mentions.add": (args) => raft.mentions.add(args),
+		"mentions.delivery": (args) => raft.mentions.delivery(args),
 		"mentions.execute": (args) => raft.mentions.execute(args),
 		"mentions.deliveries": (args) => raft.mentions.deliveries(args),
 		"actions.prepare": (args) => raft.actions.prepare(args),
@@ -16239,6 +16389,7 @@ exports.listInboxRequestSchema = listInboxRequestSchema;
 exports.listRaftRoutes = listRaftRoutes;
 exports.listTasksRequestSchema = listTasksRequestSchema;
 exports.listThreadsRequestSchema = listThreadsRequestSchema;
+exports.mentionResolutionIdsRequestSchema = mentionResolutionIdsRequestSchema;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
 exports.parseRaftState = parseRaftState;
 exports.pendingMentionActionsRequestSchema = pendingMentionActionsRequestSchema;