@botiverse/raft-sdk 0.7.0 → 0.9.0

package/README.md

@@ -141,15 +141,22 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
   `idempotency_key_reused`.
 - `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
   are rows, a hold is an interrupt whose resume is the identical claim.
-  Also `tasks.list` (a channel board or `mine: true`), `create`, `unclaim`,
-  `assign`, `updateStatus`, `amend`, `history`, `convert`, `delete`; a hold on
-  `updateStatus` / `amend` is an interrupt too.
+  Also `tasks.list` (a channel board or `mine: true`), `show` (one task's
+  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.
+  `raft.channels.info({ target })` — one regular channel's facts (visibility,
+  joined, your channel role, mute, description, member counts).
 - `raft.server.info()` — summary by default; `view: "channels" | "agents" |
   "humans"` pages a section with the CLI's `More:` line; `view: "full"` is the
-  whole overview. `raft.profile.show / update`.
+  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 /
+  update`.
 - `raft.messages.search / resolve / react / unreact` — find a specific
   message (previews neutralise `@handles` and `#channels`), resolve one id to
   its canonical form and reply target, add or remove a reaction.
@@ -159,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
@@ -267,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
@@ -284,8 +320,10 @@ whenever any field of any operation does.
 `$ref` / `$defs`, no `oneOf` / `anyOf` / `allOf`, no `const`. Richer request
 types are flattened so that every JSON-valid call is accepted by the runtime
 (zod stays the strict check): a nullable field is advertised as its non-null
-type and is optional (omitting it means null: `tasks.assign` without
-`assignee` clears it; the runtime still accepts an explicit null);
+type and is optional; omitting it never clears anything (for example
+`tasks.amend` without `description` leaves the description unchanged), and a
+value an operation cannot do without is required (`tasks.assign` requires
+`assignee`; clearing an assignee is `tasks.unassign`);
 `messages.read`'s `around` (seq or message id) is a `string` (a seq as
 `"12345"` reads the same window as `12345`);
 `actions.prepare`'s `action` is one object whose `type` enum picks the card and
@@ -745,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));
@@ -12079,6 +12113,22 @@ function formatAgentTaskHistory(data) {
 		return `seq=${event.seq} time=${event.createdAt} actor=${actor} type=${event.eventType}\n  ${JSON.stringify(event.payload)}`;
 	}).join("\n")}`;
 }
+/**
+* `raft task show`: one task's current title and description (moved verbatim
+* from the CLI's commands/task/show.ts). Labels match the agent delivery
+* surface (`Current title:` / `Current description:`). `description` has three
+* states that must not collapse: a string, an explicit null, and a field the
+* envelope omitted.
+*/
+function formatAgentTaskShow(target, task) {
+	const descriptionLine = typeof task.description === "string" ? `Current description: ${task.description}` : task.description === null ? "Current description: (none set)" : "Current description: (not returned by this surface)";
+	return [
+		`#${task.taskNumber} [${task.status ?? "unknown"}] in ${target}`,
+		`Current title: ${task.title ?? "(none set)"}`,
+		descriptionLine,
+		""
+	].join("\n");
+}
 //#endregion
 //#region ../shared/src/agentOps/tasks.ts
 const taskChannelSchema = string().describe("The channel the task board belongs to, for example `#proj-sdk`.");
@@ -12251,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 {
@@ -12273,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",
@@ -12468,6 +12522,38 @@ async function taskHistory(client, request) {
 		text: formatAgentTaskHistory(result.data)
 	};
 }
