@botiverse/raft-sdk 0.4.0 → 0.5.0

package/dist/cjs/index.cjs

@@ -4562,6 +4562,7 @@ const AGENT_API_ROUTE_META = {
 	integrationAppList: read,
 	integrationAppStatus: read,
 	actionPrepare: write,
+	agentCommand: write,
 	attachmentUpload: write,
 	attachmentUploadCapabilities: read,
 	attachmentUploadSessionCreate: write,
@@ -5465,6 +5466,47 @@ const agentApiActionPrepareBodySchema = passthroughObject({
 	target: string().trim().min(1),
 	action: actionCardActionSchema
 });
+/** Most UTF-8 bytes all argv items together may carry. */
+const AGENT_API_COMMAND_ARGV_MAX_BYTES = 16384;
+/** Most characters of `stdin`: the Server's message body cap (MAX_MESSAGE_LENGTH). */
+const AGENT_API_COMMAND_STDIN_MAX_LENGTH = 32e3;
+function isIanaTimeZone(value) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value });
+		return true;
+	} catch {
+		return false;
+	}
+}
+const agentApiCommandBodySchema = passthroughObject({
+	argv: array(string()).max(64).refine((argv) => argv.reduce((total, item) => total + new TextEncoder().encode(item).length, 0) <= AGENT_API_COMMAND_ARGV_MAX_BYTES, { message: `argv must not exceed ${AGENT_API_COMMAND_ARGV_MAX_BYTES} bytes in total` }),
+	stdin: string().max(AGENT_API_COMMAND_STDIN_MAX_LENGTH).optional(),
+	origin: _enum(["model", "code"]).optional(),
+	idempotencyKey: string().trim().min(1).max(200).optional(),
+	timezone: string().trim().min(1).max(64).refine(isIanaTimeZone, { message: "timezone must be an IANA time zone" }).optional(),
+	/**
+	* The model's current context (opaque). Reads are booked under it and a send
+	* only attests reads from the same context, so a gateway changes it when the
+	* model's context no longer holds what it read (new session, compaction),
+	* not per turn. Absent: reads count in any context.
+	*/
+	contextId: string().trim().min(1).max(200).optional(),
+	/**
+	* `message check` acknowledgement. A hosted check returns the batch it
+	* handed out unacknowledged, with `outcome.data.eventsCursor`; the gateway
+	* sends that value back here on a later request only after that result
+	* reached the model, and the next check then acknowledges the batch.
+	* Absent, or any value other than the cursor of the last batch handed out
+	* (a retry carrying an older cursor included), acknowledges nothing: the
+	* unacknowledged batch is delivered again.
+	*/
+	ackEventsCursor: string().trim().min(1).max(64).optional()
+});
+const agentApiCommandResponseSchema = passthroughObject({
+	exitCode: number$1().int(),
+	text: string(),
+	outcome: record(string(), unknown()).nullable()
+});
 const agentApiServerUpdateBodySchema = passthroughObject({
 	name: string().trim().min(1).max(100).optional(),
 	hideHumansFromMembers: boolean().optional()
@@ -7046,6 +7088,19 @@ const agentApiContract = {
 		request: { body: agentApiActionPrepareBodySchema },
 		response: { body: agentApiActionPrepareResponseSchema }
 	}),
+	agentCommand: route({
+		key: "agentCommand",
+		method: "POST",
+		path: "/command",
+		client: {
+			resource: "commands",
+			method: "run"
+		},
+		capability: "read",
+		description: "Run one `raft` command as the bound agent and return the text the CLI prints, its exit code and its outcome. HTTP 200 whenever the command ran, failed commands included; each request the command makes is authorized on its own.",
+		request: { body: agentApiCommandBodySchema },
+		response: { body: agentApiCommandResponseSchema }
+	}),
 	attachmentUpload: route({
 		key: "attachmentUpload",
 		method: "POST",
@@ -9357,6 +9412,31 @@ const AGENT_API_ROUTE_MANIFEST = [
 			"body": true
 		}
 	},
+	{
+		"key": "agentCommand",
+		"method": "POST",
+		"path": "/command",
+		"fullPath": "/internal/agent-api/command",
+		"client": {
+			"resource": "commands",
+			"method": "run"
+		},
+		"capability": "read",
+		"description": "Run one `raft` command as the bound agent and return the text the CLI prints, its exit code and its outcome. HTTP 200 whenever the command ran, failed commands included; each request the command makes is authorized on its own.",
+		"sideEffect": "write",
+		"idempotency": "none",
+		"destructive": false,
+		"audience": "both",
+		"request": {
+			"params": false,
+			"query": false,
+			"body": true
+		},
+		"response": {
+			"kind": "json",
+			"body": true
+		}
+	},
 	{
 		"key": "attachmentUpload",
 		"method": "POST",
@@ -9659,7 +9739,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "c7a793816a7a90ed";
+const AGENT_API_MANIFEST_VERSION = "311047956109765f";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -9929,613 +10009,288 @@ function createRaftManageClient(readApi, writeApi, avatar) {
 	};
 }
 //#endregion
-//#region src/client.ts
-var RaftSdkConfigurationError = class extends Error {
-	code;
-	name = "RaftSdkConfigurationError";
-	constructor(code, message) {
-		super(message);
-		this.code = code;
-	}
+//#region ../shared/src/agentOps/outcome.ts
+const SERVER_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
+const DEFAULT_MESSAGES = {
+	INVALID_REQUEST: "The request did not match the Agent API contract; nothing was sent.",
+	TRANSPORT_ERROR: "The request did not reach the Raft Server.",
+	HTTP_ERROR: "The Raft Server rejected the request.",
+	INVALID_RESPONSE: "The Raft Server response did not match the Agent API contract.",
+	CAPABILITY_NOT_AUTHORIZED: "This credential does not carry the capability this operation needs.",
+	SCOPE_DENIED: "This agent's scope set does not allow this operation.",
+	NOT_FOUND: "The target or message does not exist or is not visible to this agent.",
+	CONFLICT: "The Raft Server refused the operation because of the current state.",
+	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different message.",
+	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "This operation is not available to External Agents.",
+	UNAVAILABLE: "The Raft Server could not serve this operation right now."
 };
-function requireServerUrl(value) {
-	const serverUrl = value.trim();
-	if (!serverUrl) throw new RaftSdkConfigurationError("MISSING_SERVER_URL", "Raft Server URL is required");
-	let parsed;
-	try {
-		parsed = new URL(serverUrl);
-	} catch {
-		throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must be an absolute HTTP(S) URL");
+const DEFAULT_NEXT_ACTION = {
+	INVALID_REQUEST: "Fix the request arguments; nothing was sent.",
+	TRANSPORT_ERROR: "Check connectivity to the Raft Server and retry if the operation is safe to repeat.",
+	HTTP_ERROR: "Read the Server's error code and adjust the request.",
+	INVALID_RESPONSE: "Upgrade the SDK or report the Server version; the response shape is not the one this SDK knows.",
+	CAPABILITY_NOT_AUTHORIZED: "Ask a human who can mint credentials to include the missing capability.",
+	SCOPE_DENIED: "Ask a human with editAgents authority to extend this agent's scopes.",
+	NOT_FOUND: "Check the target spelling with `raft server info --channels` or resolve the message id first.",
+	CONFLICT: "Read the current state before repeating this operation.",
+	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different message, or resend the identical payload to reconcile.",
+	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "Use your own runtime for this; the Server does not provide it to External Agents.",
+	UNAVAILABLE: "Retry in a moment."
+};
+const RETRYABLE = {
+	INVALID_REQUEST: false,
+	TRANSPORT_ERROR: true,
+	HTTP_ERROR: false,
+	INVALID_RESPONSE: false,
+	CAPABILITY_NOT_AUTHORIZED: false,
+	SCOPE_DENIED: false,
+	NOT_FOUND: false,
+	CONFLICT: false,
+	IDEMPOTENCY_KEY_REUSED: false,
+	UNSUPPORTED_FOR_EXTERNAL_AGENTS: false,
+	UNAVAILABLE: true
+};
+function classifyHttp(status, serverCode) {
+	const code = serverCode?.toLowerCase() ?? "";
+	if (code === "idempotency_key_reused") return "IDEMPOTENCY_KEY_REUSED";
+	if (code === "reminders_unsupported_for_external_agents") return "UNSUPPORTED_FOR_EXTERNAL_AGENTS";
+	if (code === "capability_not_authorized") return "CAPABILITY_NOT_AUTHORIZED";
+	if (code === "scope_denied") return "SCOPE_DENIED";
+	if (status === 404) return "NOT_FOUND";
+	if (status === 409) return "CONFLICT";
+	if (status === 503) return "UNAVAILABLE";
+	if (status >= 500) return "UNAVAILABLE";
+	return "HTTP_ERROR";
+}
+function opErrorFromClientError(error, status) {
+	if (error.kind === "transport") return {
+		code: "TRANSPORT_ERROR",
+		message: DEFAULT_MESSAGES.TRANSPORT_ERROR,
+		nextAction: DEFAULT_NEXT_ACTION.TRANSPORT_ERROR,
+		retryable: true
+	};
+	if (error.kind === "http") {
+		const serverCode = typeof error.errorCode === "string" && SERVER_ERROR_CODE.test(error.errorCode) ? error.errorCode : void 0;
+		const code = classifyHttp(error.status, serverCode);
+		const nextAction = typeof error.suggestedNextAction === "string" && error.suggestedNextAction.trim() ? error.suggestedNextAction.trim() : DEFAULT_NEXT_ACTION[code];
+		return {
+			code,
+			message: DEFAULT_MESSAGES[code],
+			status: error.status,
+			...serverCode ? { serverCode } : {},
+			nextAction,
+			retryable: RETRYABLE[code]
+		};
 	}
-	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must use HTTP or HTTPS");
-	if (parsed.username || parsed.password) throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must not contain credentials");
-	return serverUrl.replace(/\/+$/, "");
+	const code = error.reason === "request_contract_mismatch" || error.reason === "missing_path_param" || error.reason === "missing_route" ? "INVALID_REQUEST" : "INVALID_RESPONSE";
+	return {
+		code,
+		message: DEFAULT_MESSAGES[code],
+		...status === void 0 ? {} : { status },
+		nextAction: DEFAULT_NEXT_ACTION[code],
+		retryable: false
+	};
 }
-function requireAgentCredential(value) {
-	const credential = value.trim();
-	if (!credential) throw new RaftSdkConfigurationError("MISSING_AGENT_CREDENTIAL", "Raft Agent credential is required");
-	if (!credential.startsWith("sk_agent_") || credential.length === 9) throw new RaftSdkConfigurationError("INVALID_AGENT_CREDENTIAL", "Raft Agent credential must be a long-lived External Agent credential");
-	return credential;
+function opError(code, overrides = {}) {
+	return {
+		code,
+		message: DEFAULT_MESSAGES[code],
+		nextAction: DEFAULT_NEXT_ACTION[code],
+		retryable: RETRYABLE[code],
+		...overrides
+	};
 }
-/**
-* Create a typed client for the credential-derived `/internal/agent-api/*`
-* surface. The SDK does not read CLI profiles, environment variables, or the
-* host user's home directory: the caller chooses and supplies the credential.
-*/
-function createRaftClient(options) {
-	const serverUrl = requireServerUrl(options.serverUrl);
-	const auth = { authorization: `Bearer ${requireAgentCredential(options.credential)}` };
-	const messageClient = createAgentApiMessageClient({
-		baseUrl: serverUrl,
-		fetch: options.fetch,
-		headers: options.headers,
-		retry: options.retry,
-		throttle: options.throttle,
-		auth
-	});
-	const agentApi = createAgentApiClient({ fetch: {
-		baseUrl: serverUrl,
-		fetch: options.fetch,
-		headers: options.headers,
-		retry: { attempts: Math.min(Math.max(1, options.retry?.attempts ?? 1), 5) },
-		throttle: options.throttle,
-		auth
-	} });
-	const writeApi = createAgentApiClient({ fetch: {
-		baseUrl: serverUrl,
-		fetch: options.fetch,
-		headers: options.headers,
-		retry: { attempts: 1 },
-		throttle: options.throttle,
-		auth
-	} });
-	const eventsApi = createAgentApiClient({ fetch: {
-		baseUrl: serverUrl,
-		fetch: (input, init) => (options.fetch ?? fetch)(input, {
-			...init,
-			cache: "no-store",
-			redirect: "error"
-		}),
-		headers: Object.fromEntries(new Headers(options.headers)),
-		retry: { attempts: 1 },
-		throttle: options.throttle,
-		auth
-	} });
+/** Render an error the way an agent should read it: what failed, the code, and the next action. */
+function formatOpErrorText(error) {
+	const lines = [`Error: ${error.message}`, `Code: ${error.code}`];
+	if (error.serverCode) lines.push(`Server code: ${error.serverCode}`);
+	lines.push(`Retryable: ${error.retryable ? "yes" : "no"}`);
+	lines.push(`Next action: ${error.nextAction}`);
+	return lines.join("\n");
+}
+function failureOutcome(error) {
 	return {
-		...messageClient,
-		...createRaftManageClient(agentApi, writeApi, {
-			serverUrl,
-			fetch: options.fetch ?? fetch,
-			headers: Object.fromEntries(new Headers(options.headers)),
-			authorization: auth.authorization,
-			beforeRequest: options.throttle?.beforeRequest
-		}),
-		events: { receive: (request) => receiveRaftEvents(eventsApi, request) },
-		channels: { join: (request) => joinRaftChannelByTarget(agentApi, request) },
-		routes: createRaftRoutes({
-			serverUrl,
-			fetch: options.fetch,
-			headers: options.headers,
-			authorization: auth.authorization,
-			readAttempts: options.retry?.attempts,
-			beforeRequest: options.throttle?.beforeRequest
-		}),
-		agent: { context: () => getRaftContext(agentApi) }
+		ok: false,
+		state: "error",
+		error,
+		next: {
+			kind: "recover",
+			why: error.nextAction
+		},
+		text: formatOpErrorText(error)
 	};
 }
+/** Map a shared-client failure to a failure outcome. */
+function failureFromClientResult(result) {
+	return failureOutcome(opErrorFromClientError(result.error, result.status));
+}
 //#endregion
-//#region ../shared/src/clock.ts
-function currentTimeMs() {
-	return Date.now();
+//#region ../shared/src/agentInbox.ts
+const NON_MEMBER_MENTION_REPLY_GUIDANCE = "[Raft notice: You were notified as a non-member, so you cannot reply in that channel. If no reply is needed, no action is required. Otherwise, DM the person who mentioned you or join the channel to participate.]";
+function projectAgentReplyAffordance(facts) {
+	if (facts.non_member_mention !== true) return null;
+	return {
+		kind: "non_member_mention",
+		guidance: NON_MEMBER_MENTION_REPLY_GUIDANCE
+	};
 }
-function currentDate() {
-	return new Date(currentTimeMs());
+function formatAgentReplyAffordance(facts) {
+	return projectAgentReplyAffordance(facts)?.guidance ?? "";
+}
+function formatAgentReplyAffordanceSuffix(facts) {
+	const guidance = formatAgentReplyAffordance(facts);
+	return guidance ? `\n${guidance}` : "";
 }
 //#endregion
-//#region src/credential.ts
-var RaftCredentialError = class extends Error {
-	code;
-	name = "RaftCredentialError";
-	constructor(code, message) {
-		super(message);
-		this.code = code;
-	}
-};
-function isNonEmptyString(value) {
-	return typeof value === "string" && value.trim().length > 0;
+//#region ../shared/src/raftRefs.ts
+const RAFT_REF_CHANNEL_NAME_PATTERN = String.raw`[\p{L}\p{N}_-]+`;
+const RAFT_REF_USER_NAME_PATTERN = RAFT_REF_CHANNEL_NAME_PATTERN;
+const RAFT_REF_DM_PEER_PATTERN = String.raw`[\w.-]+(?:~(?:agent|human))?(?![\w.~-])`;
+const RAFT_REF_THREAD_SHORT_ID_PATTERN = String.raw`[\da-f]{6,8}`;
+const RAFT_REF_MESSAGE_ID_PATTERN = String.raw`[A-Za-z0-9][A-Za-z0-9-]{1,63}`;
+const RAFT_REF_TASK_NUMBER_PATTERN = String.raw`[1-9]\d*`;
+const RAFT_REF_COMPUTER_ID_PATTERN = String.raw`[\da-f]{8}-[\da-f]{4}-[1-5][\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}`;
+const RAFT_REF_APP_ID_PATTERN = String.raw`[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+`;
+function createRaftUserRefRegex() {
+	return new RegExp(`(^|[^\\p{L}\\p{N}_-])@(${RAFT_REF_USER_NAME_PATTERN})`, "gu");
 }
-function parseIdentityResponse(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-	const input = value;
-	if (!isNonEmptyString(input.agentId) || !isNonEmptyString(input.agentName) || input.agentDisplayName !== null && typeof input.agentDisplayName !== "string" || !isNonEmptyString(input.serverId) || !isNonEmptyString(input.credentialId) || !Array.isArray(input.scopes) || !input.scopes.every(isNonEmptyString)) return null;
-	return {
-		agentId: input.agentId,
-		agentName: input.agentName,
-		agentDisplayName: input.agentDisplayName,
-		serverId: input.serverId,
-		credentialId: input.credentialId,
-		scopes: [...input.scopes]
-	};
+function createRaftChannelThreadRefRegex() {
+	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})`, "giu");
 }
-function parseStoredRaftCredential(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-	const input = value;
-	if (input.schemaVersion !== 1 || !isNonEmptyString(input.serverUrl) || !isNonEmptyString(input.credential) || !isNonEmptyString(input.storedAt)) return null;
-	const identity = parseIdentityResponse(input);
-	if (!identity || Number.isNaN(Date.parse(input.storedAt))) return null;
-	let serverUrl;
-	let credential;
-	try {
-		serverUrl = requireServerUrl(input.serverUrl);
-		credential = requireAgentCredential(input.credential);
-	} catch {
-		return null;
-	}
-	return {
-		schemaVersion: 1,
-		serverUrl,
-		credential,
-		storedAt: input.storedAt,
-		...identity
-	};
+function createRaftChannelRefRegex() {
+	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN})`, "gu");
+}
+function createRaftDmThreadRefRegex() {
+	return new RegExp(`dm:@(${RAFT_REF_DM_PEER_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})`, "giu");
+}
+function createRaftDmRefRegex() {
+	return new RegExp(`dm:@(${RAFT_REF_DM_PEER_PATTERN})`, "giu");
 }
 /**
-* Validate an existing External Agent credential against Raft, derive its
-* bound identity from the credential-authenticated `whoami` surface, and save
-* it through the caller's explicit store. This does not mint or rotate a
-* credential and never returns the credential bytes.
+* A `dm:@name~<suffix>` token whose suffix is not a known peer kind
+* (`~bot`, `~agentXYZ`, a bare `~`). Renderers claim it as plain text so it
+* never degrades into a link to a different target (`dm:@name` or `@name`).
+* Run after the valid DM passes; it also matches valid refs.
 */
-async function bootstrapRaftCredential(options) {
-	const serverUrl = requireServerUrl(options.serverUrl);
-	const credential = requireAgentCredential(options.credential);
-	const httpFetch = options.fetch ?? globalThis.fetch;
-	let existing;
-	try {
-		existing = await options.store.load();
-	} catch {
-		throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential could not be checked before saving");
-	}
-	if (existing) {
-		const validatedExisting = parseStoredRaftCredential(existing);
-		if (!validatedExisting) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential record is invalid");
-		existing = validatedExisting;
-		if (existing.serverUrl !== serverUrl || existing.credential !== credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
-	}
-	let response;
-	try {
-		response = await httpFetch(`${serverUrl}/internal/agent-api/`, {
-			method: "GET",
-			headers: { authorization: `Bearer ${credential}` }
-		});
-	} catch {
-		throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", "Could not reach the Raft Server to verify the Agent credential");
-	}
-	if (!response.ok) {
-		if (response.status === 401 || response.status === 403) throw new RaftCredentialError("CREDENTIAL_REJECTED", "The Raft Server rejected the Agent credential");
-		throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", `The Raft Server could not verify the Agent credential (status ${response.status})`);
-	}
-	let payload;
-	try {
-		payload = await response.json();
-	} catch {
-		throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
-	}
-	const identity = parseIdentityResponse(payload);
-	if (!identity) throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
-	if (!identity.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The Raft Agent credential does not include the send capability required by this SDK");
-	if (existing && (existing.serverId !== identity.serverId || existing.agentId !== identity.agentId)) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store is already bound to a different Raft Agent identity");
-	if (existing) return {
-		serverUrl,
-		...identity
+function createRaftMalformedDmKindRefRegex() {
+	return new RegExp(String.raw`dm:@[\w.-]+~[\w.~-]*(?::${RAFT_REF_THREAD_SHORT_ID_PATTERN})?`, "giu");
+}
+function createRaftMessageRefRegex() {
+	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})`, "giu");
+}
+function createRaftBareTaskRefRegex() {
+	return new RegExp(`(^|[^\\w/])(?:(task\\s+))?#(${RAFT_REF_TASK_NUMBER_PATTERN})\\b`, "giu");
+}
+const USER_RE = new RegExp(String.raw`^@(${RAFT_REF_USER_NAME_PATTERN})$`, "u");
+const COMPUTER_RE = new RegExp(String.raw`^computer:(${RAFT_REF_COMPUTER_ID_PATTERN})$`, "iu");
+const APP_RE = new RegExp(String.raw`^app:(${RAFT_REF_APP_ID_PATTERN})$`, "u");
+const CHANNEL_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN})$`, "u");
+const CHANNEL_THREAD_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})$`, "iu");
+const DM_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN})$`, "iu");
+const DM_THREAD_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})$`, "iu");
+const TASK_RE = new RegExp(String.raw`^task\s+#(${RAFT_REF_TASK_NUMBER_PATTERN})$`, "iu");
+const CHANNEL_MESSAGE_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})$`, "iu");
+const DM_MESSAGE_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})$`, "iu");
+function parseRaftRefTarget(rawTarget) {
+	const target = rawTarget.trim();
+	if (!target) return null;
+	const channelMessage = CHANNEL_MESSAGE_RE.exec(target);
+	if (channelMessage) return {
+		kind: "message",
+		channelName: channelMessage[1],
+		threadParentShortId: channelMessage[2] ?? null,
+		messageId: channelMessage[3]
 	};
-	const record = {
-		schemaVersion: 1,
-		serverUrl,
-		credential,
-		storedAt: currentDate().toISOString(),
-		...identity
+	const dmMessage = DM_MESSAGE_RE.exec(target);
+	if (dmMessage) return {
+		kind: "dm-message",
+		peerName: dmMessage[1],
+		threadParentShortId: dmMessage[2] ?? null,
+		messageId: dmMessage[3]
 	};
-	try {
-		await options.store.save(record);
-	} catch (error) {
-		if (error instanceof RaftCredentialError && error.code === "CREDENTIAL_STORE_CONFLICT") throw error;
-		throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The verified Agent credential could not be saved");
-	}
-	return {
-		serverUrl,
-		...identity
+	const channelThread = CHANNEL_THREAD_RE.exec(target);
+	if (channelThread) return {
+		kind: "channel-thread",
+		channelName: channelThread[1],
+		threadShortId: channelThread[2]
+	};
+	const dmThread = DM_THREAD_RE.exec(target);
+	if (dmThread) return {
+		kind: "dm-thread",
+		peerName: dmThread[1],
+		threadShortId: dmThread[2]
+	};
+	const task = TASK_RE.exec(target);
+	if (task) return {
+		kind: "task",
+		taskNumber: Number(task[1])
+	};
+	const computer = COMPUTER_RE.exec(target);
+	if (computer) return {
+		kind: "computer",
+		machineId: computer[1].toLowerCase()
+	};
+	const app = APP_RE.exec(target);
+	if (app) return {
+		kind: "app",
+		appId: app[1]
+	};
+	const user = USER_RE.exec(target);
+	if (user) return {
+		kind: "user",
+		name: user[1]
+	};
+	const channel = CHANNEL_RE.exec(target);
+	if (channel) return {
+		kind: "channel",
+		channelName: channel[1]
+	};
+	const dm = DM_RE.exec(target);
+	if (dm) return {
+		kind: "dm",
+		peerName: dm[1]
 	};
+	return null;
 }
-/** Load the caller-selected credential store and create a normal Raft client. */
-async function createRaftClientFromStore(options) {
-	let record;
-	try {
-		record = await options.store.load();
-	} catch {
-		throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential could not be loaded");
+function formatRaftRefTarget(target) {
+	switch (target.kind) {
+		case "user": return `@${target.name}`;
+		case "computer": return `computer:${target.machineId}`;
+		case "app": return `app:${target.appId}`;
+		case "channel": return `#${target.channelName}`;
+		case "channel-thread": return `#${target.channelName}:${target.threadShortId}`;
+		case "dm": return `dm:@${target.peerName}`;
+		case "dm-thread": return `dm:@${target.peerName}:${target.threadShortId}`;
+		case "task": return `task #${target.taskNumber}`;
+		case "message": return target.threadParentShortId ? `#${target.channelName}:${target.threadParentShortId} msg=${target.messageId}` : `#${target.channelName} msg=${target.messageId}`;
+		case "dm-message": return target.threadParentShortId ? `dm:@${target.peerName}:${target.threadParentShortId} msg=${target.messageId}` : `dm:@${target.peerName} msg=${target.messageId}`;
 	}
-	if (!record) throw new RaftCredentialError("CREDENTIAL_NOT_FOUND", "No stored Raft Agent credential was found");
-	const validated = parseStoredRaftCredential(record);
-	if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential is invalid");
-	if (!validated.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The stored Raft Agent credential does not include the send capability required by this SDK");
-	return createRaftClient({
-		serverUrl: validated.serverUrl,
-		credential: validated.credential,
-		fetch: options.fetch,
-		headers: options.headers,
-		retry: options.retry,
-		throttle: options.throttle
+}
+function markdownCodeSpans(source) {
+	const spans = [];
+	for (const match of source.matchAll(/```[\s\S]*?```/g)) spans.push({
+		start: match.index ?? 0,
+		end: (match.index ?? 0) + match[0].length
 	});
-}
-//#endregion
-//#region src/fileCredentialStore.ts
-const MAX_CREDENTIAL_FILE_BYTES = 65536;
-/**
-* Create a Node.js credential store at one explicit absolute path. The SDK
-* never discovers CLI profiles or a home directory. Writes use a same-directory
-* temporary file followed by atomic rename, and the final file is mode 0600.
-*/
-function createFileCredentialStore(filePath) {
-	if (!filePath.trim() || !(0, node_path.isAbsolute)(filePath)) throw new RaftSdkConfigurationError("INVALID_CREDENTIAL_PATH", "Raft credential file path must be an explicit absolute path");
-	return {
-		load: () => loadFileCredential(filePath),
-		async save(record) {
-			const validated = parseStoredRaftCredential(record);
-			if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "Refusing to write an invalid Raft Agent credential record");
-			const directory = (0, node_path.dirname)(filePath);
-			const temporaryPath = `${filePath}.${process.pid}.${(0, node_crypto.randomUUID)()}.tmp`;
-			let handle;
-			try {
-				await (0, node_fs_promises.mkdir)(directory, {
-					recursive: true,
-					mode: 448
-				});
-				const existing = await loadFileCredential(filePath);
-				if (existing) {
-					assertSameCredential(existing, validated);
-					return;
-				}
-				handle = await (0, node_fs_promises.open)(temporaryPath, "wx", 384);
-				await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
-				await handle.sync();
-				await (0, node_fs_promises.chmod)(temporaryPath, 384);
-				await handle.close();
-				handle = void 0;
-				try {
-					await (0, node_fs_promises.link)(temporaryPath, filePath);
-				} catch (error) {
-					if (error.code !== "EEXIST") throw error;
-					const winner = await loadFileCredential(filePath);
-					if (!winner) throw error;
-					assertSameCredential(winner, validated);
-				}
-				await (0, node_fs_promises.unlink)(temporaryPath);
-			} catch (error) {
-				if (handle) await handle.close().catch(() => void 0);
-				await (0, node_fs_promises.unlink)(temporaryPath).catch(() => void 0);
-				if (error instanceof RaftCredentialError) throw error;
-				throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The Raft Agent credential could not be written atomically");
-			}
-		}
-	};
-}
-async function loadFileCredential(filePath) {
-	let initialMetadata;
-	try {
-		initialMetadata = await (0, node_fs_promises.lstat)(filePath);
-	} catch (error) {
-		if (error.code === "ENOENT") return null;
-		throw fileReadError();
-	}
-	if (!initialMetadata.isFile() || initialMetadata.isSymbolicLink() || initialMetadata.size > MAX_CREDENTIAL_FILE_BYTES) throw fileReadError();
-	let parsed;
-	let handle;
-	try {
-		const noFollow = process.platform === "win32" ? 0 : node_fs.constants.O_NOFOLLOW;
-		handle = await (0, node_fs_promises.open)(filePath, node_fs.constants.O_RDONLY | noFollow);
-		const openedMetadata = await handle.stat();
-		if (!openedMetadata.isFile() || openedMetadata.size > MAX_CREDENTIAL_FILE_BYTES || initialMetadata.dev !== openedMetadata.dev || initialMetadata.ino !== openedMetadata.ino) throw fileReadError();
-		if (process.platform !== "win32" && (openedMetadata.mode & 63) !== 0) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file permissions are too broad; expected mode 0600");
-		parsed = JSON.parse(await handle.readFile("utf8"));
-	} catch (error) {
-		if (error instanceof RaftCredentialError) throw error;
-		throw fileReadError();
-	} finally {
-		await handle?.close().catch(() => void 0);
-	}
-	const record = parseStoredRaftCredential(parsed);
-	if (!record) throw fileReadError();
-	return record;
-}
-function assertSameCredential(existing, candidate) {
-	if (existing.credential !== candidate.credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
-}
-function fileReadError() {
-	return new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file is invalid or unreadable");
-}
-//#endregion
-//#region ../shared/src/agentOps/outcome.ts
-const SERVER_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
-const DEFAULT_MESSAGES = {
-	INVALID_REQUEST: "The request did not match the Agent API contract; nothing was sent.",
-	TRANSPORT_ERROR: "The request did not reach the Raft Server.",
-	HTTP_ERROR: "The Raft Server rejected the request.",
-	INVALID_RESPONSE: "The Raft Server response did not match the Agent API contract.",
-	CAPABILITY_NOT_AUTHORIZED: "This credential does not carry the capability this operation needs.",
-	SCOPE_DENIED: "This agent's scope set does not allow this operation.",
-	NOT_FOUND: "The target or message does not exist or is not visible to this agent.",
-	CONFLICT: "The Raft Server refused the operation because of the current state.",
-	IDEMPOTENCY_KEY_REUSED: "This idempotency key was already used for a different message.",
-	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "This operation is not available to External Agents.",
-	UNAVAILABLE: "The Raft Server could not serve this operation right now."
-};
-const DEFAULT_NEXT_ACTION = {
-	INVALID_REQUEST: "Fix the request arguments; nothing was sent.",
-	TRANSPORT_ERROR: "Check connectivity to the Raft Server and retry if the operation is safe to repeat.",
-	HTTP_ERROR: "Read the Server's error code and adjust the request.",
-	INVALID_RESPONSE: "Upgrade the SDK or report the Server version; the response shape is not the one this SDK knows.",
-	CAPABILITY_NOT_AUTHORIZED: "Ask a human who can mint credentials to include the missing capability.",
-	SCOPE_DENIED: "Ask a human with editAgents authority to extend this agent's scopes.",
-	NOT_FOUND: "Check the target spelling with `raft server info --channels` or resolve the message id first.",
-	CONFLICT: "Read the current state before repeating this operation.",
-	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different message, or resend the identical payload to reconcile.",
-	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "Use your own runtime for this; the Server does not provide it to External Agents.",
-	UNAVAILABLE: "Retry in a moment."
-};
-const RETRYABLE = {
-	INVALID_REQUEST: false,
-	TRANSPORT_ERROR: true,
-	HTTP_ERROR: false,
-	INVALID_RESPONSE: false,
-	CAPABILITY_NOT_AUTHORIZED: false,
-	SCOPE_DENIED: false,
-	NOT_FOUND: false,
-	CONFLICT: false,
-	IDEMPOTENCY_KEY_REUSED: false,
-	UNSUPPORTED_FOR_EXTERNAL_AGENTS: false,
-	UNAVAILABLE: true
-};
-function classifyHttp(status, serverCode) {
-	const code = serverCode?.toLowerCase() ?? "";
-	if (code === "idempotency_key_reused") return "IDEMPOTENCY_KEY_REUSED";
-	if (code === "reminders_unsupported_for_external_agents") return "UNSUPPORTED_FOR_EXTERNAL_AGENTS";
-	if (code === "capability_not_authorized") return "CAPABILITY_NOT_AUTHORIZED";
-	if (code === "scope_denied") return "SCOPE_DENIED";
-	if (status === 404) return "NOT_FOUND";
-	if (status === 409) return "CONFLICT";
-	if (status === 503) return "UNAVAILABLE";
-	if (status >= 500) return "UNAVAILABLE";
-	return "HTTP_ERROR";
-}
-function opErrorFromClientError(error, status) {
-	if (error.kind === "transport") return {
-		code: "TRANSPORT_ERROR",
-		message: DEFAULT_MESSAGES.TRANSPORT_ERROR,
-		nextAction: DEFAULT_NEXT_ACTION.TRANSPORT_ERROR,
-		retryable: true
-	};
-	if (error.kind === "http") {
-		const serverCode = typeof error.errorCode === "string" && SERVER_ERROR_CODE.test(error.errorCode) ? error.errorCode : void 0;
-		const code = classifyHttp(error.status, serverCode);
-		const nextAction = typeof error.suggestedNextAction === "string" && error.suggestedNextAction.trim() ? error.suggestedNextAction.trim() : DEFAULT_NEXT_ACTION[code];
-		return {
-			code,
-			message: DEFAULT_MESSAGES[code],
-			status: error.status,
-			...serverCode ? { serverCode } : {},
-			nextAction,
-			retryable: RETRYABLE[code]
-		};
-	}
-	const code = error.reason === "request_contract_mismatch" || error.reason === "missing_path_param" || error.reason === "missing_route" ? "INVALID_REQUEST" : "INVALID_RESPONSE";
-	return {
-		code,
-		message: DEFAULT_MESSAGES[code],
-		...status === void 0 ? {} : { status },
-		nextAction: DEFAULT_NEXT_ACTION[code],
-		retryable: false
-	};
-}
-function opError(code, overrides = {}) {
-	return {
-		code,
-		message: DEFAULT_MESSAGES[code],
-		nextAction: DEFAULT_NEXT_ACTION[code],
-		retryable: RETRYABLE[code],
-		...overrides
-	};
-}
-/** Render an error the way an agent should read it: what failed, the code, and the next action. */
-function formatOpErrorText(error) {
-	const lines = [`Error: ${error.message}`, `Code: ${error.code}`];
-	if (error.serverCode) lines.push(`Server code: ${error.serverCode}`);
-	lines.push(`Retryable: ${error.retryable ? "yes" : "no"}`);
-	lines.push(`Next action: ${error.nextAction}`);
-	return lines.join("\n");
-}
-function failureOutcome(error) {
-	return {
-		ok: false,
-		state: "error",
-		error,
-		next: {
-			kind: "recover",
-			why: error.nextAction
-		},
-		text: formatOpErrorText(error)
-	};
-}
-/** Map a shared-client failure to a failure outcome. */
-function failureFromClientResult(result) {
-	return failureOutcome(opErrorFromClientError(result.error, result.status));
-}
-//#endregion
-//#region ../shared/src/agentInbox.ts
-const NON_MEMBER_MENTION_REPLY_GUIDANCE = "[Raft notice: You were notified as a non-member, so you cannot reply in that channel. If no reply is needed, no action is required. Otherwise, DM the person who mentioned you or join the channel to participate.]";
-function projectAgentReplyAffordance(facts) {
-	if (facts.non_member_mention !== true) return null;
-	return {
-		kind: "non_member_mention",
-		guidance: NON_MEMBER_MENTION_REPLY_GUIDANCE
-	};
-}
-function formatAgentReplyAffordance(facts) {
-	return projectAgentReplyAffordance(facts)?.guidance ?? "";
-}
-function formatAgentReplyAffordanceSuffix(facts) {
-	const guidance = formatAgentReplyAffordance(facts);
-	return guidance ? `\n${guidance}` : "";
-}
-//#endregion
-//#region ../shared/src/raftRefs.ts
-const RAFT_REF_CHANNEL_NAME_PATTERN = String.raw`[\p{L}\p{N}_-]+`;
-const RAFT_REF_USER_NAME_PATTERN = RAFT_REF_CHANNEL_NAME_PATTERN;
-const RAFT_REF_DM_PEER_PATTERN = String.raw`[\w.-]+(?:~(?:agent|human))?(?![\w.~-])`;
-const RAFT_REF_THREAD_SHORT_ID_PATTERN = String.raw`[\da-f]{6,8}`;
-const RAFT_REF_MESSAGE_ID_PATTERN = String.raw`[A-Za-z0-9][A-Za-z0-9-]{1,63}`;
-const RAFT_REF_TASK_NUMBER_PATTERN = String.raw`[1-9]\d*`;
-const RAFT_REF_COMPUTER_ID_PATTERN = String.raw`[\da-f]{8}-[\da-f]{4}-[1-5][\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}`;
-const RAFT_REF_APP_ID_PATTERN = String.raw`[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+`;
-function createRaftUserRefRegex() {
-	return new RegExp(`(^|[^\\p{L}\\p{N}_-])@(${RAFT_REF_USER_NAME_PATTERN})`, "gu");
-}
-function createRaftChannelThreadRefRegex() {
-	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})`, "giu");
-}
-function createRaftChannelRefRegex() {
-	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN})`, "gu");
-}
-function createRaftDmThreadRefRegex() {
-	return new RegExp(`dm:@(${RAFT_REF_DM_PEER_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})`, "giu");
-}
-function createRaftDmRefRegex() {
-	return new RegExp(`dm:@(${RAFT_REF_DM_PEER_PATTERN})`, "giu");
-}
-/**
-* A `dm:@name~<suffix>` token whose suffix is not a known peer kind
-* (`~bot`, `~agentXYZ`, a bare `~`). Renderers claim it as plain text so it
-* never degrades into a link to a different target (`dm:@name` or `@name`).
-* Run after the valid DM passes; it also matches valid refs.
-*/
-function createRaftMalformedDmKindRefRegex() {
-	return new RegExp(String.raw`dm:@[\w.-]+~[\w.~-]*(?::${RAFT_REF_THREAD_SHORT_ID_PATTERN})?`, "giu");
-}
-function createRaftMessageRefRegex() {
-	return new RegExp(`#(${RAFT_REF_CHANNEL_NAME_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})`, "giu");
-}
-function createRaftBareTaskRefRegex() {
-	return new RegExp(`(^|[^\\w/])(?:(task\\s+))?#(${RAFT_REF_TASK_NUMBER_PATTERN})\\b`, "giu");
-}
-const USER_RE = new RegExp(String.raw`^@(${RAFT_REF_USER_NAME_PATTERN})$`, "u");
-const COMPUTER_RE = new RegExp(String.raw`^computer:(${RAFT_REF_COMPUTER_ID_PATTERN})$`, "iu");
-const APP_RE = new RegExp(String.raw`^app:(${RAFT_REF_APP_ID_PATTERN})$`, "u");
-const CHANNEL_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN})$`, "u");
-const CHANNEL_THREAD_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})$`, "iu");
-const DM_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN})$`, "iu");
-const DM_THREAD_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN}):(${RAFT_REF_THREAD_SHORT_ID_PATTERN})$`, "iu");
-const TASK_RE = new RegExp(String.raw`^task\s+#(${RAFT_REF_TASK_NUMBER_PATTERN})$`, "iu");
-const CHANNEL_MESSAGE_RE = new RegExp(String.raw`^#(${RAFT_REF_CHANNEL_NAME_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})$`, "iu");
-const DM_MESSAGE_RE = new RegExp(String.raw`^dm:@(${RAFT_REF_DM_PEER_PATTERN})(?::(${RAFT_REF_THREAD_SHORT_ID_PATTERN}))?\s+msg=(${RAFT_REF_MESSAGE_ID_PATTERN})$`, "iu");
-function parseRaftRefTarget(rawTarget) {
-	const target = rawTarget.trim();
-	if (!target) return null;
-	const channelMessage = CHANNEL_MESSAGE_RE.exec(target);
-	if (channelMessage) return {
-		kind: "message",
-		channelName: channelMessage[1],
-		threadParentShortId: channelMessage[2] ?? null,
-		messageId: channelMessage[3]
-	};
-	const dmMessage = DM_MESSAGE_RE.exec(target);
-	if (dmMessage) return {
-		kind: "dm-message",
-		peerName: dmMessage[1],
-		threadParentShortId: dmMessage[2] ?? null,
-		messageId: dmMessage[3]
-	};
-	const channelThread = CHANNEL_THREAD_RE.exec(target);
-	if (channelThread) return {
-		kind: "channel-thread",
-		channelName: channelThread[1],
-		threadShortId: channelThread[2]
-	};
-	const dmThread = DM_THREAD_RE.exec(target);
-	if (dmThread) return {
-		kind: "dm-thread",
-		peerName: dmThread[1],
-		threadShortId: dmThread[2]
-	};
-	const task = TASK_RE.exec(target);
-	if (task) return {
-		kind: "task",
-		taskNumber: Number(task[1])
-	};
-	const computer = COMPUTER_RE.exec(target);
-	if (computer) return {
-		kind: "computer",
-		machineId: computer[1].toLowerCase()
-	};
-	const app = APP_RE.exec(target);
-	if (app) return {
-		kind: "app",
-		appId: app[1]
-	};
-	const user = USER_RE.exec(target);
-	if (user) return {
-		kind: "user",
-		name: user[1]
-	};
-	const channel = CHANNEL_RE.exec(target);
-	if (channel) return {
-		kind: "channel",
-		channelName: channel[1]
-	};
-	const dm = DM_RE.exec(target);
-	if (dm) return {
-		kind: "dm",
-		peerName: dm[1]
-	};
-	return null;
-}
-function formatRaftRefTarget(target) {
-	switch (target.kind) {
-		case "user": return `@${target.name}`;
-		case "computer": return `computer:${target.machineId}`;
-		case "app": return `app:${target.appId}`;
-		case "channel": return `#${target.channelName}`;
-		case "channel-thread": return `#${target.channelName}:${target.threadShortId}`;
-		case "dm": return `dm:@${target.peerName}`;
-		case "dm-thread": return `dm:@${target.peerName}:${target.threadShortId}`;
-		case "task": return `task #${target.taskNumber}`;
-		case "message": return target.threadParentShortId ? `#${target.channelName}:${target.threadParentShortId} msg=${target.messageId}` : `#${target.channelName} msg=${target.messageId}`;
-		case "dm-message": return target.threadParentShortId ? `dm:@${target.peerName}:${target.threadParentShortId} msg=${target.messageId}` : `dm:@${target.peerName} msg=${target.messageId}`;
-	}
-}
-function markdownCodeSpans(source) {
-	const spans = [];
-	for (const match of source.matchAll(/```[\s\S]*?```/g)) spans.push({
-		start: match.index ?? 0,
-		end: (match.index ?? 0) + match[0].length
-	});
-	const fences = [...spans];
-	const scanInline = (from, to) => {
-		if (from >= to) return;
-		const segment = source.slice(from, to);
-		for (const match of segment.matchAll(/``[^`]+``|`[^`]+`/g)) {
-			const start = from + (match.index ?? 0);
-			spans.push({
-				start,
-				end: start + match[0].length
-			});
-		}
-	};
-	let cursor = 0;
-	for (const fence of fences) {
-		scanInline(cursor, fence.start);
-		cursor = fence.end;
-	}
-	scanInline(cursor, source.length);
-	return spans.sort((a, b) => a.start - b.start);
+	const fences = [...spans];
+	const scanInline = (from, to) => {
+		if (from >= to) return;
+		const segment = source.slice(from, to);
+		for (const match of segment.matchAll(/``[^`]+``|`[^`]+`/g)) {
+			const start = from + (match.index ?? 0);
+			spans.push({
+				start,
+				end: start + match[0].length
+			});
+		}
+	};
+	let cursor = 0;
+	for (const fence of fences) {
+		scanInline(cursor, fence.start);
+		cursor = fence.end;
+	}
+	scanInline(cursor, source.length);
+	return spans.sort((a, b) => a.start - b.start);
 }
 function visitMarkdownProseChunks(source, visitor) {
 	const spans = markdownCodeSpans(source);
@@ -10966,34 +10721,9 @@ function unreadMessagesInterrupt(input) {
 		contextComplete: !withheld && heldMessages.length + omittedMessageCount >= newMessageCount
 	};
 }
-/** `raft message send --send-draft` for the draft a held send saved, under its original key. */
-function sendDraftResume(target, idempotencyKey, extraArgv = []) {
-	return {
-		argv: [
-			"message",
-			"send",
-			"--send-draft",
-			"--target",
-			target,
-			"--expected-draft-key",
-			idempotencyKey,
-			...extraArgv
-		],
-		idempotencyKey
-	};
-}
-/** `raft message send --discard-draft` for the draft a held send saved (compare-and-clear on its key). */
-function discardDraftCancel(target, idempotencyKey, extraArgv = []) {
-	return { argv: [
-		"message",
-		"send",
-		"--discard-draft",
-		"--target",
-		target,
-		"--expected-draft-key",
-		idempotencyKey,
-		...extraArgv
-	] };
+/** Resume of an in-process SDK send: no argv (the SDK stores no draft), only the original key to call again with. */
+function inProcessSendResume(idempotencyKey) {
+	return { idempotencyKey };
 }
 /** `raft task claim` argv for a claim request (resume of a held claim). */
 function taskClaimArgv(target, taskNumbers, messageIds, extraArgv = []) {
@@ -11555,7 +11285,7 @@ async function sendMessage(client, request, frontier) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", sendDraftResume(request.target, idempotencyKey), discardDraftCancel(request.target, idempotencyKey));
+		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey));
 		return {
 			ok: true,
 			state: "interrupted",
@@ -13484,532 +13214,872 @@ async function resolveMessage(client, request) {
 		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 });
+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 verb = action === "add" ? "added to" : "removed from";
+	const results = normalizeAgentMentionActionResults(result.data);
 	return {
 		ok: true,
-		state: action === "add" ? "added" : "removed",
+		state: "executed",
 		data: {
-			messageId: request.messageId,
-			emoji
+			action: request.action,
+			results
 		},
 		next: null,
-		text: `Reaction ${emoji} ${verb} message ${request.messageId.slice(0, 8)}.`
+		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/mentions.ts
-function normalizeAgentMentionAction(action) {
-	if (action === "notify" || action === "notify_only") return "notify";
-	if (action === "add" || action === "invite") return "add";
-	return null;
+//#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 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 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 formatAuthoredMentionToken(targetHandle) {
-	return targetHandle.startsWith("@") ? targetHandle : `@${targetHandle}`;
+function formatAgentKnowledgeStdout(content) {
+	return content.endsWith("\n") ? content : `${content}\n`;
 }
-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;
+//#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;
 }
-function toAgentSenderPendingMentionAction(action) {
+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 {
-		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)
+		ok: true,
+		state: "topic",
+		data: result.data,
+		next: null,
+		text: formatAgentKnowledgeStdout(result.data.content)
 	};
 }
-function toAgentSenderUnresolvedMentionWarning(targetHandle) {
+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 {
-		targetHandle: formatAuthoredMentionToken(targetHandle),
-		status: "not_queued",
-		reason: "unknown_or_not_visible",
-		consequence: "This @mention did not notify anyone.",
-		expiresAt: null,
-		recoveryCommand: null
+		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"
 	};
 }
-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);
+//#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;
 }
-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);
+/** 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
+	};
 }
-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`;
+/** 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("");
 }
-/** 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`;
+/**
+* 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;
 	}
-	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.");
-		}
+	/** 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;
 	}
-	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`;
+	markDirty() {
+		this.dirty = true;
 	}
-	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(", ")}`);
+	/** 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;
 	}
-	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";
+	/**
+	* 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 ../shared/src/agentOps/actions.ts
+/** Text is the CLI's `raft action prepare` output. */
+function formatAgentActionCardPosted(target, messageId) {
+	const shortId = messageId ? messageId.slice(0, 8) : null;
+	return shortId ? `Action card posted to ${target} as message ${messageId} (short ${shortId}). The human can click the action verb to commit.\n` : `Action card posted to ${target}.\n`;
 }
-/** 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`;
+async function prepareActionCard(client, request) {
+	if (!request?.target?.trim() || !request.action) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and an action are required to prepare a card." }));
+	const result = await client.actions.prepare(request);
+	if (!result.ok) return failureFromClientResult(result);
+	const card = {
+		target: request.target,
+		messageId: result.data.messageId
+	};
+	return {
+		ok: true,
+		state: "prepared",
+		data: card,
+		next: {
+			kind: "await_confirmation",
+			command: `raft message read --target "${request.target}" --around ${card.messageId.slice(0, 8)}`,
+			args: {
+				target: request.target,
+				messageId: card.messageId
+			},
+			why: "A human must click the card to commit it. You are not notified of the result yet; read the card message to see its state instead of waiting."
+		},
+		text: formatAgentActionCardPosted(request.target, card.messageId)
+	};
 }
 //#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) });
+//#region src/command.ts
+/** Run one `raft` command on the Server for the agent this credential belongs to. */
+async function runCommand(routes, request) {
+	const result = await routes.request("agentCommand", { body: request });
 	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
-		})
+		exitCode: result.data.exitCode,
+		text: result.data.text,
+		outcome: result.data.outcome
 	};
 }
