@botiverse/raft-sdk 0.10.0 → 0.11.0

package/README.md

@@ -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

@@ -10735,11 +10735,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",
@@ -14724,6 +14721,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 +14757,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 +14790,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 +15566,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).",
@@ -16035,6 +16078,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 +16171,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 +16288,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;

package/dist/esm/index.js

@@ -10734,11 +10734,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",
@@ -14723,6 +14720,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.")
@@ -14757,13 +14756,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);
@@ -14772,11 +14789,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) {
@@ -15548,21 +15565,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).",
@@ -16034,6 +16077,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)
 		},
@@ -16124,6 +16170,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),
@@ -16194,4 +16243,4 @@ function whoamiOutcome(result) {
 	};
 }
 //#endregion
-export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_JSON_SCHEMA_KEYWORDS, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RAFT_OPERATIONS, RAFT_OPERATIONS_SCHEMA, RAFT_OPERATIONS_VERSION, RAFT_STATE_CONTINUATIONS_PER_TARGET, RAFT_STATE_CONTINUATIONS_TOTAL, RAFT_STATE_SCHEMA, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, amendTaskRequestSchema, assignTaskRequestSchema, attachmentCommentsRequestSchema, bootstrapRaftCredential, channelInfoRequestSchema, channelMembersRequestSchema, channelTargetRequestSchema, checkInboxRequestSchema, claimTasksRequestSchema, commitInboxRequestSchema, convertMessageToTaskRequestSchema, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, createTasksRequestSchema, describeRaftRoute, downloadAttachmentUrlRequestSchema, drainInboxRequestSchema, executeMentionActionRequestSchema, getManualTopicRequestSchema, hasAgentMessageIdentity, hashRaftSendContent, inferAttachmentMimeType, isInterrupted, joinRaftChannelByTarget, listInboxRequestSchema, listRaftRoutes, listTasksRequestSchema, listThreadsRequestSchema, parseRaftRegularChannelTarget, parseRaftState, pendingMentionActionsRequestSchema, prepareActionCardRequestSchema, projectRaftMessage, projectRaftMessages, raftToolNameFor, reactRequestSchema, readHistoryRequestSchema, readLatestReadThread, replyToRequestSchema, resolveMessageRequestSchema, searchManualRequestSchema, searchMessagesRequestSchema, sendMessageRequestSchema, senderMentionDeliveriesRequestSchema, serverInfoRequestSchema, showProfileRequestSchema, taskRefSchema, unfollowThreadRequestSchema, updateProfileRequestSchema, updateTaskStatusRequestSchema, userInfoRequestSchema, verifyInboxNotice, whoamiRequestSchema };
+export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_JSON_SCHEMA_KEYWORDS, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RAFT_OPERATIONS, RAFT_OPERATIONS_SCHEMA, RAFT_OPERATIONS_VERSION, RAFT_STATE_CONTINUATIONS_PER_TARGET, RAFT_STATE_CONTINUATIONS_TOTAL, RAFT_STATE_SCHEMA, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, amendTaskRequestSchema, assignTaskRequestSchema, attachmentCommentsRequestSchema, bootstrapRaftCredential, channelInfoRequestSchema, channelMembersRequestSchema, channelTargetRequestSchema, checkInboxRequestSchema, claimTasksRequestSchema, commitInboxRequestSchema, convertMessageToTaskRequestSchema, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, createTasksRequestSchema, describeRaftRoute, downloadAttachmentUrlRequestSchema, drainInboxRequestSchema, executeMentionActionRequestSchema, getManualTopicRequestSchema, hasAgentMessageIdentity, hashRaftSendContent, inferAttachmentMimeType, isInterrupted, joinRaftChannelByTarget, listInboxRequestSchema, listRaftRoutes, listTasksRequestSchema, listThreadsRequestSchema, mentionResolutionIdsRequestSchema, parseRaftRegularChannelTarget, parseRaftState, pendingMentionActionsRequestSchema, prepareActionCardRequestSchema, projectRaftMessage, projectRaftMessages, raftToolNameFor, reactRequestSchema, readHistoryRequestSchema, readLatestReadThread, replyToRequestSchema, resolveMessageRequestSchema, searchManualRequestSchema, searchMessagesRequestSchema, sendMessageRequestSchema, senderMentionDeliveriesRequestSchema, serverInfoRequestSchema, showProfileRequestSchema, taskRefSchema, unfollowThreadRequestSchema, updateProfileRequestSchema, updateTaskStatusRequestSchema, userInfoRequestSchema, verifyInboxNotice, whoamiRequestSchema };

package/dist/index.d.ts