+/**
+* `raft task show`: one task's current title and description. Reads the
+* channel's whole board (`status: "all"`, so done and closed tasks are found)
+* and picks the task; a miss says whether the Server asserted the list is
+* complete, exactly as the CLI does.
+*/
+async function showTask(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const { target, taskNumber } = request;
+	const result = await client.tasks.list({
+		channel: target,
+		status: "all"
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const tasks = result.data.tasks ?? [];
+	const task = tasks.find((candidate) => candidate.taskNumber === taskNumber);
+	if (!task) return failureOutcome(opError("NOT_FOUND", {
+		message: result.data.pagination?.mode === "complete" && result.data.pagination.truncated === false ? `task #${taskNumber} not found in ${target} (searched ${tasks.length} task(s), status=all; server asserts this list is complete)` : tasks.length === 0 ? `task #${taskNumber} not found in ${target}: the server returned 0 tasks and did not assert the list is complete. That can mean the channel has no tasks, or that the server failed to read them (it currently reports some read errors as an empty list), and this command cannot tell which — so this is not evidence that task #${taskNumber} does not exist` : `task #${taskNumber} not found in ${target} (searched ${tasks.length} task(s), status=all; this surface does NOT assert completeness — so this is "absent from what was returned", not "does not exist")`,
+		nextAction: `Check the number with \`raft task list --target "${target}" --status all\`.`
+	}));
+	return {
+		ok: true,
+		state: "task",
+		data: {
+			target,
+			task
+		},
+		next: null,
+		text: formatAgentTaskShow(target, task)
+	};
+}
 const convertMessageToTaskRequestSchema = requestSchema()(object({
 	target: taskChannelSchema,
 	messageId: string().describe("Full or short id of a top-level message in that channel.")
@@ -12796,6 +12882,30 @@ function formatPageFooter(page) {
 	if (page.nextCommand && end < page.total) lines.push(`More: ${page.nextCommand}`);
 	return `${lines.join("\n")}\n`;
 }
+/** Single channel detail block. */
+function formatAgentChannelInfo(channel, memberCounts) {
+	const lines = ["## Channel", ""];
+	lines.push(`Channel: ${agentChannelRef(channel.name, channel.type)}`);
+	if (channel.id) lines.push(`ID: ${channel.id}`);
+	lines.push(`Visibility: ${channelVisibility(channel)}`);
+	lines.push(`Joined: ${channel.joined ? "yes" : "no"}`);
+	if (channel.channelRole) lines.push(`Channel role: ${channel.channelRole}`);
+	if (channel.channelAdminBasis) lines.push(`Channel admin basis: ${channel.channelAdminBasis}`);
+	const callableCapabilities = Object.entries(channel.channelCapabilities ?? {}).filter(([, allowed]) => allowed).map(([capability]) => capability);
+	if (callableCapabilities.length > 0) lines.push(`Channel capabilities: ${callableCapabilities.join(", ")}`);
+	const muted = channelMuted(channel);
+	if (muted !== void 0) lines.push(`Muted: ${muted ? "yes" : "no"}`);
+	if (typeof channel.archived === "boolean") lines.push(`Archived: ${channel.archived ? "yes" : "no"}`);
+	lines.push(`Description: ${channel.description?.trim() || "(none)"}`);
+	if (memberCounts) {
+		const agents = memberCounts.agents ?? 0;
+		const humans = memberCounts.humans ?? 0;
+		lines.push(`Members: ${agents + humans} (${agents} agents, ${humans} humans)`);
+	}
+	lines.push("");
+	lines.push(`More: raft channel members "${agentChannelRef(channel.name, channel.type)}"`);
+	return `${lines.join("\n")}\n`;
+}
 /** Compact server summary. */
 function formatAgentServerSummary(data) {
 	const channels = data.channels ?? [];
@@ -12862,6 +12972,23 @@ function formatAgentServerHumans(humans, page) {
 	}
 	return `${lines.join("\n")}${formatPageFooter(page)}`;
 }
+/** Narrow visible facts for one user/agent. */
+function formatAgentUserInfo(user, memberships, page, skippedChannels = 0) {
+	const name = user.value.name;
+	const role = roleLabel(user.value.role);
+	const lines = ["## User", ""];
+	lines.push(`User: @${name}`);
+	lines.push(`Kind: ${user.kind}`);
+	if (user.kind === "agent") lines.push(`Status: ${agentStatusLabel(user.value)}`);
+	if (role) lines.push(`Role: ${role.slice(2, -1)}`);
+	if (user.value.description) lines.push(`Description: ${user.value.description}`);
+	lines.push("");
+	lines.push("### Visible Channel Memberships");
+	if (memberships.length === 0) lines.push("(none found in inspected visible channels)");
+	else for (const channel of memberships) lines.push(`${agentChannelRef(channel.name, channel.type)} [${channelStatus(channel)}]`);
+	if (skippedChannels > 0) lines.push(`Skipped ${skippedChannels} visible channel roster checks because the server rejected them.`);
+	return `${lines.join("\n")}${formatPageFooter(page)}`;
+}
 /** Channel membership with server-role labels. */
 function formatAgentChannelMembers(data) {
 	let text = "## Channel Members\n\n";
@@ -13252,6 +13379,41 @@ async function unfollowThread(client, request) {
 		text: `Unfollowed ${request.target}. Ordinary delivery from this thread stops; a direct @mention reactivates the follow.`
 	};
 }
+const channelInfoRequestSchema = requestSchema()(object({ target: string().describe("A regular channel, `#channel-name` (the `#` may be omitted). DMs and threads are not accepted.") }));
+/**
+* `raft channel info <target>`: the channel's facts from `server.info`, plus
+* member counts from its roster when the Server shows it.
+*/
+async function channelInfo(client, request) {
+	const invalid = validateOpRequest(channelInfoRequestSchema, request);
+	if (invalid) return invalid;
+	const trimmed = request.target.trim();
+	const input = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+	const name = parseRaftRegularChannelTarget$1(input);
+	if (!name) return failureOutcome(opError("INVALID_REQUEST", { message: "Target must be a regular channel name, e.g. '#engineering' or 'engineering'. DMs and thread targets are not supported." }));
+	const info = await client.server.info();
+	if (!info.ok) return failureFromClientResult(info);
+	const channel = info.data.channels.find((candidate) => candidate.name === name);
+	if (!channel) return failureOutcome(opError("NOT_FOUND", {
+		message: `Channel not found or not visible: ${input}`,
+		nextAction: "Run `raft server info --channels --query <name>` to inspect visible channels, or ask a channel member to add you if this is private."
+	}));
+	const members = await client.channels.members({ channel: `#${name}` });
+	const memberCounts = members.ok ? {
+		agents: members.data.agents?.length ?? 0,
+		humans: members.data.humans?.length ?? 0
+	} : null;
+	return {
+		ok: true,
+		state: "info",
+		data: {
+			channel,
+			memberCounts
+		},
+		next: null,
+		text: formatAgentChannelInfo(channel, memberCounts)
+	};
+}
 //#endregion
 //#region ../shared/src/agentOps/server.ts
 const serverInfoRequestSchema = requestSchema()(object({
@@ -13375,6 +13537,85 @@ async function updateProfile(client, request, options = {}) {
 		text: formatAgentProfile(result.data, 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).")
+}));
+/**
+* `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).
+*/
+async function userInfo(client, request) {
+	const invalid = validateOpRequest(userInfoRequestSchema, request);
+	if (invalid) return invalid;
+	const trimmed = request.name.trim();
+	const name = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+	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", {
+		message: `User not found or not visible: @${name}`,
+		nextAction: "Run `raft server info --agents --query <name>` or `raft server info --humans --query <name>` 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({
+			...channel,
+			joined: true,
+			muted: void 0,
+			activityMuted: void 0
+		});
+	}
+	const nextOffset = offset + limit;
+	const page = {
+		total: visibleChannels.length,
+		offset,
+		limit,
+		nextCommand: nextOffset < visibleChannels.length ? `raft user info @${name} --offset ${nextOffset} --limit ${limit}` : void 0
+	};
+	const next = page.nextCommand ? {
+		kind: "next_page",
+		command: page.nextCommand,
+		args: {
+			name: `@${name}`,
+			offset: nextOffset,
+			limit
+		},
+		why: "Only one page of visible channels was inspected for memberships."
+	} : null;
+	return {
+		ok: true,
+		state: "info",
+		data: {
+			user,
+			memberships,
+			skippedChannels,
+			page
+		},
+		next,
+		text: formatAgentUserInfo(user, memberships, page, skippedChannels)
+	};
+}
 //#endregion
 //#region ../shared/src/agentText/attachments.ts
 /** Upload receipt with attachment id and send-usage hint. */
@@ -14481,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,
@@ -14946,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
 	},
@@ -14999,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
 	},
@@ -15055,6 +15304,17 @@ const OPERATION_DEFS = [
 			boundBy: []
 		}
 	},