-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
+//#endregion
+//#region src/client.ts
+var RaftSdkConfigurationError = class extends Error {
+	code;
+	name = "RaftSdkConfigurationError";
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function requireServerUrl(value) {
+	const serverUrl = value.trim();
+	if (!serverUrl) throw new RaftSdkConfigurationError("MISSING_SERVER_URL", "Raft Server URL is required");
+	let parsed;
+	try {
+		parsed = new URL(serverUrl);
+	} catch {
+		throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must be an absolute HTTP(S) URL");
+	}
+	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must use HTTP or HTTPS");
+	if (parsed.username || parsed.password) throw new RaftSdkConfigurationError("INVALID_SERVER_URL", "Raft Server URL must not contain credentials");
+	return serverUrl.replace(/\/+$/, "");
+}
+function requireAgentCredential(value) {
+	const credential = value.trim();
+	if (!credential) throw new RaftSdkConfigurationError("MISSING_AGENT_CREDENTIAL", "Raft Agent credential is required");
+	if (!credential.startsWith("sk_agent_") || credential.length === 9) throw new RaftSdkConfigurationError("INVALID_AGENT_CREDENTIAL", "Raft Agent credential must be a long-lived External Agent credential");
+	return credential;
+}
+/**
+* Create a typed client for the credential-derived `/internal/agent-api/*`
+* surface. The SDK does not read CLI profiles, environment variables, or the
+* host user's home directory: the caller chooses and supplies the credential.
+*/
+function createRaftClient(options) {
+	const serverUrl = requireServerUrl(options.serverUrl);
+	const auth = { authorization: `Bearer ${requireAgentCredential(options.credential)}` };
+	const messageClient = createAgentApiMessageClient({
+		baseUrl: serverUrl,
+		fetch: options.fetch,
+		headers: options.headers,
+		retry: options.retry,
+		throttle: options.throttle,
+		auth
+	});
+	const agentApi = createAgentApiClient({ fetch: {
+		baseUrl: serverUrl,
+		fetch: options.fetch,
+		headers: options.headers,
+		retry: { attempts: Math.min(Math.max(1, options.retry?.attempts ?? 1), 5) },
+		throttle: options.throttle,
+		auth
+	} });
+	const writeApi = createAgentApiClient({ fetch: {
+		baseUrl: serverUrl,
+		fetch: options.fetch,
+		headers: options.headers,
+		retry: { attempts: 1 },
+		throttle: options.throttle,
+		auth
+	} });
+	const eventsApi = createAgentApiClient({ fetch: {
+		baseUrl: serverUrl,
+		fetch: (input, init) => (options.fetch ?? fetch)(input, {
+			...init,
+			cache: "no-store",
+			redirect: "error"
+		}),
+		headers: Object.fromEntries(new Headers(options.headers)),
+		retry: { attempts: 1 },
+		throttle: options.throttle,
+		auth
+	} });
+	const routes = createRaftRoutes({
+		serverUrl,
+		fetch: options.fetch,
+		headers: options.headers,
+		authorization: auth.authorization,
+		readAttempts: options.retry?.attempts,
+		beforeRequest: options.throttle?.beforeRequest
 	});
-	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)
+		...messageClient,
+		...createRaftManageClient(agentApi, writeApi, {
+			serverUrl,
+			fetch: options.fetch ?? fetch,
+			headers: Object.fromEntries(new Headers(options.headers)),
+			authorization: auth.authorization,
+			beforeRequest: options.throttle?.beforeRequest
+		}),
+		events: { receive: (request) => receiveRaftEvents(eventsApi, request) },
+		channels: { join: (request) => joinRaftChannelByTarget(agentApi, request) },
+		routes,
+		runCommand: (request) => runCommand(routes, request),
+		agent: { context: () => getRaftContext(agentApi) }
 	};
 }
 //#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";
