@botiverse/raft-sdk 1.0.0-alpha.1 → 1.0.0-alpha.4

package/dist/cjs/index.cjs

@@ -11044,13 +11044,17 @@ var SeenFrontier = class SeenFrontier {
 	aliases = /* @__PURE__ */ new Map();
 	static fromSnapshot(snapshot) {
 		const frontier = new SeenFrontier();
-		if (!snapshot || snapshot.version !== 1) return frontier;
+		frontier.absorb(snapshot);
+		return frontier;
+	}
+	/** Merge a snapshot into this frontier by the same monotonic rules (never lowers a mark). */
+	absorb(snapshot) {
+		if (!snapshot || snapshot.version !== 1) return;
+		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) this.recordAlias(alias, canonical);
 		for (const [target, state] of Object.entries(snapshot.targets ?? {})) {
-			if (positiveInt(state.upTo)) frontier.recordUpTo(target, state.upTo);
-			if (Array.isArray(state.exact)) frontier.recordExact(target, state.exact);
+			if (positiveInt(state.upTo)) this.recordUpTo(target, state.upTo);
+			if (Array.isArray(state.exact)) this.recordExact(target, state.exact);
 		}
-		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) frontier.recordAlias(alias, canonical);
-		return frontier;
 	}
 	/** Remember that the Server resolved `requested` to `canonical` (a thread spelling, a `~agent` suffix, …). */
 	recordAlias(requested, canonical) {
@@ -11197,7 +11201,7 @@ async function checkInbox(client, request = {}, frontier) {
 * return value summarises the drain; the batch that ends the iteration is
 * acknowledged only by the caller's next pull (`summary.cursor`).
 */
-async function* drainInbox(client, request = {}, frontier) {
+async function* drainInbox(client, request = {}, frontier, onPull) {
 	const ack = request.ack ?? "cursor";
 	let cursor = request.since ?? null;
 	let ackMode = ack;
@@ -11220,6 +11224,7 @@ async function* drainInbox(client, request = {}, frontier) {
 			error: round
 		};
 		const batch = round.data;
+		await onPull?.(sent, batch);
 		ackMode = batch.ackMode;
 		stillUnread = batch.stillUnreadConversations;
 		if (batch.messages.length > 0) {
@@ -11528,12 +11533,173 @@ async function sendMessage(client, request, frontier, internal = {}) {
 	if (data.state === "sent") return sentOutcome(request.target, data);
 	return failureOutcome(opError("INVALID_RESPONSE", { message: `Unexpected send state "${data.state}".` }));
 }
-/** Reply where a received message came from. */
-function replyTo(client, message, request, frontier) {
-	return sendMessage(client, {
-		...request,
-		target: message.target
-	}, frontier);
+function taskTimestamps(t) {
+	return `${t.createdAt ? ` created=${formatUtcTimestamp(t.createdAt)}` : ""}${t.updatedAt ? ` updated=${formatUtcTimestamp(t.updatedAt)}` : ""}`;
+}
+const TASK_STATUS_ORDER = [
+	"todo",
+	"in_progress",
+	"in_review",
+	"done",
+	"closed"
+];
+function oneLineTaskTitle(title) {
+	return (title ?? "").replace(/\s+/g, " ").trim();
+}
+/** Channel task board listing. */
+function formatAgentTaskList(channel, data, statusFilter) {
+	if (!data.tasks || data.tasks.length === 0) return `No${statusFilter && statusFilter !== "all" ? ` ${statusFilter}` : ""} tasks in ${channel}.`;
+	const formatted = data.tasks.map((t) => {
+		const assignee = t.claimedById ? ` → ${t.claimedByName ? `@${t.claimedByName}` : "<unresolved>"}` : "";
+		const departedCreator = t.createdByMembershipStatus === "left" || t.createdByMembershipStatus === "removed";
+		const creator = t.createdByName ? ` (by @${t.createdByName}${departedCreator ? " [departed]" : ""})` : "";
+		const msgId = t.messageId ? ` msg=${t.messageId.slice(0, 8)}` : "";
+		const revision = Number.isInteger(t.revision) ? ` rev=${t.revision}` : "";
+		const legacy = t.isLegacy ? " [LEGACY — read-only]" : "";
+		const resourceReceipt = t.requiresResourceReceipt ? ` resource-receipt=${t.resourceReceiptRecordedAt ? "recorded" : "pending"}` : "";
+		const details = t.description ? `\n  Current description: ${t.description.replace(/\n/g, `\n${" ".repeat(23)}`)}` : "";
+		return `#${t.taskNumber} [${t.status}]${assignee}${creator}${msgId}${revision}${resourceReceipt}${taskTimestamps(t)}${legacy} Current title: ${oneLineTaskTitle(t.title)}${details}`;
+	}).join("\n");
+	return `## Task Board for ${channel} (${data.tasks.length} tasks)\n\n${formatted}`;
+}
+/** Cross-channel --mine task listing with coverage notes. */
+function formatAgentMyTaskList(data, statusFilter) {
+	const tasks = data.tasks ?? [];
+	const visibleTypes = data.coverage?.visibleChannelTypes?.join("|") ?? "unknown";
+	const archived = data.coverage?.includesArchived ? "included" : "not included";
+	const coverage = [
+		`Coverage: ${data.coverage?.status ?? "unknown"}`,
+		`visible types=${visibleTypes}`,
+		`archived=${archived}`,
+		`inaccessible scope=${data.coverage?.inaccessibleScope ?? "unknown"}`
+	].join(" · ");
+	const output = `Output: showing ${tasks.length} of ${tasks.length} visible matches · mode=${data.pagination?.mode ?? "unknown"} · truncated=${String(data.pagination?.truncated ?? "unknown")}`;
+	const title = `## My assigned tasks on this server${statusFilter ? ` (status=${statusFilter})` : " (unfinished)"}`;
+	if (tasks.length === 0) return [
+		title,
+		"",
+		coverage,
+		output,
+		"",
+		"No tasks matched in the covered visible scope."
+	].join("\n");
+	const grouped = /* @__PURE__ */ new Map();
+	for (const task of tasks) {
+		const status = task.status ?? "unknown";
+		const bucket = grouped.get(status) ?? [];
+		bucket.push(task);
+		grouped.set(status, bucket);
+	}
+	return [
+		title,
+		"",
+		coverage,
+		output,
+		"",
+		...[...TASK_STATUS_ORDER.filter((status) => grouped.has(status)), ...[...grouped.keys()].filter((status) => !TASK_STATUS_ORDER.includes(status)).sort()].map((status) => {
+			const rows = grouped.get(status);
+			const rendered = rows.map((task) => {
+				const channelRef = task.channelRef ?? "<unresolved-visible-target>";
+				const taskNumber = task.taskNumber ?? "?";
+				const departedCreator = task.createdByMembershipStatus === "left" || task.createdByMembershipStatus === "removed";
+				const creator = task.createdByName ? ` by=@${task.createdByName}${departedCreator ? " creator=departed" : ""}` : "";
+				const message = task.messageId ? ` msg=${task.messageId.slice(0, 8)}` : "";
+				const legacy = task.isLegacy ? " legacy=read-only" : "";
+				return `- ${channelRef} task #${taskNumber} [${status}]${creator}${message}${task.requiresResourceReceipt ? ` resource-receipt=${task.resourceReceiptRecordedAt ? "recorded" : "pending"}` : ""}${taskTimestamps(task)}${legacy} Current title: ${oneLineTaskTitle(task.title)}`.trimEnd();
+			});
+			return [`### ${status} (${rows.length})`, ...rendered].join("\n");
+		})
+	].join("\n");
+}
+/** Receipt for task create. */
+function formatAgentTasksCreated(channel, data) {
+	const created = data.tasks.map((t) => {
+		const assignee = t.claimedById ? t.claimedByName ? `@${t.claimedByName}` : "<unresolved>" : "unassigned";
+		const resourceReceipt = t.requiresResourceReceipt ? " resource-receipt=pending" : "";
+		return `#${t.taskNumber} [${t.status}] assignee=${assignee} claimedAt=${t.claimedAt ?? "null"} msg=${t.messageId.slice(0, 8)}${resourceReceipt} "${t.title}"`;
+	}).join("\n");
+	const threadHints = data.tasks.map((t) => `#${t.taskNumber} → raft message send --target "${channel}:${t.messageId.slice(0, 8)}"`).join("\n");
+	const receipt = data.assignmentReceipt ? `\n\nAssignment receipt (msg=${data.assignmentReceipt.messageId.slice(0, 8)}):\n${data.assignmentReceipt.content}` : "";
+	return `Created ${data.tasks.length} task(s) in ${channel}:\n${created}${receipt}\n\nTo follow up in each task's thread:\n${threadHints}`;
+}
+const BLOCKED_ACTION_COPY = { start_conflicting_execution: "starting conflicting implementation/change work" };
+function formatClaimConflict(label, conflict) {
+	const holder = conflict.currentAssignee?.name ? `@${conflict.currentAssignee.name}` : "another actor";
+	const blocked = conflict.blockedActions.map((action) => BLOCKED_ACTION_COPY[action] ?? action).join("; ");
+	const examples = conflict.unblockedActionExamples.join(" · ");
+	return [
+		`${label}: Claim failed — ${holder} currently holds the implementation lock (assignment state as of ${conflict.observedAt}).`,
+		`  Blocked: ${blocked}.`,
+		`  Not blocked by this claim conflict (each still subject to its own authority/policy): ${examples}.`,
+		`  This is not a ruling on who owns or leads this lane. If you are its canonical owner or believe it is misrouted: correct the routing in the original thread, or file request_reassign (a request — it does not itself reassign).`
+	].join("\n");
+}
+function canonicalAgentTaskTarget(target) {
+	return target.replace(/^dm:user:/i, "dm:@");
+}
+function agentTaskThreadTarget(target, messageId) {
+	return `${canonicalAgentTaskTarget(target)}:${messageId.slice(0, 8)}`;
+}
+/** Claim results incl. concurrency-lock guidance on failed claims. */
+function formatAgentClaimResults(channel, data) {
+	const lines = data.results.map((r) => {
+		const label = r.taskNumber ? `#${r.taskNumber}` : `msg:${r.messageId}`;
+		if (r.success) return `${label} (msg:${r.messageId ? r.messageId.slice(0, 8) : ""}): claimed`;
+		if (r.reason === "already claimed by you") return `${label}: already claimed by you.`;
+		if (r.conflict?.kind === "claim_conflict") return formatClaimConflict(label, r.conflict);
+		return `${label}: FAILED — ${r.reason || "already claimed"}. Do not start conflicting execution on this task or take over its scope without a redirect; a failed claim is a concurrency lock, not a ruling on lane ownership.`;
+	});
+	const succeeded = data.results.filter((r) => r.success).length;
+	const failed = data.results.length - succeeded;
+	let summary = `${succeeded} claimed`;
+	if (failed > 0) summary += `, ${failed} failed`;
+	const claimedMsgs = data.results.filter((r) => r.success && r.messageId).map((r) => `#${r.taskNumber} → raft message send --target "${agentTaskThreadTarget(channel, r.messageId)}"`).join("\n");
+	const threadHint = claimedMsgs ? `\n\nFollow up in each task's thread:\n${claimedMsgs}` : "";
+	return `Claim results (${summary}):\n${lines.join("\n")}${threadHint}`;
+}
+function formatAgentTaskUnclaimed(taskNumber) {
+	return `#${taskNumber} unclaimed — now open.`;
+}
+function formatAgentTaskAssigned(taskNumber, assignee) {
+	return assignee ? `#${taskNumber} assigned to ${assignee}.` : `#${taskNumber} unassigned — now open.`;
+}
+function formatAgentTaskStatusUpdated(taskNumber, status) {
+	return `#${taskNumber} moved to ${status}.`;
+}
+function formatAgentTaskDeleted(taskNumber) {
+	return `#${taskNumber} deleted.`;
+}
+/** Message→task conversion receipt. */
+function formatAgentTaskConverted(channel, task) {
+	const target = `${canonicalAgentTaskTarget(channel)}:${task.messageId.slice(0, 8)}`;
+	return [
+		`Converted msg=${task.messageId.slice(0, 8)} to task #${task.taskNumber} [${task.status}] assignee=unassigned "${task.title}"`,
+		"",
+		`To follow up in the task's thread:`,
+		`raft message send --target "${target}"`
+	].join("\n");
+}
+function formatAgentTaskAmended(data) {
+	const details = data.task.description === null ? "details: <none>" : `details:\n${data.task.description.split("\n").map((line) => `  ${line}`).join("\n")}`;
+	return [
+		`#${data.task.taskNumber} amended — revision ${data.task.revision}, event seq ${data.event.seq}.`,
+		`title: ${data.task.title}`,
+		details
+	].join("\n");
+}
+function formatAgentTaskHistory(data) {
+	const description = data.task.description === null ? "(none set)" : data.task.description.replace(/\n/g, `\n${" ".repeat(21)}`);
+	const header = [
+		`## Task #${data.task.taskNumber} history — revision ${data.task.revision}`,
+		"",
+		`Current title: ${data.task.title.replace(/\s+/g, " ").trim()}`,
+		`Current description: ${description}`
+	].join("\n");
+	if (data.events.length === 0) return `${header}\n\nNo recorded events.`;
+	return `${header}\n\n${data.events.map((event) => {
+		const actor = event.actorType === "system" ? "@system" : event.actorName ? `@${event.actorName}` : "<unresolved>";
+		return `seq=${event.seq} time=${event.createdAt} actor=${actor} type=${event.eventType}\n  ${JSON.stringify(event.payload)}`;
+	}).join("\n")}`;
 }
 //#endregion
 //#region ../shared/src/agentOps/tasks.ts
@@ -11547,12 +11713,12 @@ function rowState(result) {
 function claimNext(claim) {
 	const first = claim.rows.find((row) => row.mayWork);
 	if (first) {
-		const suffix = first.messageId ? first.messageId.slice(0, 8) : null;
+		const thread = first.messageId ? agentTaskThreadTarget(claim.target, first.messageId) : null;
 		return {
 			kind: "start_work",
-			...suffix ? {
-				command: `raft message send --target "${claim.target}:${suffix}"`,
-				args: { thread: `${claim.target}:${suffix}` }
+			...thread ? {
+				command: `raft message send --target "${thread}"`,
+				args: { thread }
 			} : {},
 			why: "The claim is yours; post progress in the task's thread."
 		};
@@ -11563,20 +11729,7 @@ function claimNext(claim) {
 	};
 }
 function claimText(claim) {
-	const lines = claim.rows.map((row) => {
-		const label = row.taskNumber ? `#${row.taskNumber}` : `msg:${row.ref}`;
-		if (row.state === "claimed") return `${label}: claimed`;
-		if (row.state === "already_yours") return `${label}: already claimed by you`;
-		if (row.state === "conflict") return `${label}: held by ${row.holder?.name ? `@${row.holder.name}` : "another assignee"}`;
-		return `${label}: refused${row.reason ? ` (${row.reason})` : ""}`;
-	});
-	const head = `Claim results (${claim.rows.filter((row) => row.mayWork).length} of ${claim.rows.length} authorise work):`;
-	const next = claimNext(claim);
-	return [
-		head,
-		...lines,
-		next?.command ? `Follow up in the task's thread: ${next.command}` : next?.why ?? ""
-	].filter(Boolean).join("\n");
+	return formatAgentClaimResults(claim.target, { results: claim.rows.map((row) => row.raw) });
 }
 async function claimTasks(client, request) {
 	const numbers = (request.taskNumbers ?? []).filter((n) => Number.isInteger(n) && n > 0);
@@ -11620,7 +11773,8 @@ async function claimTasks(client, request) {
 			mayWork: state === "claimed" || state === "already_yours",
 			reason: row.reason ?? null,
 			holder: row.conflict?.currentAssignee ?? null,
-			conflict: row.conflict ?? null
+			conflict: row.conflict ?? null,
+			raw: row
 		};
 	});
 	const claim = {
@@ -11636,6 +11790,235 @@ async function claimTasks(client, request) {
 		text: claimText(claim)
 	};
 }
+async function listTasks(client, request) {
+	const mine = request.mine === true;
+	if (mine === Boolean(request.target?.trim())) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass exactly one of a channel target or mine: true." }));
+	const result = await client.tasks.list({
+		...mine ? { mine: "true" } : { channel: request.target },
+		...request.status ? { status: request.status } : {}
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	const board = {
+		scope: mine ? "mine" : "channel",
+		target: mine ? null : request.target,
+		tasks: data.tasks,
+		coverage: data.coverage ?? null
+	};
+	const text = mine ? formatAgentMyTaskList(data, request.status) : formatAgentTaskList(request.target, data, request.status);
+	const open = board.tasks.find((t) => t.status === "todo" && !t.claimedByName);
+	const next = open?.taskNumber && board.target ? {
+		kind: "claim_task",
+		command: `raft task claim --target "${board.target}" --number ${open.taskNumber}`,
+		args: {
+			target: board.target,
+			taskNumbers: [open.taskNumber]
+		},
+		why: "An unassigned todo task is open; claim it before working on it."
+	} : null;
+	return {
+		ok: true,
+		state: board.tasks.length > 0 ? "board" : "empty",
+		data: board,
+		next,
+		text
+	};
+}
+async function createTasks(client, request) {
+	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 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 } : {}
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	const first = data.tasks[0];
+	return {
+		ok: true,
+		state: "created",
+		data: {
+			...data,
+			target: request.target
+		},
+		next: first ? {
+			kind: "post_in_task_thread",
+			command: `raft message send --target "${agentTaskThreadTarget(request.target, first.messageId)}"`,
+			args: { thread: agentTaskThreadTarget(request.target, first.messageId) },
+			why: "Follow up in each task's thread."
+		} : null,
+		text: formatAgentTasksCreated(request.target, data)
+	};
+}
+function requireTaskRef(request) {
+	if (!request.target?.trim() || !Number.isInteger(request.taskNumber) || request.taskNumber <= 0) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and a positive task number are required." }));
+	return null;
+}
+async function unclaimTask(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const result = await client.tasks.unclaim({
+		channel: request.target,
+		task_number: request.taskNumber
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "unclaimed",
+		data: request,
+		next: null,
+		text: formatAgentTaskUnclaimed(request.taskNumber)
+	};
+}
+async function assignTask(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const result = await client.tasks.assign({
+		channel: request.target,
+		task_number: request.taskNumber,
+		assignee: request.assignee,
+		...request.expectedRevision === void 0 ? {} : { expected_revision: request.expectedRevision }
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const assignee = result.data.assignee;
+	return {
+		ok: true,
+		state: assignee ? "assigned" : "unassigned",
+		data: {
+			target: request.target,
+			taskNumber: request.taskNumber,
+			assignee,
+			revision: result.data.revision
+		},
+		next: null,
+		text: formatAgentTaskAssigned(request.taskNumber, assignee)
+	};
+}
+function heldTaskWrite(request, data, action, kind) {
+	const { idempotencyKey: _k, continuation: _c, ...base } = projectHeld(request.target, data, "");
+	const held = {
+		...base,
+		request
+	};
+	return {
+		ok: true,
+		state: "held",
+		data: held,
+		next: {
+			kind,
+			command: `raft message read --target "${request.target}"`,
+			args: { ...request },
+			why: `Unread messages in this channel may change the task; read them (frontier.recordHeld(held) once the model saw them), then repeat with these args if it is still right.`
+		},
+		text: `Held — ${held.newMessageCount} unread ${held.newMessageCount === 1 ? "message" : "messages"} in ${request.target}. ${action}\nRead them with: raft message read --target "${request.target}"\nAfter reviewing, repeat the operation if it is still correct.`
+	};
+}
+async function updateTaskStatus(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const result = await client.tasks.updateStatus({
+		channel: request.target,
+		task_number: request.taskNumber,
+		status: request.status
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	if (isHeldResponse(result.data)) return heldTaskWrite(request, result.data, "The status change was not applied.", "retry_update_status");
+	return {
+		ok: true,
+		state: "updated",
+		data: request,
+		next: request.status === "in_review" ? {
+			kind: "await_review",
+			why: "A human validates the work; set done after approval."
+		} : null,
+		text: formatAgentTaskStatusUpdated(request.taskNumber, request.status)
+	};
+}
+async function amendTask(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	if (request.title === void 0 && request.description === void 0) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass a new title, a new description, or description: null to clear it." }));
+	const result = await client.tasks.amend({
+		channel: request.target,
+		task_number: request.taskNumber,
+		...request.title === void 0 ? {} : { title: request.title },
+		...request.description === void 0 ? {} : { description: request.description }
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	if (isHeldResponse(result.data)) return heldTaskWrite(request, result.data, "The amendment was not applied.", "retry_amend");
+	return {
+		ok: true,
+		state: "amended",
+		data: {
+			...result.data,
+			target: request.target
+		},
+		next: null,
+		text: formatAgentTaskAmended(result.data)
+	};
+}
+async function taskHistory(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const result = await client.tasks.history({
+		channel: request.target,
+		task_number: request.taskNumber
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "history",
+		data: {
+			...result.data,
+			target: request.target
+		},
+		next: null,
+		text: formatAgentTaskHistory(result.data)
+	};
+}
+async function convertMessageToTask(client, request) {
+	if (!request.target?.trim() || !request.messageId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and a message id are required." }));
+	const result = await client.tasks.convert({
+		channel: request.target,
+		message_id: request.messageId
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const task = result.data.task;
+	return {
+		ok: true,
+		state: "converted",
+		data: {
+			target: request.target,
+			task
+		},
+		next: {
+			kind: "post_in_task_thread",
+			command: `raft message send --target "${agentTaskThreadTarget(request.target, task.messageId)}"`,
+			args: { thread: agentTaskThreadTarget(request.target, task.messageId) },
+			why: "Follow up in the task's thread; it is unassigned until someone claims it."
+		},
+		text: formatAgentTaskConverted(request.target, task)
+	};
+}
+async function deleteTask(client, request) {
+	const invalid = requireTaskRef(request);
+	if (invalid) return invalid;
+	const result = await client.tasks.delete({
+		channel: request.target,
+		task_number: request.taskNumber
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "deleted",
+		data: request,
+		next: null,
+		text: formatAgentTaskDeleted(request.taskNumber)
+	};
+}
 //#endregion
 //#region ../shared/src/agentOps/wake.ts
 const RAFT_INBOX_NOTICE_SCHEMA = "raft-agent-inbox-notice.v1";
@@ -11803,11 +12186,1605 @@ async function unregisterWebhook(client) {
 	};
 }
 //#endregion
+//#region ../shared/src/agentText/server.ts
+function formatRuntimeContext(ctx) {
+	if (!ctx) return "";
+	const lines = ["### Current Runtime", "Authoritative context for this agent process. Do not infer computer identity from hostname or cwd when this section is present."];
+	if (ctx.agentId) lines.push(`- Agent ID: ${ctx.agentId}`);
+	if (ctx.runtime) lines.push(`- Runtime: ${ctx.runtime}`);
+	if (ctx.model) lines.push(`- Model: ${ctx.model}`);
+	if (ctx.reasoningEffort) lines.push(`- Reasoning: ${ctx.reasoningEffort}`);
+	if (ctx.serverId) lines.push(`- Server ID: ${ctx.serverId}`);
+	if (ctx.machineName || ctx.machineId) {
+		const label = ctx.machineName && ctx.machineId ? `${ctx.machineName} (${ctx.machineId})` : ctx.machineName || ctx.machineId;
+		lines.push(`- Computer: ${label}`);
+	}
+	if (ctx.machineDescription) lines.push(`- Computer Description: ${ctx.machineDescription}`);
+	if (ctx.machineHostname) lines.push(`- Hostname: ${ctx.machineHostname}`);
+	if (ctx.machineOs) lines.push(`- OS: ${ctx.machineOs}`);
+	if (ctx.daemonVersion) lines.push(`- Daemon: v${ctx.daemonVersion}`);
+	if (ctx.workspacePath) lines.push(`- Workspace: ${ctx.workspacePath}`);
+	return lines.length > 2 ? `${lines.join("\n")}\n\n` : "";
+}
+function roleLabel(role) {
+	return role && role !== "member" ? ` (${role})` : "";
+}
+function channelMemberRoleDetail(member) {
+	const details = [];
+	if (member.serverRole) details.push(`server role=${member.serverRole}`);
+	if (member.channelRole) details.push(`channel role=${member.channelRole}`);
+	if (member.channelAdminBasis) details.push(`admin via=${member.channelAdminBasis}`);
+	return details.length > 0 ? ` [${details.join(", ")}]` : "";
+}
+function agentStatusLabel(agent) {
+	const lifecycle = agent.status?.trim() || "unknown";
+	const activity = agent.activity?.trim();
+	if (!activity) return lifecycle;
+	const activityWithDetail = agent.activityDetail?.trim() ? `${activity}: ${agent.activityDetail.trim()}` : activity;
+	return activity === lifecycle ? lifecycle : `${lifecycle}; ${activityWithDetail}`;
+}
+function formatCurrentAgent(data) {
+	if (!data.serverRole) return "";
+	const lines = ["### Current Agent"];
+	lines.push(`- Role: ${data.serverRole}`);
+	return `${lines.join("\n")}\n\n`;
+}
+/** Server overview: runtime context, channels, agents, humans. */
+function formatAgentServerInfo(data) {
+	let text = "## Server\n\n";
+	const channels = data.channels ?? [];
+	const agents = data.agents ?? [];
+	const humans = data.humans ?? [];
+	text += formatRuntimeContext(data.runtimeContext);
+	text += formatCurrentAgent(data);
+	text += "### Channels\n";
+	text += "Visible public channels may appear even when `joined=false`. Private channels are shown only when you are a member; do not disclose private-channel names, membership, or content outside that channel. Use channel attention commands (`raft channel join`, `leave`, `mute`, `unmute`; `raft thread unfollow`) for your own delivery state. Existing channel management commands (`raft channel create`, `update`, `archive`, `unarchive`, `add-member`, `remove-member`) are authorized per channel; a channel-admin role never grants delete, visibility, federation, or server-profile actions. There is no Agent command for changing channel roles. Run any subcommand with `--help` for syntax.\n";
+	text += "Server-profile changes still use raft server update and remain server-role gated.\n";
+	text += "Mute state is shown when the server provides it; otherwise it is omitted.\n";
+	if (channels.length > 0) for (const t of channels) {
+		const statusParts = [t.type === "private" || t.type === "dm" ? "private" : "public", t.joined ? "joined" : "not joined"];
+		if (t.channelRole) statusParts.push(`channel role=${t.channelRole}`);
+		if (t.channelAdminBasis) statusParts.push(`admin via=${t.channelAdminBasis}`);
+		const muted = channelMuted(t);
+		if (muted !== void 0) statusParts.push(muted ? "muted" : "not muted");
+		const status = statusParts.join(", ");
+		const ref = agentChannelRef(t.name, t.type);
+		text += t.description ? `  - ${ref} [${status}] — ${t.description}\n` : `  - ${ref} [${status}]\n`;
+	}
+	else text += "  (none)\n";
+	text += "\n### Agents\n";
+	text += "Other AI agents in this server.\n";
+	text += "Role labels show server-level owner/admin authority; no role label means ordinary member.\n";
+	if (agents.length > 0) for (const a of agents) {
+		const role = roleLabel(a.role);
+		const status = agentStatusLabel(a);
+		text += a.description ? `  - @${a.name} (${status})${role} — ${a.description}\n` : `  - @${a.name} (${status})${role}\n`;
+	}
+	else text += "  (none)\n";
+	text += "\n### Humans\n";
+	text += "To start a new DM: raft message send --target \"dm:@name\" <<'RAFTMSG' followed by the message body and RAFTMSG. To reply in an existing DM: reuse the target from received messages.\n";
+	text += "Role labels show server-level owner/admin authority; no role label means ordinary member.\n";
+	if (humans.length > 0) for (const u of humans) {
+		const role = roleLabel(u.role);
+		text += u.description ? `  - @${u.name}${role} — ${u.description}\n` : `  - @${u.name}${role}\n`;
+	}
+	else text += "  (none)\n";
+	return text;
+}
+function agentChannelRef(name, type) {
+	if (type === "dm") return `dm:@${name}`;
+	return name.startsWith("#") ? name : `#${name}`;
+}
+function channelVisibility(channel) {
+	const type = channel.type?.trim();
+	return type === "private" || type === "dm" ? "private" : "public";
+}
+function channelMuted(channel) {
+	if (typeof channel.muted === "boolean") return channel.muted;
+	if (typeof channel.activityMuted === "boolean") return channel.activityMuted;
+}
+function channelStatus(channel) {
+	const parts = [channelVisibility(channel), channel.joined ? "joined" : "not joined"];
+	const muted = channelMuted(channel);
+	if (channel.channelRole) parts.push(`channel role=${channel.channelRole}`);
+	if (channel.channelAdminBasis) parts.push(`admin via=${channel.channelAdminBasis}`);
+	if (muted !== void 0) parts.push(muted ? "muted" : "not muted");
+	if (typeof channel.archived === "boolean") parts.push(channel.archived ? "archived" : "not archived");
+	return parts.join(", ");
+}
+function formatPageFooter(page) {
+	if (!page) return "";
+	const start = page.total === 0 ? 0 : Math.min(page.offset + 1, page.total);
+	const end = Math.min(page.offset + page.limit, page.total);
+	const lines = [`\nShowing ${start}-${end} of ${page.total}.`];
+	if (page.nextCommand && end < page.total) lines.push(`More: ${page.nextCommand}`);
+	return `${lines.join("\n")}\n`;
+}
+/** Compact server summary. */
+function formatAgentServerSummary(data) {
+	const channels = data.channels ?? [];
+	const agents = data.agents ?? [];
+	const humans = data.humans ?? [];
+	const joined = channels.filter((channel) => channel.joined).length;
+	return `${[
+		"## Server",
+		"",
+		`Channels: ${channels.length} visible (${joined} joined)`,
+		`Agents: ${agents.length}`,
+		`Humans: ${humans.length}`,
+		"",
+		"Narrow queries:",
+		"- raft server info --channels",
+		"- raft server info --agents",
+		"- raft server info --humans",
+		"- raft channel info <name>",
+		"- raft user info <name>",
+		"",
+		"Full dump: raft server info --full"
+	].join("\n")}\n`;
+}
+/** Channel listing page. */
+function formatAgentServerChannels(channels, page) {
+	const lines = [
+		"## Server Channels",
+		"",
+		"Private channels are shown only when this agent is a member. Do not disclose private-channel names or metadata outside that channel."
+	];
+	if (channels.length === 0) lines.push("(none)");
+	else for (const channel of channels) {
+		const description = channel.description?.trim();
+		lines.push(description ? `${agentChannelRef(channel.name, channel.type)} [${channelStatus(channel)}] — ${description}` : `${agentChannelRef(channel.name, channel.type)} [${channelStatus(channel)}]`);
+	}
+	return `${lines.join("\n")}${formatPageFooter(page)}`;
+}
+/** Agent listing page. */
+function formatAgentServerAgents(agents, page) {
+	const lines = [
+		"## Server Agents",
+		"",
+		"Role labels show server-level owner/admin authority; no role label means ordinary member."
+	];
+	if (agents.length === 0) lines.push("(none)");
+	else for (const agent of agents) {
+		const role = roleLabel(agent.role);
+		const status = agentStatusLabel(agent);
+		lines.push(agent.description ? `@${agent.name} (${status})${role} — ${agent.description}` : `@${agent.name} (${status})${role}`);
+	}
+	return `${lines.join("\n")}${formatPageFooter(page)}`;
+}
+/** Human listing page. */
+function formatAgentServerHumans(humans, page) {
+	const lines = [
+		"## Server Humans",
+		"",
+		"Role labels show server-level owner/admin authority; no role label means ordinary member."
+	];
+	if (humans.length === 0) lines.push("(none)");
+	else for (const human of humans) {
+		const role = roleLabel(human.role);
+		lines.push(human.description ? `@${human.name}${role} — ${human.description}` : `@${human.name}${role}`);
+	}
+	return `${lines.join("\n")}${formatPageFooter(page)}`;
+}
+/** Channel membership with server-role labels. */
+function formatAgentChannelMembers(data) {
+	let text = "## Channel Members\n\n";
+	const ref = data.channel?.ref ?? "(unknown)";
+	const type = data.channel?.type ? ` (${data.channel.type})` : "";
+	const agents = data.agents ?? [];
+	const humans = data.humans ?? [];
+	text += `Channel: ${ref}${type}\n`;
+	text += "Members means join/post authority for this surface.\n\n";
+	text += "### Agents\n";
+	text += "Server and stored channel roles are shown separately when available.\n";
+	if (agents.length > 0) for (const a of agents) {
+		const role = roleLabel(a.role);
+		const channelRole = channelMemberRoleDetail(a);
+		const status = agentStatusLabel(a);
+		text += a.description ? `  - @${a.name} (${status})${role}${channelRole} — ${a.description}\n` : `  - @${a.name} (${status})${role}${channelRole}\n`;
+	}
+	else text += "  (none)\n";
+	text += "\n### Humans\n";
+	text += "Server and stored channel roles are shown separately when available.\n";
+	if (humans.length > 0) for (const u of humans) {
+		const role = roleLabel(u.role);
+		const channelRole = channelMemberRoleDetail(u);
+		text += u.description ? `  - @${u.name}${role}${channelRole} — ${u.description}\n` : `  - @${u.name}${role}${channelRole}\n`;
+	}
+	else text += "  (none)\n";
+	return text;
+}
+//#endregion
+//#region ../shared/src/runtimeCatalog.ts
+const EXTERNAL_AGENT_RUNTIME_ID = "external";
+const EXTERNAL_AGENT_RUNTIME_DISPLAY_NAME = "External agent";
+function isExternalAgentRuntime(runtime) {
+	return runtime === EXTERNAL_AGENT_RUNTIME_ID;
+}
+const RUNTIMES = [
+	{
+		id: "claude",
+		displayName: "Claude Code",
+		abbreviation: "CC",
+		binary: "claude",
+		supported: true
+	},
+	{
+		id: "codex",
+		displayName: "Codex CLI",
+		abbreviation: "CX",
+		binary: "codex",
+		supported: true
+	},
+	{
+		id: "grok",
+		displayName: "Grok Build",
+		abbreviation: "GK",
+		binary: "grok",
+		supported: true
+	},
+	{
+		id: "builtin",
+		displayName: "Built-in Pi",
+		abbreviation: "BP",
+		binary: "",
+		supported: true
+	},
+	{
+		id: "antigravity",
+		displayName: "Antigravity CLI",
+		abbreviation: "AG",
+		binary: "agy",
+		supported: true,
+		deprecated: true
+	},
+	{
+		id: "kimi-sdk",
+		displayName: "Kimi Code",
+		abbreviation: "KC",
+		binary: "",
+		supported: true
+	},
+	{
+		id: "kimi",
+		displayName: "Kimi CLI",
+		abbreviation: "KL",
+		binary: "kimi",
+		supported: true,
+		deprecated: true
+	},
+	{
+		id: "copilot",
+		displayName: "Copilot CLI",
+		abbreviation: "CP",
+		binary: "copilot",
+		supported: true
+	},
+	{
+		id: "cursor",
+		displayName: "Cursor CLI",
+		abbreviation: "CU",
+		binary: "cursor-agent",
+		supported: true
+	},
+	{
+		id: "gemini",
+		displayName: "Gemini CLI",
+		abbreviation: "GM",
+		binary: "gemini",
+		supported: true,
+		deprecated: true
+	},
+	{
+		id: "opencode",
+		displayName: "OpenCode",
+		abbreviation: "OC",
+		binary: "opencode",
+		supported: true
+	},
+	{
+		id: "pi",
+		displayName: "Pi",
+		abbreviation: "PI",
+		binary: "pi",
+		supported: true
+	}
+];
+function isRuntimeDeprecated(runtimeId) {
+	return RUNTIMES.some((runtime) => runtime.id === runtimeId && Boolean(runtime.deprecated));
+}
+/** Map runtime ID → display name. Falls back to the ID itself. */
+function getRuntimeDisplayName(id) {
+	if (isExternalAgentRuntime(id)) return EXTERNAL_AGENT_RUNTIME_DISPLAY_NAME;
+	return RUNTIMES.find((r) => r.id === id)?.displayName ?? id;
+}
+//#endregion
+//#region ../shared/src/agentText/threadsProfile.ts
+/**
+* Runtime label for identity display in agent-facing output: product name plus
+* lifecycle status. Agent-facing text is English-only, so the suffix is literal
+* here; the web surface renders the same status from the i18n catalog.
+*/
+function agentRuntimeLabelWithStatus(runtimeId) {
+	const name = getRuntimeDisplayName(runtimeId);
+	return isRuntimeDeprecated(runtimeId) ? `${name} (deprecated)` : name;
+}
+function formatDoneSuffix(thread) {
+	return thread.doneAt ? `, doneAt=${thread.doneAt}` : "";
+}
+/** Followed thread list for the bound agent, including exact thread targets. */
+function formatAgentThreadList(threads) {
+	if (threads.length === 0) return "No followed threads.";
+	return [`Followed threads (${threads.length}):`, ...threads.map((thread) => `- ${thread.target} (${thread.threadChannelId}, parent=${thread.parentChannelRef}, followedAt=${thread.followedAt}, reason=${thread.reason}${formatDoneSuffix(thread)})`)].join("\n");
+}
+function formatCreatedAgents(createdAgents, runtimeLabel) {
+	if (createdAgents.length === 0) return ["- Created Agents: none"];
+	return [`- Created Agents (${createdAgents.length}):`, ...createdAgents.map((createdAgent) => `  - @${createdAgent.name} (${runtimeLabel(createdAgent.runtime)}, ${createdAgent.status})`)];
+}
+function formatHumanProfile(profile, runtimeLabel) {
+	const lines = [
+		"## Profile",
+		"",
+		"- Type: human",
+		`- Handle: @${profile.name}`,
+		`- Display Name: ${profile.displayName ?? "(none)"}`,
+		`- Description: ${profile.description ?? "(none)"}`,
+		`- Membership: ${profile.membershipStatus}`
+	];
+	if (profile.role) lines.push(`- Role: ${profile.role}`);
+	if (profile.joinedAt) lines.push(`- Joined: ${profile.joinedAt}`);
+	if (profile.email) lines.push(`- Email: ${profile.email}`);
+	return [...lines, ...formatCreatedAgents(profile.createdAgents, runtimeLabel)].join("\n");
+}
+function formatCreator(profile) {
+	if (!profile.creator) return null;
+	return profile.creator.displayName ? `${profile.creator.displayName} (@${profile.creator.name})` : `@${profile.creator.name}`;
+}
+function formatAgentProfileCard(profile, runtimeLabel) {
+	const lines = [
+		"## Profile",
+		"",
+		"- Type: agent",
+		`- Handle: @${profile.name}`,
+		`- Display Name: ${profile.displayName ?? "(none)"}`,
+		`- Description: ${profile.description ?? "(none)"}`,
+		`- Status: ${profile.status}`,
+		`- Role: ${profile.serverRole}`,
+		`- Runtime: ${runtimeLabel(profile.runtime)}`,
+		`- Model: ${profile.model}`,
+		`- Reasoning: ${profile.reasoningEffort ?? "medium"}`
+	];
+	if (profile.executionMode) lines.push(`- Execution: ${profile.executionMode}`);
+	if (profile.computerName || profile.computerId) {
+		const label = profile.computerName && profile.computerId ? `${profile.computerName} (${profile.computerId})` : profile.computerName ?? profile.computerId;
+		lines.push(`- Computer: ${label}`);
+	}
+	if (profile.computerHostname) lines.push(`- Hostname: ${profile.computerHostname}`);
+	if (profile.daemonVersion) lines.push(`- Daemon: v${profile.daemonVersion}`);
+	lines.push(`- Created: ${profile.createdAt}`);
+	if (profile.deletedAt) lines.push(`- Deleted At: ${profile.deletedAt}`);
+	const creator = formatCreator(profile);
+	if (creator) lines.push(`- Creator: ${creator}`);
+	return [...lines, ...formatCreatedAgents(profile.createdAgents, runtimeLabel)].join("\n");
+}
+/** Agent/human profile card. */
+function formatAgentProfile(profile, options = {}) {
+	const runtimeLabel = options.runtimeLabel ?? agentRuntimeLabelWithStatus;
+	return profile.kind === "human" ? formatHumanProfile(profile, runtimeLabel) : formatAgentProfileCard(profile, runtimeLabel);
+}
+//#endregion
+//#region ../shared/src/agentOps/channels.ts
+const INVALID_CHANNEL_TARGET = "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported.";
+async function resolveRegularChannel(client, target) {
+	const name = parseRaftRegularChannelTarget$1(target ?? "");
+	if (!name) return failureOutcome(opError("INVALID_REQUEST", { message: INVALID_CHANNEL_TARGET }));
+	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: ${target}`,
+		nextAction: "List visible channels with `raft server info --channels`; private channels need a human to add you."
+	}));
+	return {
+		id: channel.id,
+		name: channel.name,
+		joined: channel.joined
+	};
+}
+async function joinChannel(client, request) {
+	const result = await joinRaftChannelByTarget$1(client, { target: request.target });
+	if (!result.ok) {
+		const error = result.error;
+		if (error.kind === "validation") return error.reason === "target_not_found" ? failureOutcome(opError("NOT_FOUND", {
+			message: error.message,
+			nextAction: "Only visible public channels can be joined; private and joint channels need an invitation."
+		})) : failureOutcome(opError("INVALID_REQUEST", { message: error.message }));
+		if (error.kind === "http") return failureOutcome(opError("HTTP_ERROR", {
+			message: error.message,
+			status: error.status,
+			...error.errorCode ? { serverCode: error.errorCode } : {},
+			...error.suggestedNextAction ? { nextAction: error.suggestedNextAction } : {}
+		}));
+		return failureOutcome(opError("TRANSPORT_ERROR", { message: error.message }));
+	}
+	const state = result.data.state;
+	return {
+		ok: true,
+		state,
+		data: {
+			target: result.data.target,
+			channelId: result.data.channelId
+		},
+		next: {
+			kind: "read_target",
+			command: `raft message read --target "${result.data.target}"`,
+			args: { target: result.data.target },
+			why: "Read the channel before posting."
+		},
+		text: state === "joined" ? `Joined ${result.data.target}.` : `Already a member of ${result.data.target}.`
+	};
+}
+async function leaveChannel(client, request) {
+	const channel = await resolveRegularChannel(client, request.target);
+	if ("ok" in channel) return channel;
+	if (!channel.joined) return {
+		ok: true,
+		state: "not_joined",
+		data: {
+			target: request.target,
+			channelId: channel.id
+		},
+		next: null,
+		text: `You are not a member of ${request.target}; nothing to leave.`
+	};
+	const result = await client.channels.leave({ channelId: channel.id });
+	if (!result.ok) return failureFromClientResult(result);
+	const lines = [`Left ${request.target}. You can still inspect visible public channel history there, but you can no longer send or receive ordinary channel delivery until you join the public channel again or a human re-adds you to a private channel.`];
+	const attention = result.data.attention;
+	if (attention?.ordinaryActivity) lines.push(attention.ordinaryActivity);
+	return {
+		ok: true,
+		state: "left",
+		data: {
+			target: request.target,
+			channelId: channel.id
+		},
+		next: null,
+		text: lines.join("\n")
+	};
+}
+function formatSeq(value) {
+	return value == null ? "none" : String(value);
+}
+async function setChannelMute(client, request, action) {
+	const channel = await resolveRegularChannel(client, request.target);
+	if ("ok" in channel) return channel;
+	const result = action === "mute" ? await client.channels.mute({ channelId: channel.id }, {}) : await client.channels.unmute({ channelId: channel.id });
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	const lines = [
+		`${data.activityMuted ? "Muted" : "Unmuted"} ${request.target}.`,
+		`Activity muted: ${data.activityMuted ? "yes" : "no"}`,
+		`Mute from seq: ${formatSeq(data.muteFromSeq)}`
+	];
+	if (data.attention?.ordinaryActivity) lines.push(data.attention.ordinaryActivity);
+	if (data.attention?.stillArrives?.length) {
+		lines.push("Still arrives:");
+		for (const item of data.attention.stillArrives) lines.push(`- ${item}`);
+	}
+	if (data.attention?.threadBoundary) lines.push(data.attention.threadBoundary);
+	if (data.attention?.catchUp) lines.push(data.attention.catchUp);
+	if (data.attention?.unmuteCommand) lines.push(`To unmute: ${data.attention.unmuteCommand}`);
+	if (data.attention?.unmuteApi) lines.push(`Agent API: ${data.attention.unmuteApi}`);
+	if (data.attention?.muteCommand) lines.push(`To mute: ${data.attention.muteCommand}`);
+	if (data.attention?.muteApi) lines.push(`Agent API: ${data.attention.muteApi}`);
+	return {
+		ok: true,
+		state: data.activityMuted ? "muted" : "unmuted",
+		data: {
+			target: request.target,
+			channelId: channel.id,
+			activityMuted: data.activityMuted === true,
+			muteFromSeq: data.muteFromSeq ?? null,
+			stillArrives: data.attention?.stillArrives ?? []
+		},
+		next: null,
+		text: lines.join("\n")
+	};
+}
+function muteChannel(client, request) {
+	return setChannelMute(client, request, "mute");
+}
+function unmuteChannel(client, request) {
+	return setChannelMute(client, request, "unmute");
+}
+async function channelMembers(client, request) {
+	if (!request.target?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel, DM, or thread target is required." }));
+	const result = await client.channels.members({ channel: request.target });
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "members",
+		data: result.data,
+		next: null,
+		text: formatAgentChannelMembers(result.data)
+	};
+}
+async function listThreads(client) {
+	const result = await client.threads.list();
+	if (!result.ok) return failureFromClientResult(result);
+	const threads = result.data.threads;
+	return {
+		ok: true,
+		state: threads.length > 0 ? "threads" : "empty",
+		data: threads,
+		next: null,
+		text: formatAgentThreadList(threads)
+	};
+}
+async function unfollowThread(client, request) {
+	if (!request.target?.includes(":")) return failureOutcome(opError("INVALID_REQUEST", { message: "A thread target is required, for example '#channel:shortid' or 'dm:@peer:shortid'." }));
+	const result = await client.threads.unfollow({
+		thread: request.target,
+		...request.reason ? { reason: request.reason } : {}
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "unfollowed",
+		data: { target: request.target },
+		next: null,
+		text: `Unfollowed ${request.target}. Ordinary delivery from this thread stops; a direct @mention reactivates the follow.`
+	};
+}
+//#endregion
+//#region ../shared/src/agentOps/server.ts
+function nextCommand(section, request, offset, limit, total) {
+	const nextOffset = offset + limit;
+	if (nextOffset >= total) return void 0;
+	const parts = [
+		"raft server info",
+		`--${section}`,
+		`--offset ${nextOffset}`,
+		`--limit ${limit}`
+	];
+	if (section === "channels" && request.joined) parts.push("--joined");
+	return parts.join(" ");
+}
+async function serverInfo(client, request = {}) {
+	const result = await client.server.info();
+	if (!result.ok) return failureFromClientResult(result);
+	const server = result.data;
+	const view = request.view ?? "summary";
+	if (view === "summary") return {
+		ok: true,
+		state: "info",
+		data: {
+			view,
+			server,
+			page: null
+		},
+		next: {
+			kind: "list_channels",
+			command: "raft server info --channels",
+			why: "The summary only counts; list a section to see names."
+		},
+		text: formatAgentServerSummary(server)
+	};
+	if (view === "full") return {
+		ok: true,
+		state: "info",
+		data: {
+			view,
+			server,
+			page: null
+		},
+		next: null,
+		text: formatAgentServerInfo(server)
+	};
+	const limit = Math.max(1, Math.trunc(request.limit ?? 50));
+	const offset = Math.max(0, Math.trunc(request.offset ?? 0));
+	const rows = view === "channels" ? server.channels.filter((c) => !request.joined || c.joined) : view === "agents" ? server.agents : server.humans;
+	const pageRows = rows.slice(offset, offset + limit);
+	const page = {
+		section: view,
+		total: rows.length,
+		offset,
+		limit,
+		nextCommand: nextCommand(view, request, offset, limit, rows.length)
+	};
+	const text = view === "channels" ? formatAgentServerChannels(pageRows, page) : view === "agents" ? formatAgentServerAgents(pageRows, page) : formatAgentServerHumans(pageRows, page);
+	const next = page.nextCommand ? {
+		kind: "next_page",
+		command: page.nextCommand,
+		args: {
+			view,
+			offset: offset + limit,
+			limit
+		},
+		why: "More rows exist; one page is one page."
+	} : null;
+	return {
+		ok: true,
+		state: "info",
+		data: {
+			view,
+			server,
+			page
+		},
+		next,
+		text
+	};
+}
+async function showProfile(client, request = {}, options = {}) {
+	const result = await client.profile.show(request.target ? { target: request.target } : {});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "profile",
+		data: result.data,
+		next: null,
+		text: formatAgentProfile(result.data, options)
+	};
+}
+async function updateProfile(client, request, options = {}) {
+	if (request.displayName === void 0 && request.description === void 0 && request.avatarUrl === void 0) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass a displayName, description, or avatarUrl to update." }));
+	const result = await client.profile.update(request);
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "updated",
+		data: result.data,
+		next: null,
+		text: formatAgentProfile(result.data, options)
+	};
+}
+//#endregion
+//#region ../shared/src/agentText/attachments.ts
+/** Upload receipt with attachment id and send-usage hint. */
+function formatAgentAttachmentUploaded(attachment) {
+	return `File uploaded: ${attachment.filename} (${(attachment.sizeBytes / 1024).toFixed(1)}KB)\nAttachment ID: ${attachment.id}\n\nUse this ID with raft message send --attachment-id ${attachment.id} to include it in a message.\n`;
+}
+function anchorSummary(anchor) {
+	if (anchor.type === "md-section") {
+		const title = anchor.data.headingTitle ?? anchor.data.headingId;
+		return typeof title === "string" && title ? `§ ${title}` : "§ section";
+	}
+	if (anchor.type === "lines" || anchor.type === "csv-rows") {
+		const start = Number(anchor.data.start);
+		const end = Number(anchor.data.end ?? start);
+		if (!Number.isFinite(start)) return anchor.type;
+		const prefix = anchor.type === "lines" ? "L" : "rows ";
+		return start === (Number.isFinite(end) ? end : start) ? `${prefix}${start}` : `${prefix}${start}–${end}`;
+	}
+	if (anchor.type === "html-region") {
+		const quote = anchor.data.quote;
+		if (typeof quote === "string" && quote.trim().length > 0) {
+			const trimmed = quote.trim();
+			return trimmed.length > 60 ? `${trimmed.slice(0, 60)}…` : trimmed;
+		}
+		return "HTML region";
+	}
+	return anchor.type;
+}
+/** Attachment-scoped comment list incl. anchors/reactions, or its empty state. */
+function formatAgentAttachmentComments(attachmentId, comments, threadChannelId) {
+	if (comments.length === 0) return `No comments on attachment ${attachmentId.slice(0, 8)}.\n`;
+	const lines = [`## Comments on attachment ${attachmentId.slice(0, 8)} (${comments.length})`];
+	for (const c of comments) {
+		const check = c.reactions.some((r) => r.emoji === "✅") ? " ✅" : "";
+		const anchor = c.anchor ? ` [anchor: ${anchorSummary(c.anchor)}]` : "";
+		lines.push(`[msg=${c.id.slice(0, 8)} time=${c.createdAt} type=${c.senderType}]${check}${anchor} @${c.senderName}: ${c.content}`);
+	}
+	if (threadChannelId) lines.push(`(full conversation lives in thread channel ${threadChannelId})`);
+	return lines.join("\n") + "\n";
+}
+//#endregion
+//#region ../shared/src/agentOps/attachments.ts
+/** Compatibility fallback for Servers that predate the capability endpoint (the CLI's constant). */
+const AGENT_ATTACHMENT_UPLOAD_FALLBACK_MAX_BYTES = 52428800;
+const FILENAME_MIME_MAP = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".pdf": "application/pdf",
+	".txt": "text/plain",
+	".md": "text/markdown",
+	".json": "application/json",
+	".csv": "text/csv"
+};
+const MIME_TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+function sniffMimeType(bytes) {
+	const starts = (sig) => sig.every((b, i) => bytes[i] === b);
+	if (bytes.length >= 8 && starts([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) return "image/png";
+	if (bytes.length >= 3 && starts([
+		255,
+		216,
+		255
+	])) return "image/jpeg";
+	if (bytes.length >= 6) {
+		const header = String.fromCharCode(...bytes.subarray(0, 6));
+		if (header === "GIF87a" || header === "GIF89a") return "image/gif";
+	}
+	if (bytes.length >= 12 && String.fromCharCode(...bytes.subarray(0, 4)) === "RIFF" && String.fromCharCode(...bytes.subarray(8, 12)) === "WEBP") return "image/webp";
+	return null;
+}
+/** Explicit type wins; otherwise sniff the bytes, then the filename extension, then octet-stream. */
+function inferAttachmentMimeType(filename, bytes, explicit) {
+	const normalized = explicit?.trim().toLowerCase();
+	if (normalized && MIME_TYPE_RE.test(normalized)) return normalized;
+	const dot = filename.lastIndexOf(".");
+	const ext = dot >= 0 ? filename.slice(dot).toLowerCase() : "";
+	return sniffMimeType(bytes) ?? FILENAME_MIME_MAP[ext] ?? "application/octet-stream";
+}
+/**
+* Small-file multipart upload (`POST /upload`). Files at or above the Server's
+* direct-upload threshold need the upload-session routes (`routes.attachments.
+* createUploadSession` …), which this operation reports as `UNAVAILABLE` with a
+* next action rather than attempting silently.
+*/
+async function uploadAttachment(client, transport, request) {
+	if (!request.target?.trim() || !request.filename?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and a filename are required to upload." }));
+	if (!(request.bytes instanceof Uint8Array) || request.bytes.byteLength === 0) return failureOutcome(opError("INVALID_REQUEST", { message: "Refusing to upload a 0-byte attachment." }));
+	if (request.mimeType !== void 0 && !MIME_TYPE_RE.test(request.mimeType.trim())) return failureOutcome(opError("INVALID_REQUEST", { message: `mimeType must look like type/subtype, got: ${request.mimeType}` }));
+	const capability = await client.attachments.uploadCapabilities();
+	const maxBytes = capability.ok ? capability.data.maxBytes : AGENT_ATTACHMENT_UPLOAD_FALLBACK_MAX_BYTES;
+	const threshold = capability.ok && capability.data.directUploadEnabled ? capability.data.directUploadThresholdBytes : null;
+	if (request.bytes.byteLength > maxBytes) return failureOutcome(opError("INVALID_REQUEST", { message: `Attachment is ${request.bytes.byteLength} bytes; the Server's maximum is ${maxBytes}.` }));
+	if (threshold !== null && request.bytes.byteLength >= threshold) return failureOutcome(opError("UNAVAILABLE", {
+		message: `Files of ${threshold} bytes or more use the direct-upload session routes, which this operation does not drive yet.`,
+		nextAction: "Use routes.attachments.createUploadSession / completeUploadSession, or upload a smaller file.",
+		retryable: false
+	}));
+	const resolved = await client.channels.resolve({ target: request.target });
+	if (!resolved.ok) return failureFromClientResult(resolved);
+	const channelId = resolved.data.channelId;
+	const mimeType = inferAttachmentMimeType(request.filename, request.bytes, request.mimeType);
+	const copy = new Uint8Array(request.bytes.byteLength);
+	copy.set(request.bytes);
+	const form = new FormData();
+	form.append("file", new Blob([copy.buffer], { type: mimeType }), request.filename);
+	form.append("channelId", channelId);
+	if (request.mimeType) form.append("mimeType", mimeType);
+	const headers = new Headers(transport.headers);
+	headers.delete("content-type");
+	headers.set("accept", "application/json");
+	headers.set("authorization", transport.authorization);
+	let response;
+	try {
+		response = await transport.fetch(`${transport.serverUrl}${agentApiContract.attachmentUpload.fullPath}`, {
+			method: "POST",
+			headers,
+			body: form
+		});
+	} catch {
+		return failureOutcome(opError("TRANSPORT_ERROR"));
+	}
+	let body = null;
+	try {
+		body = await response.json();
+	} catch {
+		body = null;
+	}
+	if (!response.ok) {
+		const b = body && typeof body === "object" ? body : {};
+		return failureOutcome(opErrorFromClientError({
+			kind: "http",
+			reason: "http_error",
+			message: typeof b.error === "string" ? b.error : `HTTP ${response.status}`,
+			status: response.status,
+			errorCode: typeof b.errorCode === "string" ? b.errorCode : typeof b.code === "string" ? b.code : null,
+			suggestedNextAction: typeof b.suggestedNextAction === "string" ? b.suggestedNextAction : null
+		}));
+	}
+	const parsed = agentApiContract.attachmentUpload.response.body.safeParse(body);
+	if (!parsed.success) return failureOutcome(opError("INVALID_RESPONSE"));
+	const data = parsed.data;
+	return {
+		ok: true,
+		state: "uploaded",
+		data: {
+			...data,
+			target: request.target,
+			mimeType: data.mimeType ?? mimeType
+		},
+		next: {
+			kind: "send_with_attachment",
+			command: `raft message send --target "${request.target}" --attachment-id ${data.id}`,
+			args: {
+				target: request.target,
+				attachmentIds: [data.id]
+			},
+			why: "The upload alone posts nothing; send a message that links the attachment id."
+		},
+		text: formatAgentAttachmentUploaded(data)
+	};
+}
+async function downloadAttachment(client, request) {
+	if (!request.attachmentId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "An attachment id is required." }));
+	const result = await client.attachments.download({ attachmentId: request.attachmentId });
+	if (!result.ok) return failureFromClientResult(result);
+	const bytes = result.data;
+	return {
+		ok: true,
+		state: "downloaded",
+		data: {
+			attachmentId: request.attachmentId,
+			bytes
+		},
+		next: null,
+		text: `Downloaded attachment ${request.attachmentId.slice(0, 8)} (${bytes.byteLength} bytes).`
+	};
+}
+async function attachmentComments(client, request) {
+	if (!request.attachmentId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "An attachment id is required." }));
+	const result = await client.attachments.comments({ attachmentId: request.attachmentId }, request.limit === void 0 ? {} : { limit: String(request.limit) });
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	return {
+		ok: true,
+		state: data.comments.length > 0 ? "comments" : "empty",
+		data: {
+			...data,
+			attachmentId: request.attachmentId
+		},
+		next: null,
+		text: formatAgentAttachmentComments(request.attachmentId, data.comments, data.threadChannelId)
+	};
+}
+//#endregion
+//#region ../shared/src/agentText/search.ts
+/** Local wall-clock rendering with offset, as the CLI prints search hit times. */
+function formatLocalTimeWithOffset(iso) {
+	const d = new Date(iso);
+	if (isNaN(d.getTime())) return iso;
+	const pad = (n) => String(n).padStart(2, "0");
+	const offsetMinutes = -d.getTimezoneOffset();
+	const sign = offsetMinutes >= 0 ? "+" : "-";
+	const absOffset = Math.abs(offsetMinutes);
+	const offset = `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`;
+	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())} ${offset}`;
+}
+function renderSearchSource(result) {
+	if (result.channelType === "thread") {
+		const shortId = typeof result.channelName === "string" && result.channelName.startsWith("thread-") ? result.channelName.slice(7) : typeof result.threadId === "string" && result.threadId ? result.threadId.slice(0, 8) : result.channelName;
+		if (result.parentChannelType === "dm") return `dm:${neutralizeAgentRaftRefLiterals(result.parentChannelName ?? "unknown")}:${shortId}`;
+		return `thread:${neutralizeAgentRaftRefLiterals(result.parentChannelName ?? "unknown")}:${shortId}`;
+	}
+	if (result.channelType === "dm") return `dm:${neutralizeAgentRaftRefLiterals(result.channelName ?? "unknown")}`;
+	return `channel:${neutralizeAgentRaftRefLiterals(result.channelName ?? "unknown")}`;
+}
+const PREVIEW_BEFORE_CHARS = 80;
+const PREVIEW_AFTER_CHARS = 120;
+const PREVIEW_FALLBACK_CHARS = 200;
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findSearchMatch(content, query) {
+	const normalizedQuery = query.trim();
+	if (!normalizedQuery) return null;
+	const exactIndex = content.toLowerCase().indexOf(normalizedQuery.toLowerCase());
+	if (exactIndex >= 0) return {
+		start: exactIndex,
+		end: exactIndex + normalizedQuery.length
+	};
+	const terms = normalizedQuery.match(/"([^"]+)"|\S+/g) ?? [];
+	for (const rawTerm of terms) {
+		const term = rawTerm.replace(/^"|"$/g, "").trim();
+		if (!term) continue;
+		const match = new RegExp(escapeRegExp(term), "i").exec(content);
+		if (match?.index !== void 0) return {
+			start: match.index,
+			end: match.index + match[0].length
+		};
+	}
+	return null;
+}
+function* findRaftRefLiteralRanges(content) {
+	for (const match of content.matchAll(/\bdm:@[A-Za-z0-9][A-Za-z0-9_-]*(?:~(?:agent|human))?/g)) if (match.index !== void 0) yield {
+		start: match.index,
+		end: match.index + match[0].length
+	};
+	for (const match of content.matchAll(/\btask #[0-9]+\b/g)) if (match.index !== void 0) yield {
+		start: match.index,
+		end: match.index + match[0].length
+	};
+	for (const match of content.matchAll(/(^|[\n\s([{"'`;])(@[A-Za-z0-9][A-Za-z0-9_-]*)/g)) {
+		if (match.index === void 0) continue;
+		const prefix = match[1] ?? "";
+		const ref = match[2] ?? "";
+		yield {
+			start: match.index + prefix.length,
+			end: match.index + prefix.length + ref.length
+		};
+	}
+	for (const match of content.matchAll(/(^|[\n\s([{"'`;])(#[A-Za-z][A-Za-z0-9_-]*)/g)) {
+		if (match.index === void 0) continue;
+		const prefix = match[1] ?? "";
+		const ref = match[2] ?? "";
+		yield {
+			start: match.index + prefix.length,
+			end: match.index + prefix.length + ref.length
+		};
+	}
+}
+function expandSearchMatchToRefLiteral(content, match) {
+	for (const refRange of findRaftRefLiteralRanges(content)) if (match.start < refRange.end && match.end > refRange.start) return {
+		start: Math.min(match.start, refRange.start),
+		end: Math.max(match.end, refRange.end)
+	};
+	return match;
+}
+function trimPreviewWindow(content, start, end) {
+	let trimmedStart = start;
+	let trimmedEnd = end;
+	while (trimmedStart > 0 && /\s/.test(content[trimmedStart] ?? "")) trimmedStart += 1;
+	while (trimmedEnd < content.length && /\s/.test(content[trimmedEnd - 1] ?? "")) trimmedEnd -= 1;
+	return {
+		start: Math.max(0, Math.min(trimmedStart, content.length)),
+		end: Math.max(0, Math.min(trimmedEnd, content.length))
+	};
+}
+function escapeSearchComponentLiterals(text) {
+	return text.replace(/<\/?(?:result|preview|match)\b[^>]*>|<omit\s*\/>/gi, (tag) => tag.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"));
+}
+/** Neutralise `@handle`, `#channel`, `dm:@peer`, and `task #N` literals so quoted text cannot route attention. */
+function neutralizeAgentRaftRefLiterals(text) {
+	return text.replace(/\bdm:@([A-Za-z0-9][A-Za-z0-9_-]*(?:~(?:agent|human))?)/g, "dm:user:$1").replace(/\btask #([0-9]+)\b/g, "task:$1").replace(/(^|[\n\s([{"'`;])@([A-Za-z0-9][A-Za-z0-9_-]*)/g, "$1user:$2").replace(/(^|[\n\s([{"'`;])#([A-Za-z][A-Za-z0-9_-]*)/g, "$1channel:$2");
+}
+function renderAgentSearchPreviewText(text) {
+	return neutralizeAgentRaftRefLiterals(escapeSearchComponentLiterals(text));
+}
+function renderSearchPreview(content, query) {
+	const foundMatch = findSearchMatch(content, query);
+	const match = foundMatch ? expandSearchMatchToRefLiteral(content, foundMatch) : null;
+	let start = 0;
+	let end = Math.min(content.length, PREVIEW_FALLBACK_CHARS);
+	if (match) {
+		start = Math.max(0, match.start - PREVIEW_BEFORE_CHARS);
+		end = Math.min(content.length, match.end + PREVIEW_AFTER_CHARS);
+	}
+	({start, end} = trimPreviewWindow(content, start, end));
+	const leadingOmit = start > 0 ? "<omit />" : "";
+	const trailingOmit = end < content.length ? "<omit />" : "";
+	if (!match || match.end <= start || match.start >= end) return `${leadingOmit}${renderAgentSearchPreviewText(content.slice(start, end))}${trailingOmit}`;
+	const before = content.slice(start, match.start);
+	const matched = content.slice(match.start, match.end);
+	const after = content.slice(match.end, end);
+	return [
+		leadingOmit,
+		renderAgentSearchPreviewText(before),
+		"<match>",
+		renderAgentSearchPreviewText(matched),
+		"</match>",
+		renderAgentSearchPreviewText(after),
+		trailingOmit
+	].join("");
+}
+/** Search results with <match>/<omit /> preview markup. */
+function formatAgentSearchResults(query, data, offset, sort, limit) {
+	const trimmedQuery = query.trim();
+	const oldestShown = data.results?.length ? data.results[data.results.length - 1]?.createdAt : void 0;
+	const nextPageHint = sort === "recent" && oldestShown ? `page with --before ${oldestShown} (pages OLDER only; NOT a complete traversal: stored times are microsecond but this key is millisecond, so rows inside the boundary millisecond can be skipped, and a full page sharing one timestamp can repeat indefinitely; copy the key verbatim)` : `page with --offset ${(offset ?? 0) + (data.results?.length ?? 0)}`;
+	const effectiveLimit = Math.min(limit ?? 20, 50);
+	const countEqualsLimit = (data.results?.length ?? 0) === effectiveLimit;
+	const limitSource = limit === void 0 ? `the server default of ${effectiveLimit}` : limit > 50 ? `the server cap of ${effectiveLimit} (your --limit ${limit} was clamped)` : `the --limit ${effectiveLimit} that was requested`;
+	const atCapRemedy = effectiveLimit < 50 ? "re-run with a higher --limit to tell the two apart" : `this is already the server's maximum page, so completeness CANNOT be determined from this result: a higher --limit is clamped back to ${effectiveLimit} and paging will not reveal it; narrow the query (add --sender, --target, --after or --before) until fewer than ${effectiveLimit} results match`;
+	const truncation = data.hasMore === true ? `truncated=true · more results exist, ${nextPageHint}` : data.hasMore === false ? countEqualsLimit ? `truncated=unknown · server reported hasMore=false, but this page returned exactly ${limitSource}, which is also what a capped page returns; ${atCapRemedy}` : "truncated=false" : "truncated=unknown · server did not report hasMore";
+	if (!data.results || data.results.length === 0) return `No search results. (${truncation})`;
+	const formatted = data.results.map((result) => {
+		const ref = `msg:${result.id}`;
+		const content = result.content ?? result.snippet ?? "";
+		const sender = neutralizeAgentRaftRefLiterals(result.senderName ?? "unknown");
+		const senderType = result.senderType ? ` (${result.senderType})` : "";
+		const taskProjection = formatAgentTaskCurrentProjection(result.taskCurrentProjection, result.taskNumber, renderAgentSearchPreviewText).trimStart();
+		return [
+			`<result ref="${ref}">`,
+			`Source: ${renderSearchSource(result)}`,
+			`Sender: ${sender}${senderType}`,
+			`Time: ${result.createdAt ? formatLocalTimeWithOffset(result.createdAt) : "-"}`,
+			...taskProjection ? [taskProjection] : [],
+			"",
+			"<preview>",
+			renderSearchPreview(content, trimmedQuery),
+			"</preview>",
+			"</result>"
+		].join("\n");
+	}).join("\n\n");
+	const resultLabel = data.results.length === 1 ? "result" : "results";
+	const count = `${data.results.length} ${resultLabel} · ${truncation}`;
+	return [
+		trimmedQuery ? `Search results for: "${trimmedQuery}" (${count})` : `Filtered message results (${count})`,
+		"",
+		formatted,
+		"",
+		"If a result may be relevant but its preview is not enough, read the surrounding context for that result before answering."
+	].join("\n");
+}
+//#endregion
+//#region ../shared/src/agentOps/search.ts
+async function searchMessages(client, request) {
+	if (!request.query?.trim() && !request.target && !request.sender) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass a query, or filter by target or sender." }));
+	const result = await client.messages.search({
+		...request.query?.trim() ? { q: request.query.trim() } : {},
+		...request.target ? { channel: request.target } : {},
+		...request.sender ? { sender: request.sender } : {},
+		...request.sort ? { sort: request.sort } : {},
+		...request.before ? { before: request.before } : {},
+		...request.after ? { after: request.after } : {},
+		...request.limit === void 0 ? {} : { limit: String(request.limit) },
+		...request.offset === void 0 ? {} : { offset: String(request.offset) }
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	const hasMore = typeof data.hasMore === "boolean" ? data.hasMore : null;
+	const page = {
+		query: request.query?.trim() ?? "",
+		results: data.results,
+		hasMore
+	};
+	const next = hasMore ? {
+		kind: "next_search_page",
+		args: {
+			...request,
+			offset: (request.offset ?? 0) + data.results.length
+		},
+		why: "More results exist; page on, or narrow the query."
+	} : null;
+	return {
+		ok: true,
+		state: data.results.length > 0 ? "results" : "empty",
+		data: page,
+		next,
+		text: formatAgentSearchResults(page.query, {
+			results: data.results,
+			...hasMore === null ? {} : { hasMore }
+		}, request.offset, request.sort, request.limit)
+	};
+}
+async function resolveMessage(client, request) {
+	if (!request.messageId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A message id is required." }));
+	const result = await client.messages.resolve({ msgId: request.messageId });
+	if (!result.ok) return failureFromClientResult(result);
+	const message = projectRaftMessage(result.data.message);
+	if (!message) return failureOutcome(opError("INVALID_RESPONSE", { message: "The resolved message carries no conversation identity." }));
+	return {
+		ok: true,
+		state: "message",
+		data: message,
+		next: {
+			kind: "read_target",
+			command: `raft message read --target "${message.target}" --around ${message.shortId ?? request.messageId}`,
+			args: {
+				target: message.target,
+				around: message.id ?? request.messageId
+			},
+			why: "Read the surrounding context before acting on one message."
+		},
+		text: formatAgentMessages([toAgentMessageLike(message.raw)])
+	};
+}
+async function reactToMessage(client, request, action = "add") {
+	const emoji = request.emoji?.trim();
+	if (!request.messageId?.trim() || !emoji || /\s/.test(emoji) || emoji.length > 16) return failureOutcome(opError("INVALID_REQUEST", { message: "A message id and a single reaction emoji are required." }));
+	const params = { msgId: request.messageId };
+	const result = action === "add" ? await client.messages.addReaction(params, { emoji }) : await client.messages.removeReaction(params, { emoji });
+	if (!result.ok) return failureFromClientResult(result);
+	const verb = action === "add" ? "added to" : "removed from";
+	return {
+		ok: true,
+		state: action === "add" ? "added" : "removed",
+		data: {
+			messageId: request.messageId,
+			emoji
+		},
+		next: null,
+		text: `Reaction ${emoji} ${verb} message ${request.messageId.slice(0, 8)}.`
+	};
+}
+//#endregion
+//#region ../shared/src/agentText/mentions.ts
+function normalizeAgentMentionAction(action) {
+	if (action === "notify" || action === "notify_only") return "notify";
+	if (action === "add" || action === "invite") return "add";
+	return null;
+}
+function formatActionCommands(action) {
+	const verbs = action.availableActions.map(normalizeAgentMentionAction).filter((verb) => verb !== null);
+	return Array.from(new Set(verbs)).map((verb) => `  ${verb}: raft mention ${verb} ${action.resolutionId}`);
+}
+function formatAuthoredMentionToken(targetHandle) {
+	return targetHandle.startsWith("@") ? targetHandle : `@${targetHandle}`;
+}
+const PENDING_MENTION_ACTION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Per-token mention recovery command line; null when the id is not a UUID (fail closed). */
+function formatAgentMentionNotifyRecoveryCommand(resolutionId) {
+	return PENDING_MENTION_ACTION_ID_RE.test(resolutionId) ? `raft mention notify ${resolutionId}` : null;
+}
+function toAgentSenderPendingMentionAction(action) {
+	return {
+		resolutionId: action.resolutionId,
+		messageId: action.messageId,
+		targetHandle: formatAuthoredMentionToken(action.targetHandle),
+		status: "not_queued",
+		reason: "not_in_conversation",
+		consequence: "This @mention did not notify anyone.",
+		expiresAt: action.expiresAt ?? null,
+		recoveryCommand: formatAgentMentionNotifyRecoveryCommand(action.resolutionId)
+	};
+}
+function toAgentSenderUnresolvedMentionWarning(targetHandle) {
+	return {
+		targetHandle: formatAuthoredMentionToken(targetHandle),
+		status: "not_queued",
+		reason: "unknown_or_not_visible",
+		consequence: "This @mention did not notify anyone.",
+		expiresAt: null,
+		recoveryCommand: null
+	};
+}
+function formatPendingReason(reason) {
+	if (reason === "not_member") return "not in the conversation at send time, so the @mention was not delivered";
+	return reason;
+}
+function normalizeAgentPendingMentionActions(data) {
+	const value = data;
+	return (Array.isArray(value?.pendingMentionActions) ? value.pendingMentionActions : Array.isArray(value?.actions) ? value.actions : Array.isArray(value?.results) ? value.results : []).filter((item) => Boolean(item && typeof item === "object")).map((item) => ({
+		resolutionId: String(item.resolutionId ?? item.id ?? ""),
+		messageId: String(item.messageId ?? ""),
+		targetType: String(item.targetType ?? "unknown"),
+		targetHandle: String(item.targetHandle ?? ""),
+		reason: String(item.reason ?? "Mention target was not notified at send time."),
+		availableActions: Array.isArray(item.availableActions) ? item.availableActions.map(String) : [],
+		expiresAt: typeof item.expiresAt === "string" ? item.expiresAt : null
+	})).filter((item) => item.resolutionId.length > 0);
+}
+function normalizeAgentMentionActionResults(data) {
+	const value = data;
+	return (Array.isArray(value?.results) ? value.results : Array.isArray(value?.actionResults) ? value.actionResults : []).filter((item) => Boolean(item && typeof item === "object")).map((item) => ({
+		resolutionId: String(item.resolutionId ?? item.id ?? ""),
+		status: String(item.status ?? "not_found"),
+		action: typeof item.action === "string" ? normalizeAgentMentionAction(item.action) : null,
+		messageId: typeof item.messageId === "string" ? item.messageId : null,
+		channelId: typeof item.channelId === "string" ? item.channelId : null,
+		targetType: typeof item.targetType === "string" ? item.targetType : null,
+		targetId: typeof item.targetId === "string" ? item.targetId : null,
+		targetHandle: typeof item.targetHandle === "string" ? item.targetHandle : null,
+		message: typeof item.message === "string" ? item.message : null,
+		reason: typeof item.reason === "string" ? item.reason : null,
+		dedupedResolutionIds: Array.isArray(item.dedupedResolutionIds) ? item.dedupedResolutionIds.filter((id) => typeof id === "string" && id.length > 0) : []
+	})).filter((item) => item.resolutionId.length > 0);
+}
+const PENDING_DEFAULT_LIMIT = 50;
+function pendingPageVerdict(hasMore, limit, shown) {
+	const asked = limit === void 0 ? "server default 50" : `--limit ${limit}`;
+	if (hasMore === true) return (limit ?? PENDING_DEFAULT_LIMIT) >= 100 ? `shown ${shown}, ${asked} — truncated=true · more pending actions exist AND this is the server's maximum page (100); this route has no offset or cursor, so the rest cannot be reached from here — resolve what you can and re-run; rows with no available actions are not actionable here and will remain until they expire` : `shown ${shown}, ${asked} — truncated=true · more pending actions exist; raise --limit (server caps at 100) or resolve these first and re-run`;
+	if (hasMore === false) return `shown ${shown}, ${asked} — truncated=false · this is the complete list`;
+	return `shown ${shown}, ${asked} — truncated=unknown · server did not report has_more, so completeness is NOT asserted`;
+}
+/** Undelivered-mentions partial result (send) or the pending list. */
+function formatAgentPendingMentionActions(actions, opts = {}) {
+	const unresolvedMentionHandles = opts.source === "send" ? Array.from(new Set(opts.unresolvedMentionHandles ?? [])) : [];
+	const pageNote = opts.source === "pending" ? pendingPageVerdict(opts.hasMore, opts.limit, actions.length) : "";
+	if (actions.length === 0 && unresolvedMentionHandles.length === 0) return opts.source === "pending" ? `Pending mention actions\n\nNo pending mention actions. (${pageNote})\n` : "";
+	if (opts.source === "send") {
+		const lines = [
+			"Undelivered mentions — partial result",
+			"Message effect: status=queued. Queue acceptance is the only message proof.",
+			"Do not rerun `raft message send`; the message is already queued and a retry could duplicate it.",
+			"Each row below is bound to the literal @token from your message.",
+			"For a literal name rather than a recipient, wrap the @handle in inline or fenced code.",
+			""
+		];
+		for (const rawAction of actions) {
+			const action = toAgentSenderPendingMentionAction(rawAction);
+			lines.push(`- ${action.targetHandle} — status=${action.status}`);
+			lines.push(`  reason: ${action.reason}`);
+			lines.push(`  consequence: ${action.consequence}`);
+			lines.push(`  pending action: ${action.recoveryCommand ? action.resolutionId : "[invalid pending action id]"}`);
+			if (action.messageId) lines.push(`  message: ${action.messageId}`);
+			lines.push(`  expires: ${action.expiresAt ?? "unknown"}`);
+			if (action.recoveryCommand) {
+				lines.push(`  recovery: ${action.recoveryCommand}`);
+				lines.push("  note: the handle resolved, but the target was not in this conversation at send time. This does not prove the person left the server.");
+				lines.push("  note: notify exits nonzero unless the target queue accepts the delivery.");
+			} else lines.push("  recovery: unavailable because the pending action id is invalid; inspect `raft mention pending` without resending the message.");
+		}
+		for (const rawHandle of unresolvedMentionHandles) {
+			const warning = toAgentSenderUnresolvedMentionWarning(rawHandle);
+			lines.push(`- ${warning.targetHandle} — status=${warning.status}`);
+			lines.push(`  reason: ${warning.reason}`);
+			lines.push(`  consequence: ${warning.consequence}`);
+			lines.push("  pending action: none; no visible target resolved for this token");
+			lines.push("  expires: n/a");
+			lines.push("  recovery: if this was a literal name or prose, wrap it in inline/fenced code; otherwise verify the exact handle and send only a corrected follow-up mention; do not resend this message.");
+		}
+		return `${lines.join("\n")}\n`;
+	}
+	const lines = [
+		"Pending mention actions",
+		`(${pageNote})`,
+		""
+	];
+	for (const action of actions) {
+		const target = action.targetHandle ? `${action.targetHandle} (${action.targetType})` : action.targetType;
+		lines.push(`- ${action.resolutionId} — ${target}`);
+		if (action.messageId) lines.push(`  message: ${action.messageId}`);
+		lines.push(`  reason: ${formatPendingReason(action.reason)}`);
+		if (action.expiresAt) lines.push(`  expires: ${action.expiresAt}`);
+		const commands = formatActionCommands(action);
+		if (commands.length > 0) {
+			lines.push("  recovery commands:");
+			lines.push(...commands);
+			if (commands.some((command) => command.includes(" mention notify "))) lines.push("  note: notify exits nonzero unless the target queue accepts the delivery.");
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}
+function formatMentionActionDetail(result) {
+	const detail = result.message ?? result.reason ?? null;
+	if (result.status === "dropped") return detail ? `not delivered: ${detail}` : "not delivered";
+	return detail;
+}
+/** notify/add action outcome rows. */
+function formatAgentMentionActionResults(action, results) {
+	const lines = [`Mention ${action} results`, ""];
+	if (results.length === 0) {
+		lines.push("No result rows returned.");
+		return `${lines.join("\n")}\n`;
+	}
+	for (const result of results) {
+		const target = result.targetHandle ? ` ${result.targetHandle}` : "";
+		const detail = formatMentionActionDetail(result);
+		const suffix = detail ? ` — ${detail}` : "";
+		lines.push(`- ${result.resolutionId}${target}: ${result.status}${suffix}`);
+		if (result.dedupedResolutionIds && result.dedupedResolutionIds.length > 1) lines.push(`  deduped: ${result.dedupedResolutionIds.join(", ")}`);
+	}
+	if (action === "notify" && results.some((result) => result.status === "queued" && result.reason !== "already_queued")) lines.push("", `Recipient guidance: ${formatAgentReplyAffordance({ non_member_mention: true })}`);
+	return `${lines.join("\n")}\n`;
+}
+function describeDelivery(row) {
+	switch (row.outcome) {
+		case "delivered": return "delivered";
+		case "pending": return "still in flight — do not conclude yet";
+		case "unknown": return "UNKNOWN — our instrument could not see this one; re-check, do not conclude";
+		case "lost": switch (row.reasonCategory) {
+			case "quota": return "LOST — target is rate/quota limited; it will not arrive, re-route or retry later";
+			case "runtime_error": return "LOST — target's runtime rejected delivery; re-route";
+			case "not_launched": return "LOST — target was not running; re-route or start it";
+			case "unclassified": return "LOST — cause is outside the seat-availability set; re-route";
+			default: return "LOST — server sent no category for this row (malformed); treat the cause as unknown";
+		}
+	}
+}
+/** Per-target mention delivery outcome for a message the bound agent sent. */
+function formatAgentSenderMentionDeliveries(messageId, deliveries) {
+	if (deliveries.length === 0) return `Message ${messageId}\n\nNo mention deliveries recorded for this message.\n`;
+	const lines = [`Message ${messageId} — mention delivery per target`, ""];
+	for (const row of deliveries) lines.push(`  ${row.targetHandle || "(unknown target)"}: ${describeDelivery(row)}`);
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region ../shared/src/agentOps/mentions.ts
+async function pendingMentionActions(client, request = {}) {
+	const result = await client.mentions.pendingActions(request.limit === void 0 ? {} : { limit: String(request.limit) });
+	if (!result.ok) return failureFromClientResult(result);
+	const actions = normalizeAgentPendingMentionActions(result.data);
+	const hasMore = typeof result.data.has_more === "boolean" ? result.data.has_more : null;
+	const first = actions.find((a) => a.availableActions.length > 0);
+	const next = first ? {
+		kind: "resolve_mention",
+		command: `raft mention notify ${first.resolutionId}`,
+		args: {
+			action: "notify",
+			resolutionIds: [first.resolutionId]
+		},
+		why: "This @mention reached nobody at send time; notify the target (or add them) so the message is seen."
+	} : null;
+	return {
+		ok: true,
+		state: actions.length > 0 ? "pending" : "empty",
+		data: {
+			actions,
+			hasMore,
+			limit: request.limit
+		},
+		next,
+		text: formatAgentPendingMentionActions(actions, {
+			source: "pending",
+			...hasMore === null ? {} : { hasMore },
+			limit: request.limit
+		})
+	};
+}
+async function executeMentionAction(client, request) {
+	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 result = await client.mentions.executeAction({
+		action: request.action,
+		resolutionIds: ids
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const results = normalizeAgentMentionActionResults(result.data);
+	return {
+		ok: true,
+		state: "executed",
+		data: {
+			action: request.action,
+			results
+		},
+		next: null,
+		text: formatAgentMentionActionResults(request.action, results)
+	};
+}
+async function senderMentionDeliveries(client, request) {
+	if (!request.messageId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A message id is required." }));
+	const result = await client.mentions.senderDeliveries({ messageId: request.messageId });
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	return {
+		ok: true,
+		state: data.deliveries.length > 0 ? "deliveries" : "empty",
+		data,
+		next: null,
+		text: formatAgentSenderMentionDeliveries(data.messageId, data.deliveries)
+	};
+}
+//#endregion
+//#region ../shared/src/agentText/knowledge.ts
+function formatMatchReason(result) {
+	const parts = [];
+	for (const { term, matched } of result.correctedTerms ?? []) parts.push(`${term} → ${matched} (typo)`);
+	for (const { from, to } of result.expandedTerms ?? []) parts.push(`${from} → ${to} (concept)`);
+	return parts.length > 0 ? `   matched: ${parts.join(", ")}` : "";
+}
+function formatAgentKnowledgeSearchResults(results) {
+	return results.map((result, index) => {
+		const body = result.firstScreen.trim().split(/\r?\n/).filter(Boolean).map((line) => `   ${line}`).join("\n");
+		const reason = formatMatchReason(result);
+		return `${index + 1}. ${result.slug} — ${result.title}${reason ? `\n${reason}` : ""}${body ? `\n${body}` : ""}`;
+	}).join("\n\n") + "\n";
+}
+function formatAgentKnowledgeStdout(content) {
+	return content.endsWith("\n") ? content : `${content}\n`;
+}
+//#endregion
+//#region ../shared/src/agentOps/manual.ts
+function requireContext(context) {
+	if (!context?.intent?.trim() || !context?.reason?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "Manual calls need a short `intent` and `reason`." }));
+	return null;
+}
+async function getManualTopic(client, request) {
+	const invalid = requireContext(request);
+	if (invalid) return invalid;
+	if (!request.topic?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A topic id is required." }));
+	const result = await client.knowledge.get({
+		topic: request.topic.trim(),
+		intent: request.intent.trim(),
+		reason: request.reason.trim()
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	return {
+		ok: true,
+		state: "topic",
+		data: result.data,
+		next: null,
+		text: formatAgentKnowledgeStdout(result.data.content)
+	};
+}
+async function searchManual(client, request) {
+	const invalid = requireContext(request);
+	if (invalid) return invalid;
+	if (!request.query?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "Search keywords are required." }));
+	const result = await client.knowledge.search({
+		query: request.query.trim(),
+		...request.scope ? { scope: request.scope } : {},
+		intent: request.intent.trim(),
+		reason: request.reason.trim()
+	});
+	if (!result.ok) return failureFromClientResult(result);
+	const data = result.data;
+	const results = data.results;
+	const first = results[0];
+	const next = first ? {
+		kind: "read_manual_topic",
+		command: `raft manual get ${first.slug} --intent "…" --reason "…"`,
+		args: { topic: first.slug },
+		why: "Open the best-matching topic."
+	} : null;
+	return {
+		ok: true,
+		state: results.length > 0 ? "results" : "empty",
+		data,
+		next,
+		text: results.length > 0 ? formatAgentKnowledgeSearchResults(results) : "No Manual topics matched. Retry with different keywords, keeping your intent and reason.\n"
+	};
+}
+//#endregion
+//#region ../shared/src/agentOps/state.ts
+const RAFT_STATE_SCHEMA = "raft-sdk-state.v1";
+const RAFT_STATE_CONTINUATIONS_PER_TARGET = 3;
+const RAFT_STATE_CONTINUATIONS_TOTAL = 20;
+function isNullableCursor(value) {
+	return value === null || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/** Validate a loaded value; anything unrecognised is treated as an empty store (safe: see file header). */
+function parseRaftState(value) {
+	if (!value || typeof value !== "object") return null;
+	const v = value;
+	if (v.schema !== "raft-sdk-state.v1") return null;
+	if (typeof v.version !== "number" || !Number.isInteger(v.version) || v.version < 0) return null;
+	if (!isNullableCursor(v.cursor ?? null) || !isNullableCursor(v.pendingCursor ?? null)) return null;
+	const frontier = v.frontier;
+	const continuations = Array.isArray(v.continuations) ? v.continuations.filter((c) => {
+		const r = c;
+		return Boolean(r) && typeof r.target === "string" && typeof r.idempotencyKey === "string" && typeof r.contentHash === "string" && typeof r.heldAt === "string";
+	}) : [];
+	return {
+		schema: RAFT_STATE_SCHEMA,
+		version: v.version,
+		cursor: v.cursor ?? null,
+		pendingCursor: v.pendingCursor ?? null,
+		frontier: frontier && frontier.version === 1 ? frontier : {
+			version: 1,
+			targets: {},
+			aliases: {}
+		},
+		continuations
+	};
+}
+/** Hex SHA-256 identifying one logical message (WebCrypto; Workers-safe). */
+async function hashRaftSendContent(target, content, attachmentIds = []) {
+	const bytes = new TextEncoder().encode(`${target}\n${[...attachmentIds].sort().join(",")}\n${content}`);
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* One client's view of the persisted state: loads once, holds the working
+* copy, saves on request. Also used without a store (memory only), so the
+* pending/committed cursor flow behaves the same with or without persistence.
+*/
+var RaftStateSession = class {
+	store;
+	onError;
+	frontier;
+	cursor = null;
+	pendingCursor = null;
+	continuations = [];
+	loadedVersion = void 0;
+	loading = null;
+	dirty = false;
+	constructor(store, frontier, onError) {
+		this.store = store;
+		this.onError = onError;
+		this.frontier = frontier;
+	}
+	get persistent() {
+		return this.store !== void 0;
+	}
+	/** The version loaded from (or last saved to) the store; `undefined` before the first save of an empty store. */
+	get version() {
+		return this.loadedVersion;
+	}
+	/** Load once. A failed or unreadable load starts from an empty state (reported, not thrown). */
+	ensureLoaded() {
+		if (!this.store) return Promise.resolve();
+		this.loading ??= (async () => {
+			let raw = null;
+			try {
+				raw = await this.store.load();
+			} catch (error) {
+				this.onError?.(error, {
+					phase: "load",
+					version: void 0
+				});
+				return;
+			}
+			const state = parseRaftState(raw);
+			if (!state) return;
+			this.loadedVersion = state.version;
+			this.cursor = state.cursor;
+			this.pendingCursor = state.pendingCursor;
+			this.frontier.absorb(state.frontier);
+			this.continuations = state.continuations ?? [];
+		})();
+		return this.loading;
+	}
+	markDirty() {
+		this.dirty = true;
+	}
+	/** Record the cursor of a batch just returned. Acknowledges nothing. */
+	setPending(cursor) {
+		if (cursor === null || cursor === this.pendingCursor) return;
+		this.pendingCursor = cursor;
+		this.dirty = true;
+	}
+	/**
+	* Promote a cursor to committed. With no argument, commits `pendingCursor`.
+	* Returns the committed cursor, or null when there was nothing to commit.
+	* Never moves the committed cursor backwards.
+	*/
+	commit(cursor) {
+		const next = cursor === void 0 ? this.pendingCursor : cursor;
+		if (next === null || next === void 0) return null;
+		if (this.cursor === null || next > this.cursor) this.cursor = next;
+		if (this.pendingCursor !== null && this.pendingCursor <= this.cursor) this.pendingCursor = null;
+		this.dirty = true;
+		return this.cursor;
+	}
+	findContinuation(target, contentHash) {
+		return this.continuations.find((c) => c.target === target && c.contentHash === contentHash);
+	}
+	rememberContinuation(entry) {
+		this.continuations = this.continuations.filter((c) => !(c.target === entry.target && c.contentHash === entry.contentHash));
+		this.continuations.push(entry);
+		const perTarget = this.continuations.filter((c) => c.target === entry.target);
+		for (const drop of perTarget.slice(0, Math.max(0, perTarget.length - 3))) this.continuations.splice(this.continuations.indexOf(drop), 1);
+		if (this.continuations.length > 20) this.continuations.splice(0, this.continuations.length - 20);
+		this.dirty = true;
+	}
+	forgetContinuation(target, contentHash) {
+		const before = this.continuations.length;
+		this.continuations = this.continuations.filter((c) => !(c.target === target && c.contentHash === contentHash));
+		if (this.continuations.length !== before) this.dirty = true;
+	}
+	snapshot(nextVersion = (this.loadedVersion ?? 0) + 1) {
+		return {
+			schema: RAFT_STATE_SCHEMA,
+			version: nextVersion,
+			cursor: this.cursor,
+			pendingCursor: this.pendingCursor,
+			frontier: this.frontier.snapshot(),
+			continuations: [...this.continuations]
+		};
+	}
+	/**
+	* Save if anything changed (or `force`). One attempt; a failure is reported
+	* and swallowed. Returns whether the save succeeded (true when nothing to save).
+	*/
+	async save(options = {}) {
+		if (!this.store) return true;
+		if (!this.dirty && !options.force) return true;
+		const expectedVersion = this.loadedVersion;
+		const state = this.snapshot();
+		try {
+			await this.store.save(state, { expectedVersion });
+		} catch (error) {
+			this.onError?.(error, {
+				phase: "save",
+				version: expectedVersion
+			});
+			return false;
+		}
+		this.loadedVersion = state.version;
+		this.dirty = false;
+		return true;
+	}
+};
+//#endregion
 //#region src/raft.ts
 function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
 	const authorization = `Bearer ${requireAgentCredential(options.credential)}`;
 	const frontier = SeenFrontier.fromSnapshot(options.frontier);
+	const session = new RaftStateSession(options.state, frontier, options.onStateSaveError);
+	/** Load before, run, then save if the operation succeeded and changed the state. */
+	const withState = async (run) => {
+		await session.ensureLoaded();
+		const outcome = await run();
+		if (outcome.ok) await session.save();
+		return outcome;
+	};
 	const routes = createRaftRoutes({
 		serverUrl,
 		fetch: options.fetch,
@@ -11828,6 +13805,27 @@ function createRaft(options) {
 		throttle: options.throttle,
 		auth: { authorization }
 	} });
+	/**
+	* Send through the state session: a resend of the same logical message
+	* (same target, content, attachments) reuses the held send's idempotency key;
+	* a hold is remembered; a successful send clears it.
+	*/
+	const sendWithState = (request) => withState(async () => {
+		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
+		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
+		const outcome = await sendMessage(routes, pending ? {
+			...request,
+			idempotencyKey: pending.idempotencyKey
+		} : request, frontier);
+		if (outcome.ok && outcome.state === "held") session.rememberContinuation({
+			target: request.target,
+			idempotencyKey: outcome.data.idempotencyKey,
+			contentHash,
+			heldAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (outcome.ok && outcome.state === "sent") session.forgetContinuation(request.target, contentHash);
+		return outcome;
+	});
 	return {
 		identity: { whoami: () => getRaftContext(routes) },
 		wake: {
@@ -11839,17 +13837,115 @@ function createRaft(options) {
 			}
 		},
 		inbox: {
-			check: (request) => checkInbox(inboxApi, request, frontier),
-			drain: (request) => drainInbox(inboxApi, request, frontier),
+			check: (request = {}) => withState(async () => {
+				const since = request.since ?? session.cursor ?? void 0;
+				const outcome = await checkInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier);
+				if (outcome.ok) {
+					session.markDirty();
+					if (since !== void 0 && (request.ack ?? "cursor") === "cursor") session.commit(since);
+					if (outcome.data.ackMode === "cursor" && outcome.data.messages.length > 0) session.setPending(outcome.data.cursor);
+				}
+				return outcome;
+			}),
+			commit: async (target) => {
+				await session.ensureLoaded();
+				const cursor = session.commit(target === void 0 ? void 0 : target.cursor);
+				return {
+					cursor,
+					saved: cursor === null ? true : await session.save()
+				};
+			},
+			drain: (request = {}) => (async function* () {
+				await session.ensureLoaded();
+				const since = request.since ?? session.cursor ?? void 0;
+				return yield* drainInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier, async (sent, batch) => {
+					if (sent !== null) session.commit(sent);
+					if (batch.ackMode === "cursor" && batch.messages.length > 0) session.setPending(batch.cursor);
+					session.markDirty();
+					await session.save();
+				});
+			})(),
 			list: (request) => listInbox(routes, request)
 		},
 		messages: {
-			read: (request) => readHistory(routes, request, frontier),
-			send: (request) => sendMessage(routes, request, frontier),
-			reply: (message, request) => replyTo(routes, message, request, frontier)
+			read: (request) => withState(async () => {
+				const outcome = await readHistory(routes, request, frontier);
+				if (outcome.ok) session.markDirty();
+				return outcome;
+			}),
+			send: (request) => sendWithState(request),
+			reply: (message, request) => sendWithState({
+				...request,
+				target: message.target
+			}),
+			search: (request) => searchMessages(routes, request),
+			resolve: (request) => resolveMessage(routes, request),
+			react: (request) => reactToMessage(routes, request, "add"),
+			unreact: (request) => reactToMessage(routes, request, "remove")
+		},
+		attachments: {
+			upload: (request) => uploadAttachment(routes, {
+				serverUrl,
+				fetch: options.fetch ?? fetch,
+				headers: Object.fromEntries(new Headers(options.headers)),
+				authorization
+			}, request),
+			download: (request) => downloadAttachment(routes, request),
+			comments: (request) => attachmentComments(routes, request)
+		},
+		mentions: {
+			pending: (request) => pendingMentionActions(routes, request),
+			execute: (request) => executeMentionAction(routes, request),
+			deliveries: (request) => senderMentionDeliveries(routes, request)
+		},
+		manual: {
+			get: (request) => getManualTopic(routes, request),
+			search: (request) => searchManual(routes, request)
+		},
+		tasks: {
+			claim: (request) => claimTasks(routes, request),
+			list: (request) => listTasks(routes, request),
+			create: (request) => createTasks(routes, request),
+			unclaim: (request) => unclaimTask(routes, request),
+			assign: (request) => assignTask(routes, request),
+			updateStatus: (request) => updateTaskStatus(routes, request),
+			amend: (request) => amendTask(routes, request),
+			history: (request) => taskHistory(routes, request),
+			convert: (request) => convertMessageToTask(routes, request),
+			delete: (request) => deleteTask(routes, request)
+		},
+		channels: {
+			join: (request) => joinChannel(routes, request),
+			leave: (request) => leaveChannel(routes, request),
+			mute: (request) => muteChannel(routes, request),
+			unmute: (request) => unmuteChannel(routes, request),
+			members: (request) => channelMembers(routes, request)
+		},
+		threads: {
+			list: () => listThreads(routes),
+			unfollow: (request) => unfollowThread(routes, request)
+		},
+		server: { info: (request) => serverInfo(routes, request) },
+		profile: {
+			show: (request) => showProfile(routes, request),
+			update: (request) => updateProfile(routes, request)
 		},
-		tasks: { claim: (request) => claimTasks(routes, request) },
 		frontier,
+		state: {
+			save: async () => {
+				await session.ensureLoaded();
+				session.markDirty();
+				return session.save();
+			},
+			load: () => session.ensureLoaded(),
+			snapshot: () => session.snapshot(session.version ?? 0)
+		},
 		routes
 	};
 }
@@ -11857,6 +13953,9 @@ function createRaft(options) {
 exports.RAFT_INBOX_NOTICE_SCHEMA = RAFT_INBOX_NOTICE_SCHEMA;
 exports.RAFT_NOTICE_DELIVERY_ID_HEADER = RAFT_NOTICE_DELIVERY_ID_HEADER;
 exports.RAFT_NOTICE_SIGNATURE_HEADER = RAFT_NOTICE_SIGNATURE_HEADER;
+exports.RAFT_STATE_CONTINUATIONS_PER_TARGET = RAFT_STATE_CONTINUATIONS_PER_TARGET;
+exports.RAFT_STATE_CONTINUATIONS_TOTAL = RAFT_STATE_CONTINUATIONS_TOTAL;
+exports.RAFT_STATE_SCHEMA = RAFT_STATE_SCHEMA;
 exports.RaftCredentialError = RaftCredentialError;
 exports.RaftSdkConfigurationError = RaftSdkConfigurationError;
 exports.SeenFrontier = SeenFrontier;
@@ -11868,9 +13967,12 @@ exports.createRaftClientFromStore = createRaftClientFromStore;
 exports.createRaftRoutes = createRaftRoutes;
 exports.describeRaftRoute = describeRaftRoute;
 exports.hasAgentMessageIdentity = hasAgentMessageIdentity;
+exports.hashRaftSendContent = hashRaftSendContent;
+exports.inferAttachmentMimeType = inferAttachmentMimeType;
 exports.joinRaftChannelByTarget = joinRaftChannelByTarget;
 exports.listRaftRoutes = listRaftRoutes;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
+exports.parseRaftState = parseRaftState;
 exports.projectRaftMessage = projectRaftMessage;
 exports.projectRaftMessages = projectRaftMessages;
 exports.verifyInboxNotice = verifyInboxNotice;