+	{
+		name: "tasks.show",
+		description: "One task's current status, title, and description. Finds done and closed tasks too.",
+		schema: taskRefSchema,
+		routes: ["taskList"],
+		consumes: nothing,
+		output: {
+			mayBeLarge: true,
+			boundBy: []
+		}
+	},
 	{
 		name: "tasks.convert",
 		description: "Turn a top-level message into an unassigned task.",
@@ -15114,6 +15374,14 @@ const OPERATION_DEFS = [
 			boundBy: []
 		}
 	},
+	{
+		name: "channels.info",
+		description: "A regular channel's facts: visibility, whether you joined it, your role and mute state, description, and member counts.",
+		schema: channelInfoRequestSchema,
+		routes: ["serverInfo", "channelMembers"],
+		consumes: nothing,
+		output: small
+	},
 	{
 		name: "threads.list",
 		description: "The threads you follow.",
@@ -15148,6 +15416,17 @@ 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"],
+		consumes: nothing,
+		output: {
+			mayBeLarge: true,
+			boundBy: ["offset", "limit"]
+		}
+	},
 	{
 		name: "profile.show",
 		description: "Show your profile, or someone else's by @handle.",
@@ -15393,6 +15672,7 @@ function createRaft(options) {
 			updateStatus: (request) => updateTaskStatus(api, request),
 			amend: (request) => amendTask(api, request),
 			history: (request) => taskHistory(api, request),
+			show: (request) => showTask(api, request),
 			convert: (request) => convertMessageToTask(api, request),
 			delete: (request) => deleteTask(api, request)
 		},
@@ -15401,13 +15681,15 @@ function createRaft(options) {
 			leave: (request) => leaveChannel(api, request),
 			mute: (request) => muteChannel(api, request),
 			unmute: (request) => unmuteChannel(api, request),
-			members: (request) => channelMembers(api, request)
+			members: (request) => channelMembers(api, request),
+			info: (request) => channelInfo(api, request)
 		},
 		threads: {
 			list: () => listThreads(api),
 			unfollow: (request) => unfollowThread(api, request)
 		},
 		server: { info: (request) => serverInfo(api, request) },
+		users: { info: (request) => userInfo(api, request) },
 		profile: {
 			show: (request) => showProfile(api, request),
 			update: (request) => updateProfile(api, request)
@@ -15475,6 +15757,7 @@ function createRaft(options) {
 		"tasks.updateStatus": (args) => raft.tasks.updateStatus(args),
 		"tasks.amend": (args) => raft.tasks.amend(args),
 		"tasks.history": (args) => raft.tasks.history(args),
+		"tasks.show": (args) => raft.tasks.show(args),
 		"tasks.convert": (args) => raft.tasks.convert(args),
 		"tasks.delete": (args) => raft.tasks.delete(args),
 		"channels.join": (args) => raft.channels.join(args),
@@ -15482,9 +15765,11 @@ function createRaft(options) {
 		"channels.mute": (args) => raft.channels.mute(args),
 		"channels.unmute": (args) => raft.channels.unmute(args),
 		"channels.members": (args) => raft.channels.members(args),
+		"channels.info": (args) => raft.channels.info(args),
 		"threads.list": () => raft.threads.list(),
 		"threads.unfollow": (args) => raft.threads.unfollow(args),
 		"server.info": (args) => raft.server.info(args),
+		"users.info": (args) => raft.users.info(args),
 		"profile.show": (args) => raft.profile.show(args),
 		"profile.update": (args) => raft.profile.update(args)
 	};
@@ -15545,6 +15830,7 @@ exports.amendTaskRequestSchema = amendTaskRequestSchema;
 exports.assignTaskRequestSchema = assignTaskRequestSchema;
 exports.attachmentCommentsRequestSchema = attachmentCommentsRequestSchema;
 exports.bootstrapRaftCredential = bootstrapRaftCredential;
+exports.channelInfoRequestSchema = channelInfoRequestSchema;
 exports.channelMembersRequestSchema = channelMembersRequestSchema;
 exports.channelTargetRequestSchema = channelTargetRequestSchema;
 exports.checkInboxRequestSchema = checkInboxRequestSchema;
@@ -15592,5 +15878,6 @@ exports.taskRefSchema = taskRefSchema;
 exports.unfollowThreadRequestSchema = unfollowThreadRequestSchema;
 exports.updateProfileRequestSchema = updateProfileRequestSchema;
 exports.updateTaskStatusRequestSchema = updateTaskStatusRequestSchema;
+exports.userInfoRequestSchema = userInfoRequestSchema;
 exports.verifyInboxNotice = verifyInboxNotice;
 exports.whoamiRequestSchema = whoamiRequestSchema;