+//#region ../shared/src/clock.ts
+function currentTimeMs() {
+	return Date.now();
 }
-function formatAgentKnowledgeStdout(content) {
-	return content.endsWith("\n") ? content : `${content}\n`;
+function currentDate() {
+	return new Date(currentTimeMs());
 }
 //#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;
+//#region src/credential.ts
+var RaftCredentialError = class extends Error {
+	code;
+	name = "RaftCredentialError";
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
 }
-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);
+function parseIdentityResponse(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const input = value;
+	if (!isNonEmptyString(input.agentId) || !isNonEmptyString(input.agentName) || input.agentDisplayName !== null && typeof input.agentDisplayName !== "string" || !isNonEmptyString(input.serverId) || !isNonEmptyString(input.credentialId) || !Array.isArray(input.scopes) || !input.scopes.every(isNonEmptyString)) return null;
 	return {
-		ok: true,
-		state: "topic",
-		data: result.data,
-		next: null,
-		text: formatAgentKnowledgeStdout(result.data.content)
+		agentId: input.agentId,
+		agentName: input.agentName,
+		agentDisplayName: input.agentDisplayName,
+		serverId: input.serverId,
+		credentialId: input.credentialId,
+		scopes: [...input.scopes]
 	};
 }
-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;
+function parseStoredRaftCredential(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const input = value;
+	if (input.schemaVersion !== 1 || !isNonEmptyString(input.serverUrl) || !isNonEmptyString(input.credential) || !isNonEmptyString(input.storedAt)) return null;
+	const identity = parseIdentityResponse(input);
+	if (!identity || Number.isNaN(Date.parse(input.storedAt))) return null;
+	let serverUrl;
+	let credential;
+	try {
+		serverUrl = requireServerUrl(input.serverUrl);
+		credential = requireAgentCredential(input.credential);
+	} catch {
+		return 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"
+		schemaVersion: 1,
+		serverUrl,
+		credential,
+		storedAt: input.storedAt,
+		...identity
 	};
 }
