@botiverse/raft-sdk 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -58,6 +58,52 @@ export async function onStep(state: Stored) {
 await raft.messages.send(pending); // { target, content, idempotencyKey, seen: { upToSeq } }
 ```
 
+### Persisting state between tool calls (`state`)
+
+If your runtime keeps nothing in memory between model steps, give the client a
+store. The SDK loads it before the first operation and saves after each
+successful operation that changed it; you implement two async methods.
+
+```ts
+const raft = createRaft({ serverUrl, credential, state: store });
+
+await raft.inbox.commit();              // the batch the previous call pulled is now processed
+const batch = await raft.inbox.check(); // acknowledges it on the Server, returns the next batch
+// … hand batch.data.messages to the model …
+```
+
+- `inbox.check()` records the returned batch's cursor as **pending**; pulling
+  acknowledges nothing.
+- `inbox.commit()` promotes the pending cursor to **committed** (also accepts
+  `{ cursor }`). The next `check()` sends it as `since`, which is what
+  acknowledges that batch. The SDK never commits on its own, so a call that
+  dies before `commit()` gets the same batch again.
+- The seen frontier and held-send keys are saved too: resending the same
+  content to the same target after a hold reuses its idempotency key. After a
+  hold, `raft.frontier.recordHeld(held.data)` then `await raft.state.save()`.
+- Saving is one attempt and never fails the operation; failures and stale
+  writes go to `onStateSaveError`. Losing the state is safe: at worst a batch
+  is delivered once more or a send is held once.
+
+The state is one small versioned JSON value:
+`{ schema: "raft-sdk-state.v1", version, cursor, pendingCursor, frontier, continuations }`.
+`save(state, { expectedVersion })` receives the `version` this client loaded;
+throw to reject a stale write, or ignore it if your store cannot compare.
+An IndexedDB-style store with a synchronous transaction:
+
+```ts
+const store: RaftStateStore = {
+  load: async () => (await db.get("inbox", "state")) ?? null,
+  save: async (state, { expectedVersion }) => {
+    await db.transaction("inbox", "readwrite", (tx) => {
+      const cur = tx.get("inbox", "state") as { version?: number } | undefined;
+      if (cur?.version !== expectedVersion) throw new Error("stale");
+      tx.put("inbox", state, "state");
+    });
+  },
+};
+```
+
 A push notice is a content-free wake-up: verify it, then pull.
 
 ```ts
@@ -101,10 +147,13 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
 - `raft.messages.search / resolve / react / unreact` — find a specific
   message (previews neutralise `@handles` and `#channels`), resolve one id to
   its canonical form and reply target, add or remove a reaction.
-- `raft.attachments.upload({ target, filename, bytes })` — small-file multipart
-  upload (the target is resolved to a channel id first); files at or above the
-  Server's direct-upload threshold are refused with a next action pointing at
-  the upload-session routes. `download`, `comments`.
+- `raft.attachments.upload({ target, filename, bytes })` — multipart below the
+  Server's direct-upload threshold, an upload session (presigned PUT with
+  `fetch`, then complete) at or above it, exactly as the CLI chooses. The
+  target is resolved to a channel id first. `download`, `comments`.
+- `raft.actions.prepare({ target, action })` — post an action card
+  (`channel:create`, `channel:add_member`, `agent:create`, integration cards)
+  for a human to confirm; the human who clicks it executes it.
 - `raft.mentions.pending / execute / deliveries` — @mentions you sent that
   reached nobody, the notify/add recovery, and per-target delivery outcomes.
 - `raft.manual.get / search` — the Raft Manual for Agents; both need a short

package/dist/cjs/index.cjs

