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

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

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)}` : ""}`;
 }
@@ -13614,11 +13612,179 @@ 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 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 +13805,27 @@ function createRaft(options) {
 		throttle: options.throttle,
 		auth: { authorization }
 	} });
+	/**
+	* Send through the state session: a resend of the same logical message
+	* (same target, content, attachments) reuses the held send's idempotency key;
+	* a hold is remembered; a successful send clears it.
+	*/
+	const sendWithState = (request) => withState(async () => {
+		const contentHash = await hashRaftSendContent(request.target, request.content ?? "", request.attachmentIds ?? []);
+		const pending = request.idempotencyKey ? void 0 : session.findContinuation(request.target, contentHash);
+		const outcome = await sendMessage(routes, pending ? {
+			...request,
+			idempotencyKey: pending.idempotencyKey
+		} : request, frontier);
+		if (outcome.ok && outcome.state === "held") session.rememberContinuation({
+			target: request.target,
+			idempotencyKey: outcome.data.idempotencyKey,
+			contentHash,
+			heldAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (outcome.ok && outcome.state === "sent") session.forgetContinuation(request.target, contentHash);
+		return outcome;
+	});
 	return {
 		identity: { whoami: () => getRaftContext(routes) },
 		wake: {
@@ -13650,14 +13837,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"),
@@ -13711,6 +13937,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 +13953,9 @@ function createRaft(options) {
 exports.RAFT_INBOX_NOTICE_SCHEMA = RAFT_INBOX_NOTICE_SCHEMA;
 exports.RAFT_NOTICE_DELIVERY_ID_HEADER = RAFT_NOTICE_DELIVERY_ID_HEADER;
 exports.RAFT_NOTICE_SIGNATURE_HEADER = RAFT_NOTICE_SIGNATURE_HEADER;
+exports.RAFT_STATE_CONTINUATIONS_PER_TARGET = RAFT_STATE_CONTINUATIONS_PER_TARGET;
+exports.RAFT_STATE_CONTINUATIONS_TOTAL = RAFT_STATE_CONTINUATIONS_TOTAL;
+exports.RAFT_STATE_SCHEMA = RAFT_STATE_SCHEMA;
 exports.RaftCredentialError = RaftCredentialError;
 exports.RaftSdkConfigurationError = RaftSdkConfigurationError;
 exports.SeenFrontier = SeenFrontier;
@@ -13729,10 +13967,12 @@ exports.createRaftClientFromStore = createRaftClientFromStore;
 exports.createRaftRoutes = createRaftRoutes;
 exports.describeRaftRoute = describeRaftRoute;
 exports.hasAgentMessageIdentity = hasAgentMessageIdentity;
+exports.hashRaftSendContent = hashRaftSendContent;
 exports.inferAttachmentMimeType = inferAttachmentMimeType;
 exports.joinRaftChannelByTarget = joinRaftChannelByTarget;
 exports.listRaftRoutes = listRaftRoutes;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
+exports.parseRaftState = parseRaftState;
 exports.projectRaftMessage = projectRaftMessage;
 exports.projectRaftMessages = projectRaftMessages;
 exports.verifyInboxNotice = verifyInboxNotice;

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)}` : ""}`;
 }
@@ -13613,11 +13611,179 @@ 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 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 +13804,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 +13836,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"),
@@ -13710,8 +13936,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,49 @@ 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/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 +9344,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 +9381,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
@@ -9455,9 +9530,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, 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, 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.4",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",