@@ -1295,6 +1295,10 @@ interface AgentMentionActionResult {
 export declare const pendingMentionActionsRequestSchema: z.ZodObject<{
   limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+export declare const mentionResolutionIdsRequestSchema: z.ZodObject<{
+  resolutionIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** @deprecated The request of the deprecated `mentions.execute`; use `mentionResolutionIdsRequestSchema` (`mentions.notify` / `mentions.add`). */
 export declare const executeMentionActionRequestSchema: z.ZodObject<{
   action: z.ZodEnum<{
     notify: "notify";
@@ -1311,6 +1315,14 @@ interface RaftPendingMentions {
   hasMore: boolean | null;
   limit: number | undefined;
 }
+interface MentionResolutionIdsRequest {
+  resolutionIds: string[];
+}
+type RaftMentionActionOutcome = RaftOutcome<{
+  action: AgentMentionActionKind;
+  results: AgentMentionActionResult[];
+}, "executed">;
+/** @deprecated The request of the deprecated `mentions.execute`; use `MentionResolutionIdsRequest`. */
 interface ExecuteMentionActionRequest {
   action: AgentMentionActionKind;
   resolutionIds: string[];
@@ -9916,9 +9928,54 @@ declare const OPERATION_DEFS: readonly [{
     readonly mayBeLarge: true;
     readonly boundBy: ["limit"];
   };
+}, {
+  readonly name: "mentions.notify";
+  readonly description: "Deliver unreached @mentions by notifying each mentioned target about the message, without adding them to the conversation. Takes resolutionId values from mentions.pending.";
+  readonly schema: z.ZodObject<{
+    resolutionIds: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>;
+  readonly routes: readonly ["mentionActionsExecute"];
+  readonly consumes: {
+    model: never[];
+    code: never[];
+  };
+  readonly output: {
+    mayBeLarge: false;
+    boundBy: never[];
+  };
+}, {
+  readonly name: "mentions.add";
+  readonly 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.";
+  readonly schema: z.ZodObject<{
+    resolutionIds: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>;
+  readonly routes: readonly ["mentionActionsExecute"];
+  readonly consumes: {
+    model: never[];
+    code: never[];
+  };
+  readonly output: {
+    mayBeLarge: false;
+    boundBy: never[];
+  };
+}, {
+  readonly name: "mentions.delivery";
+  readonly description: "Whether each @mention in a message you sent reached its target.";
+  readonly schema: z.ZodObject<{
+    messageId: z.ZodString;
+  }, z.core.$strip>;
+  readonly routes: readonly ["senderMentionDeliveries"];
+  readonly consumes: {
+    model: never[];
+    code: never[];
+  };
+  readonly output: {
+    mayBeLarge: false;
+    boundBy: never[];
+  };
 }, {
   readonly name: "mentions.execute";
-  readonly description: "Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.";
+  readonly 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.";
   readonly schema: z.ZodObject<{
     action: z.ZodEnum<{
       notify: "notify";
@@ -9935,9 +9992,10 @@ declare const OPERATION_DEFS: readonly [{
     mayBeLarge: false;
     boundBy: never[];
   };
+  readonly deprecated: true;
 }, {
   readonly name: "mentions.deliveries";
-  readonly description: "Whether each @mention in a message you sent reached its target.";
+  readonly description: "Deprecated: use mentions.delivery. Removed in the next minor release. Whether each @mention in a message you sent reached its target.";
   readonly schema: z.ZodObject<{
     messageId: z.ZodString;
   }, z.core.$strip>;
@@ -9950,6 +10008,7 @@ declare const OPERATION_DEFS: readonly [{
     mayBeLarge: false;
     boundBy: never[];
   };
+  readonly deprecated: true;
 }, {
   readonly name: "actions.prepare";
   readonly 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).";
@@ -10686,12 +10745,17 @@ interface Raft {
     pending(request?: {
       limit?: number;
     }): Promise<RaftOutcome<RaftPendingMentions, "pending" | "empty">>;
-    /** `notify` the target of an unreached mention, or `add` them to the conversation. */
-    execute(request: ExecuteMentionActionRequest): Promise<RaftOutcome<{
-      action: AgentMentionActionKind;
-      results: AgentMentionActionResult[];
-    }, "executed">>;
-    /** Per-target delivery outcome for a message you sent. */
+    /** Notify the targets of unreached mentions about the message (`raft mention notify`). */
+    notify(request: MentionResolutionIdsRequest): Promise<RaftMentionActionOutcome>;
+    /** Add the targets of unreached mentions to the conversation (`raft mention add`). */
+    add(request: MentionResolutionIdsRequest): Promise<RaftMentionActionOutcome>;
+    /** Per-target delivery outcome for a message you sent (`raft mention delivery`). */
+    delivery(request: {
+      messageId: string;
+    }): Promise<RaftOutcome<AgentApiSenderMentionDeliveriesResponse, "deliveries" | "empty">>;
+    /** @deprecated Use `mentions.notify` / `mentions.add`; removed in 0.12.0. */
+    execute(request: ExecuteMentionActionRequest): Promise<RaftMentionActionOutcome>;
+    /** @deprecated Use `mentions.delivery`; removed in 0.12.0. */
     deliveries(request: {
       messageId: string;
     }): Promise<RaftOutcome<AgentApiSenderMentionDeliveriesResponse, "deliveries" | "empty">>;
@@ -10829,4 +10893,4 @@ export declare const commitInboxRequestSchema: z.ZodObject<{
   cursor: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 //#endregion
-export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, ConvertMessageToTaskRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentDownloadUrl, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelInfo, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftConsumption, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHintStyle, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxDrained, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftInvokeCaller, RaftInvokeResult, RaftJsonSchema, RaftJsonSchemaType, RaftLatestReadThread, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextOperation, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOperationIdempotency, RaftOperationName, RaftOperationSpec, RaftOperationsDocument, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftUserInfo, RaftUserRef, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, ReplyToRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, UserInfoRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, ConvertMessageToTaskRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, MentionResolutionIdsRequest, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentDownloadUrl, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelInfo, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftConsumption, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHintStyle, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxDrained, RaftInboxListing, RaftInboxNotice, RaftInterrupt, RaftInterruptCancel, RaftInterruptReason, RaftInterruptResume, RaftInterrupted, RaftInvokeCaller, RaftInvokeResult, RaftJsonSchema, RaftJsonSchemaType, RaftLatestReadThread, RaftManageClient, RaftMentionActionOutcome, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextOperation, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOperationIdempotency, RaftOperationName, RaftOperationSpec, RaftOperationsDocument, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftUserInfo, RaftUserRef, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, ReadLatestReadThreadOptions, ReplyToRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, UserInfoRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };

package/operations.json

@@ -1,6 +1,6 @@
 {
   "schema": "raft-sdk-operations.v1",
-  "version": "4e70c891e417cd51",
+  "version": "16c7523f47f8b204",
   "operations": [
     {
       "name": "identity.whoami",
@@ -729,10 +729,118 @@
         ]
       }
     },
+    {
+      "name": "mentions.notify",
+      "toolName": "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.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "resolutionIds": {
+            "type": "array",
+            "description": "resolutionId values from mentions.pending.",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "resolutionIds"
+        ]
+      },
+      "sideEffect": "write",
+      "idempotency": {
+        "kind": "none"
+      },
+      "capability": [
+        "mentions"
+      ],
+      "modelOnly": false,
+      "mayInterrupt": false,
+      "consumes": {
+        "model": [],
+        "code": []
+      },
+      "output": {
+        "mayBeLarge": false,
+        "boundBy": []
+      }
+    },
+    {
+      "name": "mentions.add",
+      "toolName": "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.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "resolutionIds": {
+            "type": "array",
+            "description": "resolutionId values from mentions.pending.",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "resolutionIds"
+        ]
+      },
+      "sideEffect": "write",
+      "idempotency": {
+        "kind": "none"
+      },
+      "capability": [
+        "mentions"
+      ],
+      "modelOnly": false,
+      "mayInterrupt": false,
+      "consumes": {
+        "model": [],
+        "code": []
+      },
+      "output": {
+        "mayBeLarge": false,
+        "boundBy": []
+      }
+    },
+    {
+      "name": "mentions.delivery",
+      "toolName": "mentions_delivery",
+      "description": "Whether each @mention in a message you sent reached its target.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "messageId": {
+            "type": "string",
+            "description": "Id of a message you sent."
+          }
+        },
+        "required": [
+          "messageId"
+        ]
+      },
+      "sideEffect": "read",
+      "idempotency": {
+        "kind": "natural"
+      },
+      "capability": [
+        "mentions"
+      ],
+      "modelOnly": false,
+      "mayInterrupt": false,
+      "consumes": {
+        "model": [],
+        "code": []
+      },
+      "output": {
+        "mayBeLarge": false,
+        "boundBy": []
+      }
+    },
     {
       "name": "mentions.execute",
       "toolName": "mentions_execute",
-      "description": "Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.",
+      "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.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -773,12 +881,13 @@
       "output": {
         "mayBeLarge": false,
         "boundBy": []
-      }
+      },
+      "deprecated": true
     },
     {
       "name": "mentions.deliveries",
       "toolName": "mentions_deliveries",
-      "description": "Whether each @mention in a message you sent reached its target.",
+      "description": "Deprecated: use mentions.delivery. Removed in the next minor release. Whether each @mention in a message you sent reached its target.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -807,7 +916,8 @@
       "output": {
         "mayBeLarge": false,
         "boundBy": []
-      }
+      },
+      "deprecated": true
     },
     {
       "name": "actions.prepare",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",