-//#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
+/**
+* Validate an existing External Agent credential against Raft, derive its
+* bound identity from the credential-authenticated `whoami` surface, and save
+* it through the caller's explicit store. This does not mint or rotate a
+* credential and never returns the credential bytes.
+*/
+async function bootstrapRaftCredential(options) {
+	const serverUrl = requireServerUrl(options.serverUrl);
+	const credential = requireAgentCredential(options.credential);
+	const httpFetch = options.fetch ?? globalThis.fetch;
+	let existing;
+	try {
+		existing = await options.store.load();
+	} catch {
+		throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential could not be checked before saving");
+	}
+	if (existing) {
+		const validatedExisting = parseStoredRaftCredential(existing);
+		if (!validatedExisting) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential record is invalid");
+		existing = validatedExisting;
+		if (existing.serverUrl !== serverUrl || existing.credential !== credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+	}
+	let response;
+	try {
+		response = await httpFetch(`${serverUrl}/internal/agent-api/`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${credential}` }
+		});
+	} catch {
+		throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", "Could not reach the Raft Server to verify the Agent credential");
+	}
+	if (!response.ok) {
+		if (response.status === 401 || response.status === 403) throw new RaftCredentialError("CREDENTIAL_REJECTED", "The Raft Server rejected the Agent credential");
+		throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", `The Raft Server could not verify the Agent credential (status ${response.status})`);
+	}
+	let payload;
+	try {
+		payload = await response.json();
+	} catch {
+		throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+	}
+	const identity = parseIdentityResponse(payload);
+	if (!identity) throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+	if (!identity.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The Raft Agent credential does not include the send capability required by this SDK");
+	if (existing && (existing.serverId !== identity.serverId || existing.agentId !== identity.agentId)) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store is already bound to a different Raft Agent identity");
+	if (existing) return {
+		serverUrl,
+		...identity
+	};
+	const record = {
+		schemaVersion: 1,
+		serverUrl,
+		credential,
+		storedAt: currentDate().toISOString(),
+		...identity
+	};
+	try {
+		await options.store.save(record);
+	} catch (error) {
+		if (error instanceof RaftCredentialError && error.code === "CREDENTIAL_STORE_CONFLICT") throw error;
+		throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The verified Agent credential could not be saved");
+	}
+	return {
+		serverUrl,
+		...identity
 	};
 }
-/** 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("");
+/** Load the caller-selected credential store and create a normal Raft client. */
+async function createRaftClientFromStore(options) {
+	let record;
+	try {
+		record = await options.store.load();
+	} catch {
+		throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential could not be loaded");
+	}
+	if (!record) throw new RaftCredentialError("CREDENTIAL_NOT_FOUND", "No stored Raft Agent credential was found");
+	const validated = parseStoredRaftCredential(record);
+	if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential is invalid");
+	if (!validated.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The stored Raft Agent credential does not include the send capability required by this SDK");
+	return createRaftClient({
+		serverUrl: validated.serverUrl,
+		credential: validated.credential,
+		fetch: options.fetch,
+		headers: options.headers,
+		retry: options.retry,
+		throttle: options.throttle
+	});
 }
+//#endregion
+//#region src/fileCredentialStore.ts
+const MAX_CREDENTIAL_FILE_BYTES = 65536;
 /**
-* 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.
+* Create a Node.js credential store at one explicit absolute path. The SDK
+* never discovers CLI profiles or a home directory. Writes use a same-directory
+* temporary file followed by atomic rename, and the final file is mode 0600.
 */
-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;
+function createFileCredentialStore(filePath) {
+	if (!filePath.trim() || !(0, node_path.isAbsolute)(filePath)) throw new RaftSdkConfigurationError("INVALID_CREDENTIAL_PATH", "Raft credential file path must be an explicit absolute path");
+	return {
+		load: () => loadFileCredential(filePath),
+		async save(record) {
+			const validated = parseStoredRaftCredential(record);
+			if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "Refusing to write an invalid Raft Agent credential record");
+			const directory = (0, node_path.dirname)(filePath);
+			const temporaryPath = `${filePath}.${process.pid}.${(0, node_crypto.randomUUID)()}.tmp`;
+			let handle;
 			try {
-				raw = await this.store.load();
-			} catch (error) {
-				this.onError?.(error, {
-					phase: "load",
-					version: void 0
+				await (0, node_fs_promises.mkdir)(directory, {
+					recursive: true,
+					mode: 448
 				});
-				return;
+				const existing = await loadFileCredential(filePath);
+				if (existing) {
+					assertSameCredential(existing, validated);
+					return;
+				}
+				handle = await (0, node_fs_promises.open)(temporaryPath, "wx", 384);
+				await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+				await handle.sync();
+				await (0, node_fs_promises.chmod)(temporaryPath, 384);
+				await handle.close();
+				handle = void 0;
+				try {
+					await (0, node_fs_promises.link)(temporaryPath, filePath);
+				} catch (error) {
+					if (error.code !== "EEXIST") throw error;
+					const winner = await loadFileCredential(filePath);
+					if (!winner) throw error;
+					assertSameCredential(winner, validated);
+				}
+				await (0, node_fs_promises.unlink)(temporaryPath);
+			} catch (error) {
+				if (handle) await handle.close().catch(() => void 0);
+				await (0, node_fs_promises.unlink)(temporaryPath).catch(() => void 0);
+				if (error instanceof RaftCredentialError) throw error;
+				throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The Raft Agent credential could not be written atomically");
 			}
-			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;
+	};
+}
+async function loadFileCredential(filePath) {
+	let initialMetadata;
+	try {
+		initialMetadata = await (0, node_fs_promises.lstat)(filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw fileReadError();
 	}
-};
-//#endregion
-//#region ../shared/src/agentOps/actions.ts
-/** Text is the CLI's `raft action prepare` output. */
-function formatAgentActionCardPosted(target, messageId) {
-	const shortId = messageId ? messageId.slice(0, 8) : null;
-	return shortId ? `Action card posted to ${target} as message ${messageId} (short ${shortId}). The human can click the action verb to commit.\n` : `Action card posted to ${target}.\n`;
+	if (!initialMetadata.isFile() || initialMetadata.isSymbolicLink() || initialMetadata.size > MAX_CREDENTIAL_FILE_BYTES) throw fileReadError();
+	let parsed;
+	let handle;
+	try {
+		const noFollow = process.platform === "win32" ? 0 : node_fs.constants.O_NOFOLLOW;
+		handle = await (0, node_fs_promises.open)(filePath, node_fs.constants.O_RDONLY | noFollow);
+		const openedMetadata = await handle.stat();
+		if (!openedMetadata.isFile() || openedMetadata.size > MAX_CREDENTIAL_FILE_BYTES || initialMetadata.dev !== openedMetadata.dev || initialMetadata.ino !== openedMetadata.ino) throw fileReadError();
+		if (process.platform !== "win32" && (openedMetadata.mode & 63) !== 0) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file permissions are too broad; expected mode 0600");
+		parsed = JSON.parse(await handle.readFile("utf8"));
+	} catch (error) {
+		if (error instanceof RaftCredentialError) throw error;
+		throw fileReadError();
+	} finally {
+		await handle?.close().catch(() => void 0);
+	}
+	const record = parseStoredRaftCredential(parsed);
+	if (!record) throw fileReadError();
+	return record;
 }
-async function prepareActionCard(client, request) {
-	if (!request?.target?.trim() || !request.action) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and an action are required to prepare a card." }));
-	const result = await client.actions.prepare(request);
-	if (!result.ok) return failureFromClientResult(result);
-	const card = {
-		target: request.target,
-		messageId: result.data.messageId
-	};
-	return {
-		ok: true,
-		state: "prepared",
-		data: card,
-		next: {
-			kind: "await_confirmation",
-			command: `raft message read --target "${request.target}" --around ${card.messageId.slice(0, 8)}`,
-			args: {
-				target: request.target,
-				messageId: card.messageId
-			},
-			why: "A human must click the card to commit it. You are not notified of the result yet; read the card message to see its state instead of waiting."
-		},
-		text: formatAgentActionCardPosted(request.target, card.messageId)
-	};
+function assertSameCredential(existing, candidate) {
+	if (existing.credential !== candidate.credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+}
+function fileReadError() {
+	return new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file is invalid or unreadable");
 }
 //#endregion
 //#region src/latestReadThread.ts
@@ -14243,7 +14313,8 @@ function createRaft(options) {
 			load: () => session.ensureLoaded(),
 			snapshot: () => session.snapshot(session.version ?? 0)
 		},
-		routes
+		routes,
+		runCommand: (request) => runCommand(routes, request)
 	};
 }
 //#endregion
@@ -14274,4 +14345,5 @@ exports.parseRaftState = parseRaftState;
 exports.projectRaftMessage = projectRaftMessage;
 exports.projectRaftMessages = projectRaftMessages;
 exports.readLatestReadThread = readLatestReadThread;
+exports.runCommand = runCommand;
 exports.verifyInboxNotice = verifyInboxNotice;