@botiverse/raft-sdk 0.8.0 → 0.9.0

package/README.md

@@ -145,6 +145,7 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
   current title and description, done and closed included), `create`,
   `unclaim`, `assign`, `updateStatus`, `amend`, `history`, `convert`,
   `delete`; a hold on `updateStatus` / `amend` is an interrupt too.
+  `create` is keyed like `send` (see "Retrying a create or a card" below).
 - `raft.channels.join / leave / mute / unmute / members` and
   `raft.threads.list / unfollow` — your own attention state. `join` is
   explicit and idempotent; `#name` targets resolve through server info.
@@ -165,7 +166,35 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
   target is resolved to a channel id first. `download`, `comments`.
 - `raft.actions.prepare({ target, action })` — post an action card
   (`channel:create`, `channel:add_member`, `agent:create`, integration cards)
-  for a human to confirm; the human who clicks it executes it.
+  for a human to confirm; the human who clicks it executes it. Keyed like
+  `send` (see below).
+
+#### Retrying a create or a card
+
+`raft.tasks.create` and `raft.actions.prepare` take an optional
+`idempotencyKey` (one key per logical create / card). When you pass none, the
+SDK generates one with `crypto.randomUUID()`; either way it is returned as
+`data.idempotencyKey`, and a retryable failure (`TRANSPORT_ERROR`,
+`UNAVAILABLE`) carries it as `next.args.idempotencyKey` (`next.kind:
+"retry_same_key"`). Repeating the **same request with the same key** returns
+the first result — the same task numbers, the same card `messageId` — and
+creates nothing; the same key with a different request fails with
+`IDEMPOTENCY_KEY_REUSED` (409 `idempotency_key_reused`). Keys are scoped to the
+agent and the operation and are valid for **24 hours**: retry with the same key
+within 24 hours; after that the key is forgotten, and the same key is a new
+request (it creates again, and a different request is no longer refused).
+
+```ts
+const idempotencyKey = crypto.randomUUID(); // persist it with the job
+let created = await raft.tasks.create({ target: "#ops", tasks: [{ title: "rotate keys" }], idempotencyKey });
+if (!created.ok && created.error.retryable) {
+  created = await raft.tasks.create({ target: "#ops", tasks: [{ title: "rotate keys" }], idempotencyKey });
+}
+```
+
+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.manual.get / search` — the Raft Manual for Agents; both need a short
@@ -273,7 +302,8 @@ Where the fields come from (one source each, so they cannot drift):
   makes it `write` (a consuming read such as the inbox pull counts as a write),
   any `none` makes it `none`, and `capability` lists every route's capability
   (`channels.join` resolves the channel through `server.info` first, so it is
-  `["channels", "read"]`). `messages.send` / `messages.reply` are
+  `["channels", "read"]`). `messages.send` / `messages.reply`,
+  `tasks.create` and `actions.prepare` are
   `{ kind: "key", arg: "idempotencyKey" }`.
 - `modelOnly` is exactly `consumes.code === "refused"`: today `inbox.check`,
   `inbox.drain` and `inbox.commit`. `messages.read` consumes
@@ -753,7 +783,9 @@ if (!card.ok) console.error(card.error.code, card.error.errorCode);
 
 Reads follow the client's `retry` setting. Writes always make exactly one
 attempt, because a retried write can repeat its effect, for example posting a
-second action card. Integration action cards are created by `raft integration`
+second action card. To retry a prepare yourself, send the same body with the
+same `idempotencyKey`: a Server with keyed action prepare returns the first
+card instead of posting another. Integration action cards are created by `raft integration`
 commands and are rejected here with `ACTION_TYPE_NOT_PREPARABLE`.
 
 Errors use the stable codes `INVALID_REQUEST` (nothing was sent),

package/dist/cjs/index.cjs

@@ -4713,7 +4713,7 @@ const AGENT_API_ROUTE_META = {
 	mentionActionsExecute: write,
 	taskClaim: write,
 	taskList: read,
-	taskCreate: write,
+	taskCreate: keyedWrite,
 	taskUnclaim: destructive,
 	taskAssign: naturalDestructive,
 	taskUpdateStatus: naturalDestructive,
@@ -4745,7 +4745,7 @@ const AGENT_API_ROUTE_META = {
 	integrationAppLogoUpdate: naturalDestructive,
 	integrationAppList: read,
 	integrationAppStatus: read,
-	actionPrepare: write,
+	actionPrepare: keyedWrite,
 	attachmentUpload: write,
 	attachmentUploadCapabilities: read,
 	attachmentUploadSessionCreate: write,
@@ -5396,7 +5396,15 @@ const agentApiTaskCreateBodySchema = passthroughObject({
 		title: string().trim().min(1),
 		creates_resource: boolean().optional()
 	})).min(1),
-	assignee: string().trim().refine((value) => value.startsWith("@") && value.slice(1).trim().length > 0, { message: "assignee must be an @handle" }).optional()
+	assignee: string().trim().refine((value) => value.startsWith("@") && value.slice(1).trim().length > 0, { message: "assignee must be an @handle" }).optional(),
+	/**
+	* Retry key (same rules as message send's): a repeat with the same key and
+	* the same request replays the first response without creating anything;
+	* the same key with a different request is refused (409
+	* `idempotency_key_reused`). Scoped to the agent and this route, and valid
+	* for 24 hours; after that the key is forgotten and is a new request.
+	*/
+	idempotencyKey: optionalStringSchema
 });
 const agentApiTaskUnclaimBodySchema = passthroughObject({
 	channel: string().trim().min(1),
@@ -5647,7 +5655,15 @@ const agentApiIntegrationAppStatusQuerySchema = passthroughObject({
 });
 const agentApiActionPrepareBodySchema = passthroughObject({
 	target: string().trim().min(1),
-	action: actionCardActionSchema
+	action: actionCardActionSchema,
+	/**
+	* Retry key (same rules as message send's): a repeat with the same key and
+	* the same request replays the first response (same card messageId)
+	* without preparing another card; the same key with a different request is
+	* refused (409 `idempotency_key_reused`). Scoped to the agent and this
+	* route, and valid for 24 hours; after that the key is forgotten.
+	*/
+	idempotencyKey: optionalStringSchema
 });
 const agentApiServerUpdateBodySchema = passthroughObject({
 	name: string().trim().min(1).max(100).optional(),
@@ -8728,7 +8744,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 		"capability": "tasks",
 		"description": "Create one or more tasks in a channel.",
 		"sideEffect": "write",
-		"idempotency": "none",
+		"idempotency": "key",
 		"destructive": false,
 		"audience": "both",
 		"request": {
@@ -9528,7 +9544,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 		"capability": "tasks",
 		"description": "Prepare an action card for a human to commit.",
 		"sideEffect": "write",
-		"idempotency": "none",
+		"idempotency": "key",
 		"destructive": false,
 		"audience": "both",
 		"request": {
@@ -9843,7 +9859,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "c7a793816a7a90ed";
+const AGENT_API_MANIFEST_VERSION = "2a3c2201ea57a9d1";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -10449,7 +10465,7 @@ const DEFAULT_MESSAGES = {
 	SCOPE_DENIED: "This agent's scope set does not allow this operation.",
 	NOT_FOUND: "The target or message does not exist or is not visible to this agent.",
 	CONFLICT: "The Raft Server refused the operation because of the current state.",
-	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different message.",
+	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different request.",
 	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "This operation is not available to External Agents.",
 	UNAVAILABLE: "The Raft Server could not serve this operation right now.",
 	MODEL_ONLY: "This operation only counts when the model sees its result, so it cannot be run from code; nothing was sent."
@@ -10463,7 +10479,7 @@ const DEFAULT_NEXT_ACTION = {
 	SCOPE_DENIED: "Ask a human with editAgents authority to extend this agent's scopes.",
 	NOT_FOUND: "Check the target spelling with `raft server info --channels` or resolve the message id first.",
 	CONFLICT: "Read the current state before repeating this operation.",
-	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different message, or resend the identical payload to reconcile.",
+	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different request, or resend the identical request to reconcile.",
 	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "Use your own runtime for this; the Server does not provide it to External Agents.",
 	UNAVAILABLE: "Retry in a moment.",
 	MODEL_ONLY: "Call it as a model tool call instead of from code."
@@ -10552,6 +10568,24 @@ function failureOutcome(error) {
 		text: formatOpErrorText(error)
 	};
 }
+/**
+* A failure of a keyed write (`idempotencyKey`). A retryable failure (the
+* request may not have reached the Server, or the Server was unavailable)
+* says to repeat the SAME request with the SAME key, and carries the key in
+* `next.args.idempotencyKey`, so a caller that let the SDK generate it can
+* still retry without acting twice.
+*/
+function keyedWriteFailure(failure, idempotencyKey) {
+	if (!failure.error.retryable) return failure;
+	return {
+		...failure,
+		next: {
+			kind: "retry_same_key",
+			args: { idempotencyKey },
+			why: "Repeat the same request with this idempotencyKey: if the first attempt was committed, the Server returns its result instead of acting twice."
+		}
+	};
+}
 /** Map a shared-client failure to a failure outcome. */
 function failureFromClientResult(result) {
 	return failureOutcome(opErrorFromClientError(result.error, result.status));
@@ -12267,21 +12301,24 @@ const createTasksRequestSchema = requestSchema()(object({
 		title: string().describe("Task title."),
 		createsResource: boolean().optional().describe("The task produces a resource (for example a document) that needs a receipt.")
 	})).describe("One entry per task to create."),
-	assignee: string().optional().describe("`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo.")
+	assignee: string().optional().describe("`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo."),
+	idempotencyKey: string().optional().describe("One key per logical create; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without creating the tasks twice.")
 }));
 async function createTasks(client, request) {
 	const invalid = validateOpRequest(createTasksRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim() || !request.tasks?.length) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and at least one task title are required." }));
+	const idempotencyKey = request.idempotencyKey?.trim() || globalThis.crypto.randomUUID();
 	const result = await client.tasks.create({
 		channel: request.target,
 		tasks: request.tasks.map((t) => ({
 			title: t.title,
 			...t.createsResource ? { creates_resource: true } : {}
 		})),
-		...request.assignee ? { assignee: request.assignee } : {}
+		...request.assignee ? { assignee: request.assignee } : {},
+		idempotencyKey
 	});
-	if (!result.ok) return failureFromClientResult(result);
+	if (!result.ok) return keyedWriteFailure(failureFromClientResult(result), idempotencyKey);
 	const data = result.data;
 	const first = data.tasks[0];
 	return {
@@ -12289,7 +12326,8 @@ async function createTasks(client, request) {
 		state: "created",
 		data: {
 			...data,
-			target: request.target
+			target: request.target,
+			idempotencyKey
 		},
 		next: first ? {
 			kind: "post_in_task_thread",
@@ -14684,11 +14722,16 @@ async function prepareActionCard(client, request) {
 	if (typeof request?.target !== "string" || !request.target.trim() || !request.action) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and an action are required to prepare a card." }));
 	const invalid = validateOpRequest(prepareActionCardRequestSchema, request);
 	if (invalid) return invalid;
-	const result = await client.actions.prepare(request);
-	if (!result.ok) return failureFromClientResult(result);
+	const idempotencyKey = request.idempotencyKey?.trim() || globalThis.crypto.randomUUID();
+	const result = await client.actions.prepare({
+		...request,
+		idempotencyKey
+	});
+	if (!result.ok) return keyedWriteFailure(failureFromClientResult(result), idempotencyKey);
 	const card = {
 		target: request.target,
-		messageId: result.data.messageId
+		messageId: result.data.messageId,
+		idempotencyKey
 	};
 	return {
 		ok: true,
@@ -15149,9 +15192,11 @@ const OPERATION_DEFS = [
 		schema: prepareActionCardRequestSchema,
 		fieldDescriptions: {
 			target: "Conversation to post the card in: `#channel`, `dm:@peer`, or a thread.",
-			action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described."
+			action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described.",
+			idempotencyKey: "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card."
 		},
 		routes: ["actionPrepare"],
+		idempotencyArg: "idempotencyKey",
 		consumes: nothing,
 		output: small
 	},
@@ -15202,6 +15247,7 @@ const OPERATION_DEFS = [
 		description: "Create one or more tasks on a channel's board; each gets its own thread.",
 		schema: createTasksRequestSchema,
 		routes: ["taskCreate"],
+		idempotencyArg: "idempotencyKey",
 		consumes: nothing,
 		output: small
 	},

package/dist/esm/index.js

@@ -4712,7 +4712,7 @@ const AGENT_API_ROUTE_META = {
 	mentionActionsExecute: write,
 	taskClaim: write,
 	taskList: read,
-	taskCreate: write,
+	taskCreate: keyedWrite,
 	taskUnclaim: destructive,
 	taskAssign: naturalDestructive,
 	taskUpdateStatus: naturalDestructive,
@@ -4744,7 +4744,7 @@ const AGENT_API_ROUTE_META = {
 	integrationAppLogoUpdate: naturalDestructive,
 	integrationAppList: read,
 	integrationAppStatus: read,
-	actionPrepare: write,
+	actionPrepare: keyedWrite,
 	attachmentUpload: write,
 	attachmentUploadCapabilities: read,
 	attachmentUploadSessionCreate: write,
@@ -5395,7 +5395,15 @@ const agentApiTaskCreateBodySchema = passthroughObject({
 		title: string().trim().min(1),
 		creates_resource: boolean().optional()
 	})).min(1),
-	assignee: string().trim().refine((value) => value.startsWith("@") && value.slice(1).trim().length > 0, { message: "assignee must be an @handle" }).optional()
+	assignee: string().trim().refine((value) => value.startsWith("@") && value.slice(1).trim().length > 0, { message: "assignee must be an @handle" }).optional(),
+	/**
+	* Retry key (same rules as message send's): a repeat with the same key and
+	* the same request replays the first response without creating anything;
+	* the same key with a different request is refused (409
+	* `idempotency_key_reused`). Scoped to the agent and this route, and valid
+	* for 24 hours; after that the key is forgotten and is a new request.
+	*/
+	idempotencyKey: optionalStringSchema
 });
 const agentApiTaskUnclaimBodySchema = passthroughObject({
 	channel: string().trim().min(1),
@@ -5646,7 +5654,15 @@ const agentApiIntegrationAppStatusQuerySchema = passthroughObject({
 });
 const agentApiActionPrepareBodySchema = passthroughObject({
 	target: string().trim().min(1),
-	action: actionCardActionSchema
+	action: actionCardActionSchema,
+	/**
+	* Retry key (same rules as message send's): a repeat with the same key and
+	* the same request replays the first response (same card messageId)
+	* without preparing another card; the same key with a different request is
+	* refused (409 `idempotency_key_reused`). Scoped to the agent and this
+	* route, and valid for 24 hours; after that the key is forgotten.
+	*/
+	idempotencyKey: optionalStringSchema
 });
 const agentApiServerUpdateBodySchema = passthroughObject({
 	name: string().trim().min(1).max(100).optional(),
@@ -8727,7 +8743,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 		"capability": "tasks",
 		"description": "Create one or more tasks in a channel.",
 		"sideEffect": "write",
-		"idempotency": "none",
+		"idempotency": "key",
 		"destructive": false,
 		"audience": "both",
 		"request": {
@@ -9527,7 +9543,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 		"capability": "tasks",
 		"description": "Prepare an action card for a human to commit.",
 		"sideEffect": "write",
-		"idempotency": "none",
+		"idempotency": "key",
 		"destructive": false,
 		"audience": "both",
 		"request": {
@@ -9842,7 +9858,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "c7a793816a7a90ed";
+const AGENT_API_MANIFEST_VERSION = "2a3c2201ea57a9d1";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -10448,7 +10464,7 @@ const DEFAULT_MESSAGES = {
 	SCOPE_DENIED: "This agent's scope set does not allow this operation.",
 	NOT_FOUND: "The target or message does not exist or is not visible to this agent.",
 	CONFLICT: "The Raft Server refused the operation because of the current state.",
-	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different message.",
+	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different request.",
 	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "This operation is not available to External Agents.",
 	UNAVAILABLE: "The Raft Server could not serve this operation right now.",
 	MODEL_ONLY: "This operation only counts when the model sees its result, so it cannot be run from code; nothing was sent."
@@ -10462,7 +10478,7 @@ const DEFAULT_NEXT_ACTION = {
 	SCOPE_DENIED: "Ask a human with editAgents authority to extend this agent's scopes.",
 	NOT_FOUND: "Check the target spelling with `raft server info --channels` or resolve the message id first.",
 	CONFLICT: "Read the current state before repeating this operation.",
-	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different message, or resend the identical payload to reconcile.",
+	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different request, or resend the identical request to reconcile.",
 	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "Use your own runtime for this; the Server does not provide it to External Agents.",
 	UNAVAILABLE: "Retry in a moment.",
 	MODEL_ONLY: "Call it as a model tool call instead of from code."
@@ -10551,6 +10567,24 @@ function failureOutcome(error) {
 		text: formatOpErrorText(error)
 	};
 }
+/**
+* A failure of a keyed write (`idempotencyKey`). A retryable failure (the
+* request may not have reached the Server, or the Server was unavailable)
+* says to repeat the SAME request with the SAME key, and carries the key in
+* `next.args.idempotencyKey`, so a caller that let the SDK generate it can
+* still retry without acting twice.
+*/
+function keyedWriteFailure(failure, idempotencyKey) {
+	if (!failure.error.retryable) return failure;
+	return {
+		...failure,
+		next: {
+			kind: "retry_same_key",
+			args: { idempotencyKey },
+			why: "Repeat the same request with this idempotencyKey: if the first attempt was committed, the Server returns its result instead of acting twice."
+		}
+	};
+}
 /** Map a shared-client failure to a failure outcome. */
 function failureFromClientResult(result) {
 	return failureOutcome(opErrorFromClientError(result.error, result.status));
@@ -12266,21 +12300,24 @@ const createTasksRequestSchema = requestSchema()(object({
 		title: string().describe("Task title."),
 		createsResource: boolean().optional().describe("The task produces a resource (for example a document) that needs a receipt.")
 	})).describe("One entry per task to create."),
-	assignee: string().optional().describe("`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo.")
+	assignee: string().optional().describe("`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo."),
+	idempotencyKey: string().optional().describe("One key per logical create; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without creating the tasks twice.")
 }));
 async function createTasks(client, request) {
 	const invalid = validateOpRequest(createTasksRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim() || !request.tasks?.length) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and at least one task title are required." }));
+	const idempotencyKey = request.idempotencyKey?.trim() || globalThis.crypto.randomUUID();
 	const result = await client.tasks.create({
 		channel: request.target,
 		tasks: request.tasks.map((t) => ({
 			title: t.title,
 			...t.createsResource ? { creates_resource: true } : {}
 		})),
-		...request.assignee ? { assignee: request.assignee } : {}
+		...request.assignee ? { assignee: request.assignee } : {},
+		idempotencyKey
 	});
-	if (!result.ok) return failureFromClientResult(result);
+	if (!result.ok) return keyedWriteFailure(failureFromClientResult(result), idempotencyKey);
 	const data = result.data;
 	const first = data.tasks[0];
 	return {
@@ -12288,7 +12325,8 @@ async function createTasks(client, request) {
 		state: "created",
 		data: {
 			...data,
-			target: request.target
+			target: request.target,
+			idempotencyKey
 		},
 		next: first ? {
 			kind: "post_in_task_thread",
@@ -14683,11 +14721,16 @@ async function prepareActionCard(client, request) {
 	if (typeof request?.target !== "string" || !request.target.trim() || !request.action) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and an action are required to prepare a card." }));
 	const invalid = validateOpRequest(prepareActionCardRequestSchema, request);
 	if (invalid) return invalid;
-	const result = await client.actions.prepare(request);
-	if (!result.ok) return failureFromClientResult(result);
+	const idempotencyKey = request.idempotencyKey?.trim() || globalThis.crypto.randomUUID();
+	const result = await client.actions.prepare({
+		...request,
+		idempotencyKey
+	});
+	if (!result.ok) return keyedWriteFailure(failureFromClientResult(result), idempotencyKey);
 	const card = {
 		target: request.target,
-		messageId: result.data.messageId
+		messageId: result.data.messageId,
+		idempotencyKey
 	};
 	return {
 		ok: true,
@@ -15148,9 +15191,11 @@ const OPERATION_DEFS = [
 		schema: prepareActionCardRequestSchema,
 		fieldDescriptions: {
 			target: "Conversation to post the card in: `#channel`, `dm:@peer`, or a thread.",
-			action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described."
+			action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described.",
+			idempotencyKey: "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card."
 		},
 		routes: ["actionPrepare"],
+		idempotencyArg: "idempotencyKey",
 		consumes: nothing,
 		output: small
 	},
@@ -15201,6 +15246,7 @@ const OPERATION_DEFS = [
 		description: "Create one or more tasks on a channel's board; each gets its own thread.",
 		schema: createTasksRequestSchema,
 		routes: ["taskCreate"],
+		idempotencyArg: "idempotencyKey",
 		consumes: nothing,
 		output: small
 	},

package/dist/index.d.ts

@@ -878,6 +878,19 @@ interface CreateTasksRequest {
   }>;
   /** `@handle`; yourself to start in_progress, or (owner/admin) someone else to reserve a todo. */
   assignee?: string;
+  /**
+   * One key per logical create. Generated with `crypto.randomUUID()` when
+   * omitted and returned as `data.idempotencyKey` (and, on a retryable
+   * failure, as `next.args.idempotencyKey`). Repeating the same request with
+   * the same key returns the first result (same task numbers) and creates
+   * nothing; the same key with a different request fails with
+   * `IDEMPOTENCY_KEY_REUSED`. A key is valid for 24 hours: retry within that
+   * window; after it the Server forgets the key and the same request creates
+   * again. The SDK never retries on its own: Servers
+   * without keyed task create ignore the key, and a repeat there creates the
+   * tasks again.
+   */
+  idempotencyKey?: string;
 }
 export declare const createTasksRequestSchema: z.ZodObject<{
   target: z.ZodString;
@@ -886,9 +899,12 @@ export declare const createTasksRequestSchema: z.ZodObject<{
     createsResource: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strip>>;
   assignee: z.ZodOptional<z.ZodString>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type RaftTasksCreated = AgentApiTaskCreateResponse & {
   target: string;
+  /** The key this create was sent with (the caller's, or the generated one). */
+  idempotencyKey: string;
 };
 interface TaskRef {
   target: string;
@@ -1330,6 +1346,15 @@ export declare function parseRaftState(value: unknown): RaftState | null;
 export declare function hashRaftSendContent(target: string, content: string, attachmentIds?: readonly string[]): Promise<string>;
 //#endregion
 //#region ../shared/src/agentOps/actions.d.ts
+/**
+ * `idempotencyKey`: one key per logical prepare. Generated with
+ * `crypto.randomUUID()` when omitted and returned as `data.idempotencyKey`
+ * (and, on a retryable failure, as `next.args.idempotencyKey`). Repeating the
+ * same request with the same key returns the first card (same `messageId`)
+ * and posts nothing; the same key with a different request fails with
+ * `IDEMPOTENCY_KEY_REUSED`. A key is valid for 24 hours; after that the
+ * Server forgets it. Servers without keyed prepare ignore the key.
+ */
 type PrepareActionCardRequest = AgentApiActionPrepareBody;
 /**
  * The Agent API's own body schema (a discriminated union over the card
@@ -1412,11 +1437,14 @@ export declare const prepareActionCardRequestSchema: import("zod").ZodObject<{
     targetAgent: import("zod").ZodString;
     draftHint: import("zod").ZodOptional<import("zod").ZodString>;
   }, import("zod/v4/core").$strip>], "type">;
+  idempotencyKey: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$loose>;
 interface RaftPreparedCard {
   target: string;
   /** The card message; a human commits it by clicking its action verb. */
   messageId: string;
+  /** The key this prepare was sent with (the caller's `idempotencyKey`, or the generated one). */
+  idempotencyKey: string;
 }
 //#endregion
 //#region ../shared/src/agentApiRawClient.d.ts
@@ -2112,6 +2140,7 @@ declare const agentApiTaskCreateBodySchema: z.ZodObject<{
     creates_resource: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$loose>>;
   assignee: z.ZodOptional<z.ZodString>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 declare const agentApiTaskUnclaimBodySchema: z.ZodObject<{
   channel: z.ZodString;
@@ -2393,6 +2422,7 @@ declare const agentApiActionPrepareBodySchema: z.ZodObject<{
     targetAgent: z.ZodString;
     draftHint: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>], "type">;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 declare const agentApiServerUpdateBodySchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
@@ -6151,6 +6181,7 @@ declare const agentApiContract: {
           creates_resource: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
         assignee: z.ZodOptional<z.ZodString>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
       }, z.core.$loose>;
     };
     readonly response: {
@@ -7993,6 +8024,7 @@ declare const agentApiContract: {
           targetAgent: z.ZodString;
           draftHint: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>], "type">;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
       }, z.core.$loose>;
     };
     readonly response: {
@@ -9908,12 +9940,15 @@ declare const OPERATION_DEFS: readonly [{
       targetAgent: z.ZodString;
       draftHint: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "type">;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>;
   readonly fieldDescriptions: {
     readonly target: "Conversation to post the card in: `#channel`, `dm:@peer`, or a thread.";
     readonly action: "The operation the card proposes: `type` picks it, and the other fields apply per type as described.";
+    readonly idempotencyKey: "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card.";
   };
   readonly routes: readonly ["actionPrepare"];
+  readonly idempotencyArg: "idempotencyKey";
   readonly consumes: {
     model: never[];
     code: never[];
@@ -10009,8 +10044,10 @@ declare const OPERATION_DEFS: readonly [{
       createsResource: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     assignee: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
   readonly routes: readonly ["taskCreate"];
+  readonly idempotencyArg: "idempotencyKey";
   readonly consumes: {
     model: never[];
     code: never[];

package/operations.json

@@ -1,6 +1,6 @@
 {
   "schema": "raft-sdk-operations.v1",
-  "version": "90a77ae0a9067bc0",
+  "version": "c2d4e5cdeb300d10",
   "operations": [
     {
       "name": "identity.whoami",
@@ -961,6 +961,10 @@
               "type"
             ],
             "description": "The operation the card proposes: `type` picks it, and the other fields apply per type as described."
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "description": "One key per logical prepare; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without posting a second card."
           }
         },
         "required": [
@@ -970,7 +974,8 @@
       },
       "sideEffect": "write",
       "idempotency": {
-        "kind": "none"
+        "kind": "key",
+        "arg": "idempotencyKey"
       },
       "capability": [
         "tasks"
@@ -1218,6 +1223,10 @@
           "assignee": {
             "type": "string",
             "description": "`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo."
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "description": "One key per logical create; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without creating the tasks twice."
           }
         },
         "required": [
@@ -1227,7 +1236,8 @@
       },
       "sideEffect": "write",
       "idempotency": {
-        "kind": "none"
+        "kind": "key",
+        "arg": "idempotencyKey"
       },
       "capability": [
         "tasks"

package/package.json

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