@@ -11044,13 +11044,17 @@ var SeenFrontier = class SeenFrontier {
 	aliases = /* @__PURE__ */ new Map();
 	static fromSnapshot(snapshot) {
 		const frontier = new SeenFrontier();
-		if (!snapshot || snapshot.version !== 1) return frontier;
+		frontier.absorb(snapshot);
+		return frontier;
+	}
+	/** Merge a snapshot into this frontier by the same monotonic rules (never lowers a mark). */
+	absorb(snapshot) {
+		if (!snapshot || snapshot.version !== 1) return;
+		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) this.recordAlias(alias, canonical);
 		for (const [target, state] of Object.entries(snapshot.targets ?? {})) {
-			if (positiveInt(state.upTo)) frontier.recordUpTo(target, state.upTo);
-			if (Array.isArray(state.exact)) frontier.recordExact(target, state.exact);
+			if (positiveInt(state.upTo)) this.recordUpTo(target, state.upTo);
+			if (Array.isArray(state.exact)) this.recordExact(target, state.exact);
 		}
-		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) frontier.recordAlias(alias, canonical);
-		return frontier;
 	}
 	/** Remember that the Server resolved `requested` to `canonical` (a thread spelling, a `~agent` suffix, …). */
 	recordAlias(requested, canonical) {
@@ -11197,7 +11201,7 @@ async function checkInbox(client, request = {}, frontier) {
 * return value summarises the drain; the batch that ends the iteration is
 * acknowledged only by the caller's next pull (`summary.cursor`).
 */
-async function* drainInbox(client, request = {}, frontier) {
+async function* drainInbox(client, request = {}, frontier, onPull) {
 	const ack = request.ack ?? "cursor";
 	let cursor = request.since ?? null;
 	let ackMode = ack;
@@ -11220,6 +11224,7 @@ async function* drainInbox(client, request = {}, frontier) {
 			error: round
 		};
 		const batch = round.data;
+		await onPull?.(sent, batch);
 		ackMode = batch.ackMode;
 		stillUnread = batch.stillUnreadConversations;
 		if (batch.messages.length > 0) {
@@ -11528,13 +11533,6 @@ async function sendMessage(client, request, frontier, internal = {}) {
 	if (data.state === "sent") return sentOutcome(request.target, data);
 	return failureOutcome(opError("INVALID_RESPONSE", { message: `Unexpected send state "${data.state}".` }));
 }
-/** Reply where a received message came from. */
-function replyTo(client, message, request, frontier) {
-	return sendMessage(client, {
-		...request,
-		target: message.target
-	}, frontier);
-}
 function taskTimestamps(t) {
 	return `${t.createdAt ? ` created=${formatUtcTimestamp(t.createdAt)}` : ""}${t.updatedAt ? ` updated=${formatUtcTimestamp(t.updatedAt)}` : ""}`;
 }
@@ -12931,10 +12929,9 @@ function inferAttachmentMimeType(filename, bytes, explicit) {
 	return sniffMimeType(bytes) ?? FILENAME_MIME_MAP[ext] ?? "application/octet-stream";
 }
 /**
-* Small-file multipart upload (`POST /upload`). Files at or above the Server's
-* direct-upload threshold need the upload-session routes (`routes.attachments.
-* createUploadSession` …), which this operation reports as `UNAVAILABLE` with a
-* next action rather than attempting silently.
+* Upload bytes into a conversation, choosing the path the CLI would: multipart
+* `POST /upload` below the Server's direct-upload threshold, an upload session
+* (create → PUT to a presigned URL → complete) at or above it.
 */
 async function uploadAttachment(client, transport, request) {
 	if (!request.target?.trim() || !request.filename?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and a filename are required to upload." }));
@@ -12944,15 +12941,11 @@ async function uploadAttachment(client, transport, request) {
 	const maxBytes = capability.ok ? capability.data.maxBytes : AGENT_ATTACHMENT_UPLOAD_FALLBACK_MAX_BYTES;
 	const threshold = capability.ok && capability.data.directUploadEnabled ? capability.data.directUploadThresholdBytes : null;
 	if (request.bytes.byteLength > maxBytes) return failureOutcome(opError("INVALID_REQUEST", { message: `Attachment is ${request.bytes.byteLength} bytes; the Server's maximum is ${maxBytes}.` }));
-	if (threshold !== null && request.bytes.byteLength >= threshold) return failureOutcome(opError("UNAVAILABLE", {
-		message: `Files of ${threshold} bytes or more use the direct-upload session routes, which this operation does not drive yet.`,
-		nextAction: "Use routes.attachments.createUploadSession / completeUploadSession, or upload a smaller file.",
-		retryable: false
-	}));
 	const resolved = await client.channels.resolve({ target: request.target });
 	if (!resolved.ok) return failureFromClientResult(resolved);
 	const channelId = resolved.data.channelId;
 	const mimeType = inferAttachmentMimeType(request.filename, request.bytes, request.mimeType);
+	if (threshold !== null && request.bytes.byteLength >= threshold) return uploadThroughSession(client, transport, request, channelId, mimeType);
 	const copy = new Uint8Array(request.bytes.byteLength);
 	copy.set(request.bytes);
 	const form = new FormData();
@@ -12992,20 +12985,22 @@ async function uploadAttachment(client, transport, request) {
 	}
 	const parsed = agentApiContract.attachmentUpload.response.body.safeParse(body);
 	if (!parsed.success) return failureOutcome(opError("INVALID_RESPONSE"));
-	const data = parsed.data;
+	return uploadedOutcome(request.target, parsed.data, mimeType);
+}
+function uploadedOutcome(target, data, mimeType) {
 	return {
 		ok: true,
 		state: "uploaded",
 		data: {
 			...data,
-			target: request.target,
+			target,
 			mimeType: data.mimeType ?? mimeType
 		},
 		next: {
 			kind: "send_with_attachment",
-			command: `raft message send --target "${request.target}" --attachment-id ${data.id}`,
+			command: `raft message send --target "${target}" --attachment-id ${data.id}`,
 			args: {
-				target: request.target,
+				target,
 				attachmentIds: [data.id]
 			},
 			why: "The upload alone posts nothing; send a message that links the attachment id."
@@ -13013,6 +13008,69 @@ async function uploadAttachment(client, transport, request) {
 		text: formatAgentAttachmentUploaded(data)
 	};
 }
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Direct upload for files at or above the Server's threshold, mirroring the
+* CLI: create a session, PUT the bytes to the presigned URL (fetch; one retry
+* when the object store may have committed), then complete, which the Server
+* verifies against the object store. A PUT that definitely failed cancels the
+* session; a PUT whose outcome is unknown leaves it for completion to verify.
+*/
+async function uploadThroughSession(client, transport, request, channelId, mimeType) {
+	const created = await client.attachments.createUploadSession({
+		channelId,
+		filename: request.filename,
+		mimeType,
+		sizeBytes: request.bytes.byteLength,
+		clientRequestId: crypto.randomUUID()
+	});
+	if (!created.ok) return failureFromClientResult(created);
+	const { uploadId, upload } = created.data;
+	const body = new Uint8Array(request.bytes.byteLength);
+	body.set(request.bytes);
+	let definitelyFailed = null;
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		let response;
+		try {
+			response = await transport.fetch(upload.url, {
+				method: upload.method ?? "PUT",
+				headers: { ...upload.headers },
+				body: body.buffer,
+				redirect: "error"
+			});
+		} catch {
+			if (attempt === 0) continue;
+			break;
+		}
+		if (response.ok || response.status === 412) {
+			definitelyFailed = null;
+			break;
+		}
+		const mayExist = response.status === 408 || response.status === 429 || response.status >= 500;
+		if (mayExist && attempt === 0) continue;
+		if (!mayExist) definitelyFailed = response.status;
+		break;
+	}
+	if (definitelyFailed !== null) {
+		await client.attachments.cancelUploadSession({ uploadId }).catch(() => void 0);
+		return failureOutcome(opError("HTTP_ERROR", {
+			message: `Direct object upload failed with HTTP ${definitelyFailed}; the upload session was cancelled.`,
+			status: definitelyFailed,
+			nextAction: "Retry the upload; nothing was attached."
+		}));
+	}
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		const completed = await client.attachments.completeUploadSession({ uploadId });
+		if (completed.ok) {
+			const attachment = completed.data.attachment;
+			return uploadedOutcome(request.target, attachment, mimeType);
+		}
+		const code = completed.error.kind === "http" ? completed.error.errorCode : null;
+		if (!(code === "UPLOAD_OBJECT_NOT_FOUND" || code === "UPLOAD_VERIFICATION_IN_PROGRESS") || attempt === 2) return failureFromClientResult(completed);
+		await wait(250 * (attempt + 1));
+	}
+	return failureOutcome(opError("UNAVAILABLE", { message: "Direct upload completion ended without a terminal response." }));
+}
 async function downloadAttachment(client, request) {
 	if (!request.attachmentId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "An attachment id is required." }));
 	const result = await client.attachments.download({ attachmentId: request.attachmentId });
@@ -13614,11 +13672,210 @@ async function searchManual(client, request) {
 	};
 }
 //#endregion
+//#region ../shared/src/agentOps/state.ts
+const RAFT_STATE_SCHEMA = "raft-sdk-state.v1";
+const RAFT_STATE_CONTINUATIONS_PER_TARGET = 3;
+const RAFT_STATE_CONTINUATIONS_TOTAL = 20;
+function isNullableCursor(value) {
+	return value === null || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/** Validate a loaded value; anything unrecognised is treated as an empty store (safe: see file header). */
+function parseRaftState(value) {
+	if (!value || typeof value !== "object") return null;
+	const v = value;
+	if (v.schema !== "raft-sdk-state.v1") return null;
+	if (typeof v.version !== "number" || !Number.isInteger(v.version) || v.version < 0) return null;
+	if (!isNullableCursor(v.cursor ?? null) || !isNullableCursor(v.pendingCursor ?? null)) return null;
+	const frontier = v.frontier;
+	const continuations = Array.isArray(v.continuations) ? v.continuations.filter((c) => {
+		const r = c;
+		return Boolean(r) && typeof r.target === "string" && typeof r.idempotencyKey === "string" && typeof r.contentHash === "string" && typeof r.heldAt === "string";
+	}) : [];
+	return {
+		schema: RAFT_STATE_SCHEMA,
+		version: v.version,
+		cursor: v.cursor ?? null,
+		pendingCursor: v.pendingCursor ?? null,
+		frontier: frontier && frontier.version === 1 ? frontier : {
+			version: 1,
+			targets: {},
+			aliases: {}
+		},
+		continuations
+	};
+}
+/** Hex SHA-256 identifying one logical message (WebCrypto; Workers-safe). */
+async function hashRaftSendContent(target, content, attachmentIds = []) {
+	const bytes = new TextEncoder().encode(`${target}\n${[...attachmentIds].sort().join(",")}\n${content}`);
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* One client's view of the persisted state: loads once, holds the working
+* copy, saves on request. Also used without a store (memory only), so the
+* pending/committed cursor flow behaves the same with or without persistence.
+*/
+var RaftStateSession = class {
+	store;
+	onError;
+	frontier;
+	cursor = null;
+	pendingCursor = null;
+	continuations = [];
+	loadedVersion = void 0;
+	loading = null;
+	dirty = false;
+	constructor(store, frontier, onError) {
+		this.store = store;
+		this.onError = onError;
+		this.frontier = frontier;
+	}
+	get persistent() {
+		return this.store !== void 0;
+	}
+	/** The version loaded from (or last saved to) the store; `undefined` before the first save of an empty store. */
+	get version() {
+		return this.loadedVersion;
+	}
+	/** Load once. A failed or unreadable load starts from an empty state (reported, not thrown). */
+	ensureLoaded() {
+		if (!this.store) return Promise.resolve();
+		this.loading ??= (async () => {
+			let raw = null;
+			try {
+				raw = await this.store.load();
+			} catch (error) {
+				this.onError?.(error, {
+					phase: "load",
+					version: void 0
+				});
+				return;
+			}
+			const state = parseRaftState(raw);
+			if (!state) return;
+			this.loadedVersion = state.version;
+			this.cursor = state.cursor;
+			this.pendingCursor = state.pendingCursor;
+			this.frontier.absorb(state.frontier);
+			this.continuations = state.continuations ?? [];
+		})();
+		return this.loading;
+	}
+	markDirty() {
+		this.dirty = true;
+	}
+	/** Record the cursor of a batch just returned. Acknowledges nothing. */
+	setPending(cursor) {
+		if (cursor === null || cursor === this.pendingCursor) return;
+		this.pendingCursor = cursor;
+		this.dirty = true;
+	}
+	/**
+	* Promote a cursor to committed. With no argument, commits `pendingCursor`.
+	* Returns the committed cursor, or null when there was nothing to commit.
+	* Never moves the committed cursor backwards.
+	*/
+	commit(cursor) {
+		const next = cursor === void 0 ? this.pendingCursor : cursor;
+		if (next === null || next === void 0) return null;
+		if (this.cursor === null || next > this.cursor) this.cursor = next;
+		if (this.pendingCursor !== null && this.pendingCursor <= this.cursor) this.pendingCursor = null;
+		this.dirty = true;
+		return this.cursor;
+	}
+	findContinuation(target, contentHash) {
+		return this.continuations.find((c) => c.target === target && c.contentHash === contentHash);
+	}
+	rememberContinuation(entry) {
+		this.continuations = this.continuations.filter((c) => !(c.target === entry.target && c.contentHash === entry.contentHash));
+		this.continuations.push(entry);
+		const perTarget = this.continuations.filter((c) => c.target === entry.target);
+		for (const drop of perTarget.slice(0, Math.max(0, perTarget.length - 3))) this.continuations.splice(this.continuations.indexOf(drop), 1);
+		if (this.continuations.length > 20) this.continuations.splice(0, this.continuations.length - 20);
+		this.dirty = true;
+	}
+	forgetContinuation(target, contentHash) {
+		const before = this.continuations.length;
+		this.continuations = this.continuations.filter((c) => !(c.target === target && c.contentHash === contentHash));
+		if (this.continuations.length !== before) this.dirty = true;
+	}
+	snapshot(nextVersion = (this.loadedVersion ?? 0) + 1) {
+		return {
+			schema: RAFT_STATE_SCHEMA,
+			version: nextVersion,
+			cursor: this.cursor,
+			pendingCursor: this.pendingCursor,
+			frontier: this.frontier.snapshot(),
+			continuations: [...this.continuations]
+		};
+	}
+	/**
+	* Save if anything changed (or `force`). One attempt; a failure is reported
+	* and swallowed. Returns whether the save succeeded (true when nothing to save).
+	*/
+	async save(options = {}) {
+		if (!this.store) return true;
+		if (!this.dirty && !options.force) return true;
+		const expectedVersion = this.loadedVersion;
+		const state = this.snapshot();
+		try {
+			await this.store.save(state, { expectedVersion });
+		} catch (error) {
+			this.onError?.(error, {
+				phase: "save",
+				version: expectedVersion
+			});
+			return false;
+		}
+		this.loadedVersion = state.version;
+		this.dirty = false;
+		return true;
+	}
+};
+//#endregion
+//#region ../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`;
+}
+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; its outcome arrives in your inbox."
+		},
+		text: formatAgentActionCardPosted(request.target, card.messageId)
+	};
+}
+//#endregion
 //#region src/raft.ts
 function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
 	const authorization = `Bearer ${requireAgentCredential(options.credential)}`;
 	const frontier = SeenFrontier.fromSnapshot(options.frontier);
+	const session = new RaftStateSession(options.state, frontier, options.onStateSaveError);
+	/** Load before, run, then save if the operation succeeded and changed the state. */
+	const withState = async (run) => {
+		await session.ensureLoaded();
+		const outcome = await run();
+		if (outcome.ok) await session.save();
+		return outcome;
+	};
 	const routes = createRaftRoutes({
 		serverUrl,
 		fetch: options.fetch,
@@ -13639,6 +13896,27 @@ function createRaft(options) {
 		throttle: options.throttle,
 		auth: { authorization }
 	} });
+	/**
+	* Send through the state session: a resend of the same logical message
+	* (same target, content, attachments) reuses the held send's idempotency key;
+	* a hold is remembered; a successful send clears it.
+	*/
+	const sendWithState = (request) => withState(async () => {
+		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
+		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
+		const outcome = await sendMessage(routes, pending ? {
+			...request,
+			idempotencyKey: pending.idempotencyKey
+		} : request, frontier);
+		if (outcome.ok && outcome.state === "held") session.rememberContinuation({
+			target: request.target,
+			idempotencyKey: outcome.data.idempotencyKey,
+			contentHash,
+			heldAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (outcome.ok && outcome.state === "sent") session.forgetContinuation(request.target, contentHash);
+		return outcome;
+	});
 	return {
 		identity: { whoami: () => getRaftContext(routes) },
 		wake: {
@@ -13650,14 +13928,53 @@ function createRaft(options) {
 			}
 		},
 		inbox: {
-			check: (request) => checkInbox(inboxApi, request, frontier),
-			drain: (request) => drainInbox(inboxApi, request, frontier),
+			check: (request = {}) => withState(async () => {
+				const since = request.since ?? session.cursor ?? void 0;
+				const outcome = await checkInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier);
+				if (outcome.ok) {
+					session.markDirty();
+					if (since !== void 0 && (request.ack ?? "cursor") === "cursor") session.commit(since);
+					if (outcome.data.ackMode === "cursor" && outcome.data.messages.length > 0) session.setPending(outcome.data.cursor);
+				}
+				return outcome;
+			}),
+			commit: async (target) => {
+				await session.ensureLoaded();
+				const cursor = session.commit(target === void 0 ? void 0 : target.cursor);
+				return {
+					cursor,
+					saved: cursor === null ? true : await session.save()
+				};
+			},
+			drain: (request = {}) => (async function* () {
+				await session.ensureLoaded();
+				const since = request.since ?? session.cursor ?? void 0;
+				return yield* drainInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier, async (sent, batch) => {
+					if (sent !== null) session.commit(sent);
+					if (batch.ackMode === "cursor" && batch.messages.length > 0) session.setPending(batch.cursor);
+					session.markDirty();
+					await session.save();
+				});
+			})(),
 			list: (request) => listInbox(routes, request)
 		},
 		messages: {
-			read: (request) => readHistory(routes, request, frontier),
-			send: (request) => sendMessage(routes, request, frontier),
-			reply: (message, request) => replyTo(routes, message, request, frontier),
+			read: (request) => withState(async () => {
+				const outcome = await readHistory(routes, request, frontier);
+				if (outcome.ok) session.markDirty();
+				return outcome;
+			}),
+			send: (request) => sendWithState(request),
+			reply: (message, request) => sendWithState({
+				...request,
+				target: message.target
+			}),
 			search: (request) => searchMessages(routes, request),
 			resolve: (request) => resolveMessage(routes, request),
 			react: (request) => reactToMessage(routes, request, "add"),
@@ -13678,6 +13995,7 @@ function createRaft(options) {
 			execute: (request) => executeMentionAction(routes, request),
 			deliveries: (request) => senderMentionDeliveries(routes, request)
 		},
+		actions: { prepare: (request) => prepareActionCard(routes, request) },
 		manual: {
 			get: (request) => getManualTopic(routes, request),
 			search: (request) => searchManual(routes, request)
@@ -13711,6 +14029,15 @@ function createRaft(options) {
 			update: (request) => updateProfile(routes, request)
 		},
 		frontier,
+		state: {
+			save: async () => {
+				await session.ensureLoaded();
+				session.markDirty();
+				return session.save();
+			},
+			load: () => session.ensureLoaded(),
+			snapshot: () => session.snapshot(session.version ?? 0)
+		},
 		routes
 	};
 }
@@ -13718,6 +14045,9 @@ function createRaft(options) {
 exports.RAFT_INBOX_NOTICE_SCHEMA = RAFT_INBOX_NOTICE_SCHEMA;
 exports.RAFT_NOTICE_DELIVERY_ID_HEADER = RAFT_NOTICE_DELIVERY_ID_HEADER;
 exports.RAFT_NOTICE_SIGNATURE_HEADER = RAFT_NOTICE_SIGNATURE_HEADER;
+exports.RAFT_STATE_CONTINUATIONS_PER_TARGET = RAFT_STATE_CONTINUATIONS_PER_TARGET;
+exports.RAFT_STATE_CONTINUATIONS_TOTAL = RAFT_STATE_CONTINUATIONS_TOTAL;
+exports.RAFT_STATE_SCHEMA = RAFT_STATE_SCHEMA;
 exports.RaftCredentialError = RaftCredentialError;
 exports.RaftSdkConfigurationError = RaftSdkConfigurationError;
 exports.SeenFrontier = SeenFrontier;
@@ -13729,10 +14059,12 @@ exports.createRaftClientFromStore = createRaftClientFromStore;
 exports.createRaftRoutes = createRaftRoutes;
 exports.describeRaftRoute = describeRaftRoute;
 exports.hasAgentMessageIdentity = hasAgentMessageIdentity;
+exports.hashRaftSendContent = hashRaftSendContent;
 exports.inferAttachmentMimeType = inferAttachmentMimeType;
 exports.joinRaftChannelByTarget = joinRaftChannelByTarget;
 exports.listRaftRoutes = listRaftRoutes;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
+exports.parseRaftState = parseRaftState;
 exports.projectRaftMessage = projectRaftMessage;
 exports.projectRaftMessages = projectRaftMessages;
 exports.verifyInboxNotice = verifyInboxNotice;

package/dist/esm/index.js

@@ -11043,13 +11043,17 @@ var SeenFrontier = class SeenFrontier {
 	aliases = /* @__PURE__ */ new Map();
 	static fromSnapshot(snapshot) {
 		const frontier = new SeenFrontier();
-		if (!snapshot || snapshot.version !== 1) return frontier;
+		frontier.absorb(snapshot);
+		return frontier;
+	}
+	/** Merge a snapshot into this frontier by the same monotonic rules (never lowers a mark). */
+	absorb(snapshot) {
+		if (!snapshot || snapshot.version !== 1) return;
+		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) this.recordAlias(alias, canonical);
 		for (const [target, state] of Object.entries(snapshot.targets ?? {})) {
-			if (positiveInt(state.upTo)) frontier.recordUpTo(target, state.upTo);
-			if (Array.isArray(state.exact)) frontier.recordExact(target, state.exact);
+			if (positiveInt(state.upTo)) this.recordUpTo(target, state.upTo);
+			if (Array.isArray(state.exact)) this.recordExact(target, state.exact);
 		}
-		for (const [alias, canonical] of Object.entries(snapshot.aliases ?? {})) frontier.recordAlias(alias, canonical);
-		return frontier;
 	}
 	/** Remember that the Server resolved `requested` to `canonical` (a thread spelling, a `~agent` suffix, …). */
 	recordAlias(requested, canonical) {
@@ -11196,7 +11200,7 @@ async function checkInbox(client, request = {}, frontier) {
 * return value summarises the drain; the batch that ends the iteration is
 * acknowledged only by the caller's next pull (`summary.cursor`).
 */
-async function* drainInbox(client, request = {}, frontier) {
+async function* drainInbox(client, request = {}, frontier, onPull) {
 	const ack = request.ack ?? "cursor";
 	let cursor = request.since ?? null;
 	let ackMode = ack;
@@ -11219,6 +11223,7 @@ async function* drainInbox(client, request = {}, frontier) {
 			error: round
 		};
 		const batch = round.data;
+		await onPull?.(sent, batch);
 		ackMode = batch.ackMode;
 		stillUnread = batch.stillUnreadConversations;
 		if (batch.messages.length > 0) {
@@ -11527,13 +11532,6 @@ async function sendMessage(client, request, frontier, internal = {}) {
 	if (data.state === "sent") return sentOutcome(request.target, data);
 	return failureOutcome(opError("INVALID_RESPONSE", { message: `Unexpected send state "${data.state}".` }));
 }
-/** Reply where a received message came from. */
-function replyTo(client, message, request, frontier) {
-	return sendMessage(client, {
-		...request,
-		target: message.target
-	}, frontier);
-}
 function taskTimestamps(t) {
 	return `${t.createdAt ? ` created=${formatUtcTimestamp(t.createdAt)}` : ""}${t.updatedAt ? ` updated=${formatUtcTimestamp(t.updatedAt)}` : ""}`;
 }
@@ -12930,10 +12928,9 @@ function inferAttachmentMimeType(filename, bytes, explicit) {
 	return sniffMimeType(bytes) ?? FILENAME_MIME_MAP[ext] ?? "application/octet-stream";
 }
 /**
-* Small-file multipart upload (`POST /upload`). Files at or above the Server's
-* direct-upload threshold need the upload-session routes (`routes.attachments.
-* createUploadSession` …), which this operation reports as `UNAVAILABLE` with a
-* next action rather than attempting silently.
+* Upload bytes into a conversation, choosing the path the CLI would: multipart
+* `POST /upload` below the Server's direct-upload threshold, an upload session
+* (create → PUT to a presigned URL → complete) at or above it.
 */
 async function uploadAttachment(client, transport, request) {
 	if (!request.target?.trim() || !request.filename?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and a filename are required to upload." }));
@@ -12943,15 +12940,11 @@ async function uploadAttachment(client, transport, request) {
 	const maxBytes = capability.ok ? capability.data.maxBytes : AGENT_ATTACHMENT_UPLOAD_FALLBACK_MAX_BYTES;
 	const threshold = capability.ok && capability.data.directUploadEnabled ? capability.data.directUploadThresholdBytes : null;
 	if (request.bytes.byteLength > maxBytes) return failureOutcome(opError("INVALID_REQUEST", { message: `Attachment is ${request.bytes.byteLength} bytes; the Server's maximum is ${maxBytes}.` }));
-	if (threshold !== null && request.bytes.byteLength >= threshold) return failureOutcome(opError("UNAVAILABLE", {
-		message: `Files of ${threshold} bytes or more use the direct-upload session routes, which this operation does not drive yet.`,
-		nextAction: "Use routes.attachments.createUploadSession / completeUploadSession, or upload a smaller file.",
-		retryable: false
-	}));
 	const resolved = await client.channels.resolve({ target: request.target });
 	if (!resolved.ok) return failureFromClientResult(resolved);
 	const channelId = resolved.data.channelId;
 	const mimeType = inferAttachmentMimeType(request.filename, request.bytes, request.mimeType);
+	if (threshold !== null && request.bytes.byteLength >= threshold) return uploadThroughSession(client, transport, request, channelId, mimeType);
 	const copy = new Uint8Array(request.bytes.byteLength);
 	copy.set(request.bytes);
 	const form = new FormData();
@@ -12991,20 +12984,22 @@ async function uploadAttachment(client, transport, request) {
 	}
 	const parsed = agentApiContract.attachmentUpload.response.body.safeParse(body);
 	if (!parsed.success) return failureOutcome(opError("INVALID_RESPONSE"));
-	const data = parsed.data;
+	return uploadedOutcome(request.target, parsed.data, mimeType);
+}
+function uploadedOutcome(target, data, mimeType) {
 	return {
 		ok: true,
 		state: "uploaded",
 		data: {
 			...data,
-			target: request.target,
+			target,
 			mimeType: data.mimeType ?? mimeType
 		},
 		next: {
 			kind: "send_with_attachment",
-			command: `raft message send --target "${request.target}" --attachment-id ${data.id}`,
+			command: `raft message send --target "${target}" --attachment-id ${data.id}`,
 			args: {
-				target: request.target,
+				target,
 				attachmentIds: [data.id]
 			},
 			why: "The upload alone posts nothing; send a message that links the attachment id."
@@ -13012,6 +13007,69 @@ async function uploadAttachment(client, transport, request) {
 		text: formatAgentAttachmentUploaded(data)
 	};
 }
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Direct upload for files at or above the Server's threshold, mirroring the
+* CLI: create a session, PUT the bytes to the presigned URL (fetch; one retry
+* when the object store may have committed), then complete, which the Server
+* verifies against the object store. A PUT that definitely failed cancels the
+* session; a PUT whose outcome is unknown leaves it for completion to verify.
+*/
+async function uploadThroughSession(client, transport, request, channelId, mimeType) {
+	const created = await client.attachments.createUploadSession({
+		channelId,
+		filename: request.filename,
+		mimeType,
+		sizeBytes: request.bytes.byteLength,
+		clientRequestId: crypto.randomUUID()
+	});
+	if (!created.ok) return failureFromClientResult(created);
+	const { uploadId, upload } = created.data;
+	const body = new Uint8Array(request.bytes.byteLength);
+	body.set(request.bytes);
+	let definitelyFailed = null;
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		let response;
+		try {
+			response = await transport.fetch(upload.url, {
+				method: upload.method ?? "PUT",
+				headers: { ...upload.headers },
+				body: body.buffer,
+				redirect: "error"
+			});
+		} catch {
+			if (attempt === 0) continue;
+			break;
+		}
+		if (response.ok || response.status === 412) {
+			definitelyFailed = null;
+			break;
+		}
+		const mayExist = response.status === 408 || response.status === 429 || response.status >= 500;
+		if (mayExist && attempt === 0) continue;
+		if (!mayExist) definitelyFailed = response.status;
+		break;
+	}
+	if (definitelyFailed !== null) {
+		await client.attachments.cancelUploadSession({ uploadId }).catch(() => void 0);
+		return failureOutcome(opError("HTTP_ERROR", {
+			message: `Direct object upload failed with HTTP ${definitelyFailed}; the upload session was cancelled.`,
+			status: definitelyFailed,
+			nextAction: "Retry the upload; nothing was attached."
+		}));
+	}
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		const completed = await client.attachments.completeUploadSession({ uploadId });
+		if (completed.ok) {
+			const attachment = completed.data.attachment;
+			return uploadedOutcome(request.target, attachment, mimeType);
+		}
+		const code = completed.error.kind === "http" ? completed.error.errorCode : null;
+		if (!(code === "UPLOAD_OBJECT_NOT_FOUND" || code === "UPLOAD_VERIFICATION_IN_PROGRESS") || attempt === 2) return failureFromClientResult(completed);
+		await wait(250 * (attempt + 1));
+	}
+	return failureOutcome(opError("UNAVAILABLE", { message: "Direct upload completion ended without a terminal response." }));
+}
 async function downloadAttachment(client, request) {
 	if (!request.attachmentId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "An attachment id is required." }));
 	const result = await client.attachments.download({ attachmentId: request.attachmentId });
@@ -13613,11 +13671,210 @@ async function searchManual(client, request) {
 	};
 }
 //#endregion
+//#region ../shared/src/agentOps/state.ts
+const RAFT_STATE_SCHEMA = "raft-sdk-state.v1";
+const RAFT_STATE_CONTINUATIONS_PER_TARGET = 3;
+const RAFT_STATE_CONTINUATIONS_TOTAL = 20;
+function isNullableCursor(value) {
+	return value === null || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+/** Validate a loaded value; anything unrecognised is treated as an empty store (safe: see file header). */
+function parseRaftState(value) {
+	if (!value || typeof value !== "object") return null;
+	const v = value;
+	if (v.schema !== "raft-sdk-state.v1") return null;
+	if (typeof v.version !== "number" || !Number.isInteger(v.version) || v.version < 0) return null;
+	if (!isNullableCursor(v.cursor ?? null) || !isNullableCursor(v.pendingCursor ?? null)) return null;
+	const frontier = v.frontier;
+	const continuations = Array.isArray(v.continuations) ? v.continuations.filter((c) => {
+		const r = c;
+		return Boolean(r) && typeof r.target === "string" && typeof r.idempotencyKey === "string" && typeof r.contentHash === "string" && typeof r.heldAt === "string";
+	}) : [];
+	return {
+		schema: RAFT_STATE_SCHEMA,
+		version: v.version,
+		cursor: v.cursor ?? null,
+		pendingCursor: v.pendingCursor ?? null,
+		frontier: frontier && frontier.version === 1 ? frontier : {
+			version: 1,
+			targets: {},
+			aliases: {}
+		},
+		continuations
+	};
+}
+/** Hex SHA-256 identifying one logical message (WebCrypto; Workers-safe). */
+async function hashRaftSendContent(target, content, attachmentIds = []) {
+	const bytes = new TextEncoder().encode(`${target}\n${[...attachmentIds].sort().join(",")}\n${content}`);
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* One client's view of the persisted state: loads once, holds the working
+* copy, saves on request. Also used without a store (memory only), so the
+* pending/committed cursor flow behaves the same with or without persistence.
+*/
+var RaftStateSession = class {
+	store;
+	onError;
+	frontier;
+	cursor = null;
+	pendingCursor = null;
+	continuations = [];
+	loadedVersion = void 0;
+	loading = null;
+	dirty = false;
+	constructor(store, frontier, onError) {
+		this.store = store;
+		this.onError = onError;
+		this.frontier = frontier;
+	}
+	get persistent() {
+		return this.store !== void 0;
+	}
+	/** The version loaded from (or last saved to) the store; `undefined` before the first save of an empty store. */
+	get version() {
+		return this.loadedVersion;
+	}
+	/** Load once. A failed or unreadable load starts from an empty state (reported, not thrown). */
+	ensureLoaded() {
+		if (!this.store) return Promise.resolve();
+		this.loading ??= (async () => {
+			let raw = null;
+			try {
+				raw = await this.store.load();
+			} catch (error) {
+				this.onError?.(error, {
+					phase: "load",
+					version: void 0
+				});
+				return;
+			}
+			const state = parseRaftState(raw);
+			if (!state) return;
+			this.loadedVersion = state.version;
+			this.cursor = state.cursor;
+			this.pendingCursor = state.pendingCursor;
+			this.frontier.absorb(state.frontier);
+			this.continuations = state.continuations ?? [];
+		})();
+		return this.loading;
+	}
+	markDirty() {
+		this.dirty = true;
+	}
+	/** Record the cursor of a batch just returned. Acknowledges nothing. */
+	setPending(cursor) {
+		if (cursor === null || cursor === this.pendingCursor) return;
+		this.pendingCursor = cursor;
+		this.dirty = true;
+	}
+	/**
+	* Promote a cursor to committed. With no argument, commits `pendingCursor`.
+	* Returns the committed cursor, or null when there was nothing to commit.
+	* Never moves the committed cursor backwards.
+	*/
+	commit(cursor) {
+		const next = cursor === void 0 ? this.pendingCursor : cursor;
+		if (next === null || next === void 0) return null;
+		if (this.cursor === null || next > this.cursor) this.cursor = next;
+		if (this.pendingCursor !== null && this.pendingCursor <= this.cursor) this.pendingCursor = null;
+		this.dirty = true;
+		return this.cursor;
+	}
+	findContinuation(target, contentHash) {
+		return this.continuations.find((c) => c.target === target && c.contentHash === contentHash);
+	}
+	rememberContinuation(entry) {
+		this.continuations = this.continuations.filter((c) => !(c.target === entry.target && c.contentHash === entry.contentHash));
+		this.continuations.push(entry);
+		const perTarget = this.continuations.filter((c) => c.target === entry.target);
+		for (const drop of perTarget.slice(0, Math.max(0, perTarget.length - 3))) this.continuations.splice(this.continuations.indexOf(drop), 1);
+		if (this.continuations.length > 20) this.continuations.splice(0, this.continuations.length - 20);
+		this.dirty = true;
+	}
+	forgetContinuation(target, contentHash) {
+		const before = this.continuations.length;
+		this.continuations = this.continuations.filter((c) => !(c.target === target && c.contentHash === contentHash));
+		if (this.continuations.length !== before) this.dirty = true;
+	}
+	snapshot(nextVersion = (this.loadedVersion ?? 0) + 1) {
+		return {
+			schema: RAFT_STATE_SCHEMA,
+			version: nextVersion,
+			cursor: this.cursor,
+			pendingCursor: this.pendingCursor,
+			frontier: this.frontier.snapshot(),
+			continuations: [...this.continuations]
+		};
+	}
+	/**
+	* Save if anything changed (or `force`). One attempt; a failure is reported
+	* and swallowed. Returns whether the save succeeded (true when nothing to save).
+	*/
+	async save(options = {}) {
+		if (!this.store) return true;
+		if (!this.dirty && !options.force) return true;
+		const expectedVersion = this.loadedVersion;
+		const state = this.snapshot();
+		try {
+			await this.store.save(state, { expectedVersion });
+		} catch (error) {
+			this.onError?.(error, {
+				phase: "save",
+				version: expectedVersion
+			});
+			return false;
+		}
+		this.loadedVersion = state.version;
+		this.dirty = false;
+		return true;
+	}
+};
+//#endregion
+//#region ../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`;
+}
+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; its outcome arrives in your inbox."
+		},
+		text: formatAgentActionCardPosted(request.target, card.messageId)
+	};
+}
+//#endregion
 //#region src/raft.ts
 function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
 	const authorization = `Bearer ${requireAgentCredential(options.credential)}`;
 	const frontier = SeenFrontier.fromSnapshot(options.frontier);
+	const session = new RaftStateSession(options.state, frontier, options.onStateSaveError);
+	/** Load before, run, then save if the operation succeeded and changed the state. */
+	const withState = async (run) => {
+		await session.ensureLoaded();
+		const outcome = await run();
+		if (outcome.ok) await session.save();
+		return outcome;
+	};
 	const routes = createRaftRoutes({
 		serverUrl,
 		fetch: options.fetch,
@@ -13638,6 +13895,27 @@ function createRaft(options) {
 		throttle: options.throttle,
 		auth: { authorization }
 	} });
+	/**
+	* Send through the state session: a resend of the same logical message
+	* (same target, content, attachments) reuses the held send's idempotency key;
+	* a hold is remembered; a successful send clears it.
+	*/
+	const sendWithState = (request) => withState(async () => {
+		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
+		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
+		const outcome = await sendMessage(routes, pending ? {
+			...request,
+			idempotencyKey: pending.idempotencyKey
+		} : request, frontier);
+		if (outcome.ok && outcome.state === "held") session.rememberContinuation({
+			target: request.target,
+			idempotencyKey: outcome.data.idempotencyKey,
+			contentHash,
+			heldAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (outcome.ok && outcome.state === "sent") session.forgetContinuation(request.target, contentHash);
+		return outcome;
+	});
 	return {
 		identity: { whoami: () => getRaftContext(routes) },
 		wake: {
@@ -13649,14 +13927,53 @@ function createRaft(options) {
 			}
 		},
 		inbox: {
-			check: (request) => checkInbox(inboxApi, request, frontier),
-			drain: (request) => drainInbox(inboxApi, request, frontier),
+			check: (request = {}) => withState(async () => {
+				const since = request.since ?? session.cursor ?? void 0;
+				const outcome = await checkInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier);
+				if (outcome.ok) {
+					session.markDirty();
+					if (since !== void 0 && (request.ack ?? "cursor") === "cursor") session.commit(since);
+					if (outcome.data.ackMode === "cursor" && outcome.data.messages.length > 0) session.setPending(outcome.data.cursor);
+				}
+				return outcome;
+			}),
+			commit: async (target) => {
+				await session.ensureLoaded();
+				const cursor = session.commit(target === void 0 ? void 0 : target.cursor);
+				return {
+					cursor,
+					saved: cursor === null ? true : await session.save()
+				};
+			},
+			drain: (request = {}) => (async function* () {
+				await session.ensureLoaded();
+				const since = request.since ?? session.cursor ?? void 0;
+				return yield* drainInbox(inboxApi, {
+					...request,
+					...since === void 0 ? {} : { since }
+				}, frontier, async (sent, batch) => {
+					if (sent !== null) session.commit(sent);
+					if (batch.ackMode === "cursor" && batch.messages.length > 0) session.setPending(batch.cursor);
+					session.markDirty();
+					await session.save();
+				});
+			})(),
 			list: (request) => listInbox(routes, request)
 		},
 		messages: {
-			read: (request) => readHistory(routes, request, frontier),
-			send: (request) => sendMessage(routes, request, frontier),
-			reply: (message, request) => replyTo(routes, message, request, frontier),
+			read: (request) => withState(async () => {
+				const outcome = await readHistory(routes, request, frontier);
+				if (outcome.ok) session.markDirty();
+				return outcome;
+			}),
+			send: (request) => sendWithState(request),
+			reply: (message, request) => sendWithState({
+				...request,
+				target: message.target
+			}),
 			search: (request) => searchMessages(routes, request),
 			resolve: (request) => resolveMessage(routes, request),
 			react: (request) => reactToMessage(routes, request, "add"),
@@ -13677,6 +13994,7 @@ function createRaft(options) {
 			execute: (request) => executeMentionAction(routes, request),
 			deliveries: (request) => senderMentionDeliveries(routes, request)
 		},
+		actions: { prepare: (request) => prepareActionCard(routes, request) },
 		manual: {
 			get: (request) => getManualTopic(routes, request),
 			search: (request) => searchManual(routes, request)
@@ -13710,8 +14028,17 @@ function createRaft(options) {
 			update: (request) => updateProfile(routes, request)
 		},
 		frontier,
+		state: {
+			save: async () => {
+				await session.ensureLoaded();
+				session.markDirty();
+				return session.save();
+			},
+			load: () => session.ensureLoaded(),
+			snapshot: () => session.snapshot(session.version ?? 0)
+		},
 		routes
 	};
 }
 //#endregion
-export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, bootstrapRaftCredential, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, describeRaftRoute, hasAgentMessageIdentity, inferAttachmentMimeType, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, projectRaftMessage, projectRaftMessages, verifyInboxNotice };
+export { RAFT_INBOX_NOTICE_SCHEMA, RAFT_NOTICE_DELIVERY_ID_HEADER, RAFT_NOTICE_SIGNATURE_HEADER, RAFT_STATE_CONTINUATIONS_PER_TARGET, RAFT_STATE_CONTINUATIONS_TOTAL, RAFT_STATE_SCHEMA, RaftCredentialError, RaftSdkConfigurationError, SeenFrontier, bootstrapRaftCredential, createFileCredentialStore, createRaft, createRaftClient, createRaftClientFromStore, createRaftRoutes, describeRaftRoute, hasAgentMessageIdentity, hashRaftSendContent, inferAttachmentMimeType, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, parseRaftState, projectRaftMessage, projectRaftMessages, verifyInboxNotice };

package/dist/index.d.ts

@@ -444,6 +444,8 @@ export declare class SeenFrontier {
   private readonly targets;
   private readonly aliases;
   static fromSnapshot(snapshot: SeenFrontierSnapshot | null | undefined): SeenFrontier;
+  /** Merge a snapshot into this frontier by the same monotonic rules (never lowers a mark). */
+  absorb(snapshot: SeenFrontierSnapshot | null | undefined): void;
   /** Remember that the Server resolved `requested` to `canonical` (a thread spelling, a `~agent` suffix, …). */
   recordAlias(requested: string, canonical: string): void;
   canonical(target: string): string;
@@ -935,6 +937,57 @@ interface ManualContext {
   reason: string;
 }
 //#endregion
+//#region ../shared/src/agentOps/state.d.ts
+export declare const RAFT_STATE_SCHEMA: "raft-sdk-state.v1";
+interface RaftStateContinuation {
+  target: string;
+  idempotencyKey: string;
+  /** Hex SHA-256 of target, content and attachment ids; a resend with the same hash is the same logical message. */
+  contentHash: string;
+  /** ISO time the send was held. */
+  heldAt: string;
+}
+interface RaftState {
+  schema: typeof RAFT_STATE_SCHEMA;
+  /** Revision, incremented on every save by this SDK. Compare-and-set stores compare against it. */
+  version: number;
+  /** Last committed inbox cursor; the next pull passes it as `since`. */
+  cursor: number | null;
+  /** Cursor of the batch returned but not yet committed. */
+  pendingCursor: number | null;
+  frontier: SeenFrontierSnapshot;
+  continuations?: RaftStateContinuation[];
+}
+interface RaftStateStore {
+  load(): Promise<RaftState | null>;
+  /**
+   * Persist `state`. `expectedVersion` is the version this client loaded
+   * (`undefined` when the store was empty). Throw to reject a stale write;
+   * stores without compare-and-set may ignore it.
+   */
+  save(state: RaftState, options: {
+    expectedVersion: number | undefined;
+  }): Promise<void>;
+}
+type RaftStateSaveErrorHandler = (error: unknown, context: {
+  phase: "load" | "save";
+  version: number | undefined;
+}) => void;
+export declare const RAFT_STATE_CONTINUATIONS_PER_TARGET = 3;
+export declare const RAFT_STATE_CONTINUATIONS_TOTAL = 20;
+/** Validate a loaded value; anything unrecognised is treated as an empty store (safe: see file header). */
+export declare function parseRaftState(value: unknown): RaftState | null;
+/** Hex SHA-256 identifying one logical message (WebCrypto; Workers-safe). */
+export declare function hashRaftSendContent(target: string, content: string, attachmentIds?: readonly string[]): Promise<string>;
+//#endregion
+//#region ../shared/src/agentOps/actions.d.ts
+type PrepareActionCardRequest = AgentApiActionPrepareBody;
+interface RaftPreparedCard {
+  target: string;
+  /** The card message; a human commits it by clicking its action verb. */
+  messageId: string;
+}
+//#endregion
 //#region ../shared/src/agentApiRawClient.d.ts
 type AgentApiRawClientErrorReason = "missing_route" | "missing_path_param" | "request_contract_mismatch" | "transport_error" | "http_error" | "empty_response" | "response_contract_mismatch";
 interface AgentApiRawTransportRequest<K extends AgentApiRouteKey = AgentApiRouteKey> {
@@ -9299,6 +9352,22 @@ interface CreateRaftOptions {
    * is held once and returns the unread context, which is the safe default.
    */
   frontier?: SeenFrontierSnapshot | null;
+  /**
+   * Persist the client's state (committed and pending inbox cursors, the seen
+   * frontier, held-send keys) across tool calls and processes. The store
+   * implements `load()` and `save(state, { expectedVersion })`; the SDK loads
+   * once before the first operation and saves after each successful operation
+   * that changed the state (one attempt, never fails the operation).
+   */
+  state?: RaftStateStore;
+  /** Called when loading or saving the state fails or is rejected as stale. */
+  onStateSaveError?: RaftStateSaveErrorHandler;
+}
+interface RaftInboxCommitResult {
+  /** The committed cursor, or null when there was nothing to commit. */
+  cursor: number | null;
+  /** Whether the state was persisted (true when no store is configured). */
+  saved: boolean;
 }
 interface Raft {
   identity: {
@@ -9320,8 +9389,22 @@ interface Raft {
     };
   };
   inbox: {
-    /** One bounded pull. Nothing is acknowledged until the next call passes `data.cursor` as `since` (cursor mode). */
+    /**
+     * One bounded pull. Nothing is acknowledged by it. Without `since`, sends
+     * the last committed cursor (from `state`), which is what acknowledges the
+     * previously committed batch on the Server; the returned batch's cursor is
+     * recorded as pending until you `commit()` it.
+     */
     check(request?: CheckInboxRequest): Promise<CheckInboxOutcome>;
+    /**
+     * Mark a batch as processed. With no argument, commits the pending cursor
+     * from the last `check()` (possibly in an earlier process, via `state`);
+     * also accepts `{ cursor }` or a batch. Records only; the next `check()`
+     * acknowledges it on the Server. The SDK never commits on its own.
+     */
+    commit(target?: {
+      cursor: number | null;
+    }): Promise<RaftInboxCommitResult>;
     /**
      * Pull until the Server reports nothing more, like `raft message check`, as
      * an async iterator: the pull that acknowledges a batch is only sent when
@@ -9376,6 +9459,14 @@ interface Raft {
       messageId: string;
     }): Promise<RaftOutcome<AgentApiSenderMentionDeliveriesResponse, "deliveries" | "empty">>;
   };
+  actions: {
+    /**
+     * Post an action card for a human to confirm (channel:create,
+     * channel:add_member, agent:create, and the integration card types). The
+     * human who clicks it executes it as themselves.
+     */
+    prepare(request: PrepareActionCardRequest): Promise<RaftOutcome<RaftPreparedCard, "prepared">>;
+  };
   manual: {
     /** Fetch a Manual topic; `intent` and `reason` are required and must never carry prompts, credentials, or message payloads. */
     get(request: {
@@ -9455,9 +9546,17 @@ interface Raft {
   };
   /** What this process has shown its model, per target; export it to survive restarts. */
   frontier: SeenFrontier;
+  state: {
+    /** Save now (for example after `frontier.recordHeld`). Best effort; returns whether it succeeded. */
+    save(): Promise<boolean>;
+    /** Load the persisted state now (operations do this automatically). */
+    load(): Promise<void>;
+    /** The current state value, as it would be saved. */
+    snapshot(): RaftState;
+  };
   /** Every Agent API route, typed from the shared contract. */
   routes: RaftRoutes;
 }
 export declare function createRaft(options: CreateRaftOptions): Raft;
 //#endregion
-export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimHeld, RaftClaimHeldLike, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHeld, RaftHeldBase, RaftHistoryPage, RaftInboxBatch, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftPendingMentions, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+export type { AmendTaskOutcome, AmendTaskRequest, AssignTaskRequest, BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, CreateTasksRequest, DrainInboxRequest, ExecuteMentionActionRequest, ListInboxRequest, ListTasksRequest, ManualContext, PrepareActionCardRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAttachmentBytes, RaftAttachmentUploaded, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftChannelMuteState, RaftChannelRef, RaftClaimHeld, RaftClaimHeldLike, RaftClaimResult, RaftClaimRow, RaftClaimRowState, RaftClient, RaftClientError, RaftClientFailure, RaftClientResult, RaftClientSuccess, RaftClientThrottleOptions, RaftClientTransportRequest, RaftContextAgent, RaftContextData, RaftContextError, RaftContextResult, RaftContextServer, RaftCredentialErrorCode, RaftCredentialIdentity, RaftCredentialStore, RaftEvent, RaftEventAttachment, RaftEventExternalMessage, RaftEventsReceiveData, RaftEventsReceiveError, RaftEventsReceiveRequest, RaftEventsReceiveResult, RaftFailure, RaftHeld, RaftHeldBase, RaftHistoryPage, RaftInboxBatch, RaftInboxCommitResult, RaftInboxConversation, RaftInboxDrainSummary, RaftInboxListing, RaftInboxNotice, RaftManageClient, RaftMessage, RaftMessageAttachment, RaftMessageTask, RaftNextStep, RaftNoticeFlag, RaftNoticeTarget, RaftOpError, RaftOpErrorCode, RaftOutcome, RaftPendingMentions, RaftPreparedCard, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSearchPage, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerInfo, RaftServerProfile, RaftServerUpdate, RaftState, RaftStateContinuation, RaftStateSaveErrorHandler, RaftStateStore, RaftTaskBoard, RaftTaskStatus, RaftTasksCreated, RaftWebhookStatus, ReactRequest, ReadHistoryRequest, SearchMessagesRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, ServerInfoRequest, ServerInfoSection, StoredRaftCredential, TaskRef, UpdateTaskStatusOutcome, UpdateTaskStatusRequest, UploadAttachmentRequest, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };

package/package.json

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