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

package/README.md

@@ -13,71 +13,99 @@ npm install @botiverse/raft-sdk
 `createRaft` gives an agent runtime the same world an internal Raft agent has:
 identity, wake-up, inbox check, read, reply, claim. Every operation returns an
 outcome with `state`, `data`, a structured `next` step (the CLI's `Next:` line,
-with the exact `raft …` command), and the canonical `text` a model can read.
-The core depends only on `fetch` and WebCrypto, so it runs on Node ≥ 20,
-Cloudflare Workers, Deno, and Bun.
+with the exact `raft …` command and plain-data `args`), and the canonical `text`
+a model can read. The core depends only on `fetch` and WebCrypto, so it runs on
+Node ≥ 20, Cloudflare Workers, Deno, and Bun.
+
+**Design rule for serverless runtimes: every continuation is data.** Nothing
+you need between two model steps is a closure or an iterator. The cursor, the
+seen frontier, and a held send's continuation are all plain values you can
+store and pass back into a fresh client in another process.
 
 ```ts
 import { createRaft } from "@botiverse/raft-sdk";
 
-const raft = createRaft({
-  serverUrl: "https://api.raft.build",
-  credential: process.env.RAFT_AGENT_CREDENTIAL!, // sk_agent_*
-});
-
-// A push notice is a content-free wake-up: verify it, then pull.
-export async function onWebhook(request: Request) {
-  const body = new Uint8Array(await request.arrayBuffer());
-  const signal = await raft.wake.verifyNotice({ headers: request.headers, body, secret: WEBHOOK_SECRET });
-  if (!signal.ok) return new Response(signal.message, { status: 401 });
-
-  // A pull never acknowledges. Under `drain`, the pull that acknowledges a
-  // batch is only sent when you ask for the next one, so handle each batch
-  // fully before continuing; a crash midway means the same batch comes back.
-  for await (const batch of raft.inbox.drain()) {
-    for (const message of batch.messages) {
-      model.observe(message.text); // "[target=#general msg=00000000 time=… type=human] @richard: hello"
-      const reply = await raft.messages.reply(message, { content: "on it" }); // idempotency key generated per message
-      if (reply.ok && reply.state === "held") {
-        // Newer messages arrived in that conversation; the outcome carries them.
-        model.observe(reply.text);
-        await reply.data.resend({ seen: "held" });
-      }
+// One model step = one handler invocation, possibly in a new process.
+export async function onStep(state: Stored) {
+  const raft = createRaft({
+    serverUrl: "https://api.raft.build",
+    credential: env.RAFT_AGENT_CREDENTIAL, // sk_agent_*
+    frontier: state.frontier,               // snapshot from the previous step, or null
+  });
+
+  // A pull never acknowledges. Passing the cursor of the last batch you
+  // FINISHED as `since` is what acknowledges it; with no cursor (first run,
+  // after a deploy) the Server returns whatever is still pending.
+  const batch = await raft.inbox.check({ since: state.cursor ?? undefined });
+  if (!batch.ok) throw new Error(batch.text);
+
+  for (const message of batch.data.messages) {
+    model.observe(message.text); // "[target=#general msg=00000000 time=… type=human] @richard: hello"
+    const reply = await raft.messages.reply(message, { content: "on it" }); // idempotencyKey generated
+    if (reply.ok && reply.state === "held") {
+      // Newer messages arrived in that conversation. Show them to the model,
+      // attest that, and continue the same logical send on a later step.
+      model.observe(reply.text);
+      raft.frontier.recordHeld(reply.data);
+      state.pendingSends.push({ target: message.target, content: "on it", ...reply.data.continuation });
     }
-    await recordProcessed(batch.cursor); // your own bookkeeping; the next iteration acknowledges the batch
   }
-  return new Response("ok");
+
+  return { ...state, cursor: batch.data.cursor, frontier: raft.frontier.snapshot() };
 }
+
+// On a later step: same key, attested boundary, no closure needed.
+await raft.messages.send(pending); // { target, content, idempotencyKey, seen: { upToSeq } }
 ```
 
-Prefer `raft.inbox.check({ since })` when you want to hold the cursor yourself:
-pass the cursor of the last batch you finished as `since` on the next call,
-and only that call acknowledges it.
+A push notice is a content-free wake-up: verify it, then pull.
+
+```ts
+const body = new Uint8Array(await request.arrayBuffer());
+const signal = await raft.wake.verifyNotice({ headers: request.headers, body, secret: WEBHOOK_SECRET });
+if (!signal.ok) return new Response(signal.message, { status: 401 });
+// signal.notice.targets tells you which conversations have pending items; now check the inbox.
+```
 
 - `raft.identity.whoami()` — agent, server, capabilities, operating guide.
-- `raft.inbox.check()` / `drain()` / `list()` — one bounded pull, the full
-  `raft message check` loop as an async iterator, or the Activity panel.
+- `raft.inbox.check({ since })` — one bounded pull. **This is the primary
+  path.** `ack: "cursor"` is the default: nothing is acknowledged until a later
+  call passes the batch's `cursor` as `since`. Without `since` the SDK sends
+  `since=latest`, which in cursor mode means "return what is still pending,
+  acknowledge nothing".
+- `raft.inbox.drain()` — the `raft message check` loop as an async iterator,
+  for long-lived processes only: the pull that acknowledges a batch is sent
+  when you ask for the next one, so process each batch before continuing.
+- `raft.inbox.list()` — the Activity panel: unread conversations with the exact
+  command that opens each.
 - `raft.messages.read({ target, after })` / `send()` / `reply(message, …)`.
   Every send gets an `idempotencyKey` (`crypto.randomUUID()`) unless you pass
-  one; a request that never reached the Server is retried with the same key,
-  and a `resend` after a hold reuses it. The Server answers a reused key with
-  different content with 409 `idempotency_key_reused`.
+  one; a request that never reached the Server is retried with the same key.
+  A hold is `state: "held"`: `data.heldMessages` (with `text`), `data.continuation`
+  (`{ idempotencyKey, seen? }`, also in `next.args`) to spread into a later
+  `send`, and `data.resend()` as in-process sugar. Spreading `seen` asserts the
+  model saw the held messages; if you stored the continuation without showing
+  them, drop `seen` and the next send is simply held again. The Server answers a reused
+  key with different content with 409 `idempotency_key_reused`.
 - `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
-  are rows, holds carry `retry()`.
+  are rows, a hold carries `data.request` (the claim to repeat) and `retry()`.
 - `raft.wake.webhook.register({ url, secret })` / `status()` / `unregister()`.
 - `raft.frontier` — what this process has shown its model, per conversation.
-  `messages.read` advances it (to the Server's own model-seen boundary),
-  `inbox.check` records exact seqs, and `send` attests it so a reply into a
-  conversation you have read is not held. Export `raft.frontier.snapshot()`
-  and pass it back as `frontier` to survive restarts, or pass `seen` on a
-  send when your runtime tracks this itself. Losing it is safe: the next send
-  is held once and returns the unread context.
+  `messages.read` advances it to the Server's own model-seen boundary,
+  `inbox.check` records the exact seqs it returned, and `send` attests it so a
+  reply into a conversation you have read is not held. **After a hold, call
+  `raft.frontier.recordHeld(held.data)` once the held messages reached the
+  model**; the SDK never records that implicitly because it cannot know.
+  Persist `raft.frontier.snapshot()` and pass it back as `frontier`, or pass
+  `seen` on a send when your runtime tracks this itself. Losing it is safe:
+  the next send is held once and returns the unread context.
 - `raft.routes.<resource>.<method>()` — every Agent API route, typed from the
   shared contract (see below).
 
 Failures are outcomes too (`ok: false`) with a stable `error.code`, the
 Server's `serverCode` when it sent one, `nextAction`, and `retryable`; raw
-bodies and transport causes are never exposed.
+bodies and transport causes are never exposed. Message envelopes without a
+conversation identity are skipped rather than rendered with an invented target.
 
 ## Usage (0.x API, kept until 1.0.0)
 

package/dist/cjs/index.cjs

@@ -10975,7 +10975,22 @@ function toAgentMessageLike(envelope) {
 		task_current_projection: envelope.task_current_projection ?? envelope.taskCurrentProjection ?? null
 	};
 }
+/**
+* An envelope carries a reply target only when it names its conversation
+* (`channel_type` + `channel_name`, or a third-party event). Some Server
+* responses embed bare envelopes (for example `recentUnread: [{ content }]`);
+* those must not be rendered with a made-up target.
+*/
+function hasAgentMessageIdentity(envelope) {
+	const like = toAgentMessageLike(envelope);
+	if (like.third_party_event) return true;
+	if (typeof like.channel_type !== "string" || typeof like.channel_name !== "string" || !like.channel_name) return false;
+	if (like.channel_type === "thread" && !like.parent_channel_name) return false;
+	return true;
+}
+/** Project one envelope; `null` when it has no conversation identity (skip it rather than render `#undefined`). */
 function projectRaftMessage(envelope) {
+	if (!hasAgentMessageIdentity(envelope)) return null;
 	const like = toAgentMessageLike(envelope);
 	const id = nullableString(like.message_id);
 	const taskNumber = nullableNumber(like.task_number);
@@ -11014,6 +11029,10 @@ function projectRaftMessage(envelope) {
 function sortBySeq(messages) {
 	return [...messages].sort((a, b) => (a.seq ?? Number.MAX_SAFE_INTEGER) - (b.seq ?? Number.MAX_SAFE_INTEGER));
 }
+/** Project a list, skipping envelopes without a conversation identity. */
+function projectRaftMessages(envelopes) {
+	return envelopes.map(projectRaftMessage).filter((m) => m !== null);
+}
 //#endregion
 //#region ../shared/src/agentOps/frontier.ts
 const MAX_EXACT_SEQS = 2500;
@@ -11061,6 +11080,17 @@ var SeenFrontier = class SeenFrontier {
 			for (const seq of keep) state.exact.add(seq);
 		}
 	}
+	/**
+	* Attest that the model saw the context a held send/claim returned. Call it
+	* only after the held messages actually reached the model (the SDK cannot
+	* know that, so it never records this implicitly). Returns false and records
+	* nothing when the context was withheld or the Server sent no boundary.
+	*/
+	recordHeld(held) {
+		if (held.withheld || held.seenUpToSeq === null) return false;
+		this.recordUpTo(held.target, held.seenUpToSeq);
+		return true;
+	}
 	/** What to attest on a send or claim to `target`; omits `seenUpToSeq` when nothing contiguous is known. */
 	attestation(target) {
 		const state = this.targets.get(this.canonical(target));
@@ -11139,7 +11169,7 @@ async function checkInbox(client, request = {}, frontier) {
 	});
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
-	const messages = sortBySeq(data.events.map(projectRaftMessage));
+	const messages = sortBySeq(projectRaftMessages(data.events));
 	recordExactSeen(frontier, messages);
 	const batch = {
 		messages,
@@ -11361,7 +11391,7 @@ async function readHistory(client, request, frontier) {
 	const data = result.data;
 	const page = {
 		target: typeof data.target === "string" && data.target ? data.target : request.target,
-		messages: sortBySeq(data.messages.map(projectRaftMessage)),
+		messages: sortBySeq(projectRaftMessages(data.messages)),
 		hasOlder: data.has_older === true,
 		hasNewer: data.has_newer === true,
 		lastReadSeq: typeof data.last_read_seq === "number" ? data.last_read_seq : null,
@@ -11391,25 +11421,31 @@ function heldText(held, action) {
 }
 function heldNext(held) {
 	return {
-		kind: "review_then_resend",
+		kind: "resend",
 		command: `raft message read --target "${held.target}"`,
 		args: {
 			target: held.target,
-			newMessageCount: held.newMessageCount
+			...held.continuation
 		},
-		why: "Newer messages arrived in this conversation; read them, then resend if the message still applies."
+		why: held.withheld ? "Newer messages exist in this conversation but were withheld; read them, then send again with the same idempotencyKey." : "Newer messages arrived in this conversation. Show the held messages to the model, call frontier.recordHeld(held) to attest that, then send again with these args (same idempotencyKey, seen.upToSeq)."
 	};
 }
-function projectHeld(target, data) {
+function projectHeld(target, data, idempotencyKey) {
 	const withheld = data.freshnessContextMode === "withheld";
-	const heldMessages = (data.heldMessages ?? []).map(projectRaftMessage);
+	const heldMessages = projectRaftMessages(data.heldMessages ?? []);
+	const seenUpToSeq = typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null;
 	return {
 		target,
+		idempotencyKey,
+		continuation: {
+			idempotencyKey,
+			...!withheld && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
+		},
 		newMessageCount: withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length,
 		heldMessages,
 		omittedMessageCount: data.omittedMessageCount ?? 0,
 		formalMentionCount: data.mentionAnnotation?.formalMentionCount ?? 0,
-		seenUpToSeq: typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null,
+		seenUpToSeq,
 		withheld
 	};
 }
@@ -11421,7 +11457,7 @@ function sentOutcome(target, data) {
 		messageId: data.messageId,
 		messageSeq: typeof data.messageSeq === "number" ? data.messageSeq : null,
 		unresolvedMentionHandles: data.unresolvedMentionHandles ?? [],
-		recentUnread: (data.recentUnread ?? []).map(projectRaftMessage)
+		recentUnread: projectRaftMessages(data.recentUnread ?? [])
 	};
 	const warn = sent.unresolvedMentionHandles.length > 0 ? ` Unresolved @handles: ${sent.unresolvedMentionHandles.map((h) => `@${h}`).join(", ")}.` : "";
 	return {
@@ -11468,7 +11504,7 @@ async function sendMessage(client, request, frontier, internal = {}) {
 			idempotencyKey
 		};
 		const held = {
-			...projectHeld(request.target, data),
+			...projectHeld(request.target, data, idempotencyKey),
 			resend: (options) => sendMessage(client, options.seen === "held" && typeof data.seenUpToSeq === "number" ? {
 				...keyed,
 				seen: {
@@ -11555,8 +11591,10 @@ async function claimTasks(client, request) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
+		const { idempotencyKey: _unused, continuation: _c, ...heldBase } = projectHeld(request.target, data, "");
 		const held = {
-			...projectHeld(request.target, data),
+			...heldBase,
+			request,
 			retry: () => claimTasks(client, request)
 		};
 		return {
@@ -11564,13 +11602,10 @@ async function claimTasks(client, request) {
 			state: "held",
 			data: held,
 			next: {
-				kind: "review_then_retry",
+				kind: "retry_claim",
 				command: `raft message read --target "${request.target}"`,
-				args: {
-					target: request.target,
-					newMessageCount: held.newMessageCount
-				},
-				why: "Unread messages in this channel may change the task; read them, then claim again if it is still right."
+				args: { ...request },
+				why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(held) once the model saw them), then claim again with these args if it is still right."
 			},
 			text: `Held — ${held.newMessageCount} unread ${held.newMessageCount === 1 ? "message" : "messages"} in ${request.target}. Your task claim was not applied.\nRead them with: raft message read --target "${request.target}"\nAfter reviewing, rerun the claim if it is still correct.`
 		};
@@ -11832,7 +11867,10 @@ exports.createRaftClient = createRaftClient;
 exports.createRaftClientFromStore = createRaftClientFromStore;
 exports.createRaftRoutes = createRaftRoutes;
 exports.describeRaftRoute = describeRaftRoute;
+exports.hasAgentMessageIdentity = hasAgentMessageIdentity;
 exports.joinRaftChannelByTarget = joinRaftChannelByTarget;
 exports.listRaftRoutes = listRaftRoutes;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
+exports.projectRaftMessage = projectRaftMessage;
+exports.projectRaftMessages = projectRaftMessages;
 exports.verifyInboxNotice = verifyInboxNotice;

package/dist/esm/index.js

@@ -10974,7 +10974,22 @@ function toAgentMessageLike(envelope) {
 		task_current_projection: envelope.task_current_projection ?? envelope.taskCurrentProjection ?? null
 	};
 }
+/**
+* An envelope carries a reply target only when it names its conversation
+* (`channel_type` + `channel_name`, or a third-party event). Some Server
+* responses embed bare envelopes (for example `recentUnread: [{ content }]`);
+* those must not be rendered with a made-up target.
+*/
+function hasAgentMessageIdentity(envelope) {
+	const like = toAgentMessageLike(envelope);
+	if (like.third_party_event) return true;
+	if (typeof like.channel_type !== "string" || typeof like.channel_name !== "string" || !like.channel_name) return false;
+	if (like.channel_type === "thread" && !like.parent_channel_name) return false;
+	return true;
+}
+/** Project one envelope; `null` when it has no conversation identity (skip it rather than render `#undefined`). */
 function projectRaftMessage(envelope) {
+	if (!hasAgentMessageIdentity(envelope)) return null;
 	const like = toAgentMessageLike(envelope);
 	const id = nullableString(like.message_id);
 	const taskNumber = nullableNumber(like.task_number);
@@ -11013,6 +11028,10 @@ function projectRaftMessage(envelope) {
 function sortBySeq(messages) {
 	return [...messages].sort((a, b) => (a.seq ?? Number.MAX_SAFE_INTEGER) - (b.seq ?? Number.MAX_SAFE_INTEGER));
 }
+/** Project a list, skipping envelopes without a conversation identity. */
+function projectRaftMessages(envelopes) {
+	return envelopes.map(projectRaftMessage).filter((m) => m !== null);
+}
 //#endregion
 //#region ../shared/src/agentOps/frontier.ts
 const MAX_EXACT_SEQS = 2500;
@@ -11060,6 +11079,17 @@ var SeenFrontier = class SeenFrontier {
 			for (const seq of keep) state.exact.add(seq);
 		}
 	}
+	/**
+	* Attest that the model saw the context a held send/claim returned. Call it
+	* only after the held messages actually reached the model (the SDK cannot
+	* know that, so it never records this implicitly). Returns false and records
+	* nothing when the context was withheld or the Server sent no boundary.
+	*/
+	recordHeld(held) {
+		if (held.withheld || held.seenUpToSeq === null) return false;
+		this.recordUpTo(held.target, held.seenUpToSeq);
+		return true;
+	}
 	/** What to attest on a send or claim to `target`; omits `seenUpToSeq` when nothing contiguous is known. */
 	attestation(target) {
 		const state = this.targets.get(this.canonical(target));
@@ -11138,7 +11168,7 @@ async function checkInbox(client, request = {}, frontier) {
 	});
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
-	const messages = sortBySeq(data.events.map(projectRaftMessage));
+	const messages = sortBySeq(projectRaftMessages(data.events));
 	recordExactSeen(frontier, messages);
 	const batch = {
 		messages,
@@ -11360,7 +11390,7 @@ async function readHistory(client, request, frontier) {
 	const data = result.data;
 	const page = {
 		target: typeof data.target === "string" && data.target ? data.target : request.target,
-		messages: sortBySeq(data.messages.map(projectRaftMessage)),
+		messages: sortBySeq(projectRaftMessages(data.messages)),
 		hasOlder: data.has_older === true,
 		hasNewer: data.has_newer === true,
 		lastReadSeq: typeof data.last_read_seq === "number" ? data.last_read_seq : null,
@@ -11390,25 +11420,31 @@ function heldText(held, action) {
 }
 function heldNext(held) {
 	return {
-		kind: "review_then_resend",
+		kind: "resend",
 		command: `raft message read --target "${held.target}"`,
 		args: {
 			target: held.target,
-			newMessageCount: held.newMessageCount
+			...held.continuation
 		},
-		why: "Newer messages arrived in this conversation; read them, then resend if the message still applies."
+		why: held.withheld ? "Newer messages exist in this conversation but were withheld; read them, then send again with the same idempotencyKey." : "Newer messages arrived in this conversation. Show the held messages to the model, call frontier.recordHeld(held) to attest that, then send again with these args (same idempotencyKey, seen.upToSeq)."
 	};
 }
-function projectHeld(target, data) {
+function projectHeld(target, data, idempotencyKey) {
 	const withheld = data.freshnessContextMode === "withheld";
-	const heldMessages = (data.heldMessages ?? []).map(projectRaftMessage);
+	const heldMessages = projectRaftMessages(data.heldMessages ?? []);
+	const seenUpToSeq = typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null;
 	return {
 		target,
+		idempotencyKey,
+		continuation: {
+			idempotencyKey,
+			...!withheld && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
+		},
 		newMessageCount: withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length,
 		heldMessages,
 		omittedMessageCount: data.omittedMessageCount ?? 0,
 		formalMentionCount: data.mentionAnnotation?.formalMentionCount ?? 0,
-		seenUpToSeq: typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null,
+		seenUpToSeq,
 		withheld
 	};
 }
@@ -11420,7 +11456,7 @@ function sentOutcome(target, data) {
 		messageId: data.messageId,
 		messageSeq: typeof data.messageSeq === "number" ? data.messageSeq : null,
 		unresolvedMentionHandles: data.unresolvedMentionHandles ?? [],
-		recentUnread: (data.recentUnread ?? []).map(projectRaftMessage)
+		recentUnread: projectRaftMessages(data.recentUnread ?? [])
 	};
 	const warn = sent.unresolvedMentionHandles.length > 0 ? ` Unresolved @handles: ${sent.unresolvedMentionHandles.map((h) => `@${h}`).join(", ")}.` : "";
 	return {
@@ -11467,7 +11503,7 @@ async function sendMessage(client, request, frontier, internal = {}) {
 			idempotencyKey
 		};
 		const held = {
-			...projectHeld(request.target, data),
+			...projectHeld(request.target, data, idempotencyKey),
 			resend: (options) => sendMessage(client, options.seen === "held" && typeof data.seenUpToSeq === "number" ? {
 				...keyed,
 				seen: {
@@ -11554,8 +11590,10 @@ async function claimTasks(client, request) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
+		const { idempotencyKey: _unused, continuation: _c, ...heldBase } = projectHeld(request.target, data, "");
 		const held = {
-			...projectHeld(request.target, data),
+			...heldBase,
+			request,
 			retry: () => claimTasks(client, request)
 		};
 		return {
@@ -11563,13 +11601,10 @@ async function claimTasks(client, request) {
 			state: "held",
 			data: held,
 			next: {
-				kind: "review_then_retry",
+				kind: "retry_claim",
 				command: `raft message read --target "${request.target}"`,
-				args: {
-					target: request.target,
-					newMessageCount: held.newMessageCount
-				},
-				why: "Unread messages in this channel may change the task; read them, then claim again if it is still right."
+				args: { ...request },
+				why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(held) once the model saw them), then claim again with these args if it is still right."
 			},
 			text: `Held — ${held.newMessageCount} unread ${held.newMessageCount === 1 ? "message" : "messages"} in ${request.target}. Your task claim was not applied.\nRead them with: raft message read --target "${request.target}"\nAfter reviewing, rerun the claim if it is still correct.`
 		};
@@ -11818,4 +11853,4 @@ function createRaft(options) {
 	};
 }
 //#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, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, verifyInboxNotice };
+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, joinRaftChannelByTarget, listRaftRoutes, parseRaftRegularChannelTarget, projectRaftMessage, projectRaftMessages, verifyInboxNotice };

package/dist/index.d.ts

@@ -338,8 +338,13 @@ interface RaftNextStep {
   kind: string;
   /** The exact CLI command an agent would run for this step, when one exists. */
   command?: string;
-  /** Structured arguments for the step (target, seq, …). */
-  args?: Record<string, string | number | boolean | null>;
+  /**
+   * Structured arguments for the step: plain, serialisable data (never a
+   * closure), so a runtime whose next step runs in another process can store
+   * it and act on it later — for example spread a held send's `args` into the
+   * next `messages.send`.
+   */
+  args?: Record<string, unknown>;
   /** One sentence explaining why this is the next step. */
   why: string;
 }
@@ -409,6 +414,17 @@ interface RaftMessage {
   /** The wire envelope, for fields this projection does not name. */
   raw: AgentApiMessageEnvelope;
 }
+/**
+ * An envelope carries a reply target only when it names its conversation
+ * (`channel_type` + `channel_name`, or a third-party event). Some Server
+ * responses embed bare envelopes (for example `recentUnread: [{ content }]`);
+ * those must not be rendered with a made-up target.
+ */
+export declare function hasAgentMessageIdentity(envelope: AgentApiMessageEnvelope): boolean;
+/** Project one envelope; `null` when it has no conversation identity (skip it rather than render `#undefined`). */
+export declare function projectRaftMessage(envelope: AgentApiMessageEnvelope): RaftMessage | null;
+/** Project a list, skipping envelopes without a conversation identity. */
+export declare function projectRaftMessages(envelopes: readonly AgentApiMessageEnvelope[]): RaftMessage[];
 //#endregion
 //#region ../shared/src/agentOps/frontier.d.ts
 interface SeenAttestation {
@@ -435,6 +451,17 @@ export declare class SeenFrontier {
   recordUpTo(target: string, seq: number): void;
   /** Record bodies that were rendered without proving contiguity. */
   recordExact(target: string, seqs: readonly number[]): void;
+  /**
+   * Attest that the model saw the context a held send/claim returned. Call it
+   * only after the held messages actually reached the model (the SDK cannot
+   * know that, so it never records this implicitly). Returns false and records
+   * nothing when the context was withheld or the Server sent no boundary.
+   */
+  recordHeld(held: {
+    target: string;
+    seenUpToSeq: number | null;
+    withheld: boolean;
+  }): boolean;
   /** What to attest on a send or claim to `target`; omits `seenUpToSeq` when nothing contiguous is known. */
   attestation(target: string): SeenAttestation;
   snapshot(): SeenFrontierSnapshot;
@@ -564,8 +591,27 @@ interface RaftSent {
   /** Newer messages the Server returned alongside the acceptance, if any. */
   recentUnread: RaftMessage[];
 }
+/**
+ * Plain data that continues a held send in a later process: spread it into
+ * the next `messages.send({ ...original, ...continuation })`. `seen` is set
+ * only when the Server reported a boundary and nothing was withheld.
+ * Spreading `seen` asserts that the model saw the held messages (the same
+ * attestation as `frontier.recordHeld`); drop it if the held text was stored
+ * without being handed to the model, and the next send will be held again
+ * with the same context instead of passing on a false attestation.
+ */
+interface RaftSendContinuation {
+  idempotencyKey: string;
+  seen?: {
+    upToSeq: number;
+  };
+}
 interface RaftHeldBase {
   target: string;
+  /** The idempotency key of the held message; a later send with this key is the same logical message. */
+  idempotencyKey: string;
+  /** Serialisable continuation for the next step (also carried in `next.args`). */
+  continuation: RaftSendContinuation;
   /** How many newer messages the agent has not seen in this conversation. */
   newMessageCount: number;
   /** The newest of them, previewed; the Server may omit older ones. */
@@ -580,9 +626,11 @@ interface RaftHeldBase {
 }
 interface RaftHeld extends RaftHeldBase {
   /**
-   * Send the same message again after the runtime has handled the held context.
-   * `seen: "held"` attests the Server's `seenUpToSeq` (say this only if the model
-   * saw the held messages); `seen: "anyway"` bypasses the freshness check.
+   * In-process sugar over `continuation`: send the same message again after the
+   * runtime has handled the held context. `seen: "held"` attests the Server's
+   * `seenUpToSeq` (say this only if the model saw the held messages);
+   * `seen: "anyway"` bypasses the freshness check. Runtimes whose next step
+   * runs elsewhere store `continuation` (or `next.args`) instead.
    */
   resend(options: {
     seen: "held" | "anyway";
@@ -619,8 +667,10 @@ interface RaftClaimResult {
   /** At least one row authorises work. */
   anyAuthorised: boolean;
 }
-interface RaftClaimHeld extends RaftHeldBase {
-  /** Retry the identical claim after the runtime has handled the held context. */
+interface RaftClaimHeld extends Omit<RaftHeldBase, "idempotencyKey" | "continuation"> {
+  /** The claim to repeat once the held context has been handled (plain data; also in `next.args`). */
+  request: ClaimTasksRequest;
+  /** In-process sugar: retry the identical claim. */
   retry(): Promise<ClaimTasksOutcome>;
 }
 type ClaimTasksOutcome = RaftOutcome<RaftClaimResult, "claimed" | "partial" | "refused"> | RaftOutcome<RaftClaimHeld, "held">;
@@ -9085,4 +9135,4 @@ interface Raft {
 }
 export declare function createRaft(options: CreateRaftOptions): Raft;
 //#endregion
-export type { BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, DrainInboxRequest, ListInboxRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftClaimHeld, 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, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSenderType, RaftSent, RaftServerProfile, RaftServerUpdate, RaftWebhookStatus, ReadHistoryRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, StoredRaftCredential, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };
+export type { BootstrapRaftCredentialOptions, CheckInboxOutcome, CheckInboxRequest, ClaimTasksOutcome, ClaimTasksRequest, CreateRaftClientFromStoreOptions, CreateRaftClientOptions, CreateRaftOptions, CreateRaftRoutesOptions, DrainInboxRequest, ListInboxRequest, Raft, RaftAckMode, RaftActionPrepareRequest, RaftActionPrepared, RaftApiError, RaftApiResult, RaftAppConfig, RaftAppConfigPatch, RaftAvatarUpload, RaftChannelJoinClient, RaftChannelJoinClientResult, RaftChannelJoinError, RaftChannelJoinFailure, RaftChannelJoinOperation, RaftChannelJoinRequest, RaftChannelJoinResult, RaftChannelJoinSuccess, RaftChannelJoinTransportError, RaftClaimHeld, 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, RaftProfile, RaftProfileUpdate, RaftRouteAnnotations, RaftRouteInfo, RaftRouteKey, RaftRouteMeta, RaftRouteResult, RaftRouteRetryPolicy, RaftRoutes, RaftSdkConfigurationErrorCode, RaftSendContinuation, RaftSenderType, RaftSent, RaftServerProfile, RaftServerUpdate, RaftWebhookStatus, ReadHistoryRequest, SeenAttestation, SeenFrontierSnapshot, SendMessageOutcome, SendMessageRequest, StoredRaftCredential, VerifyNoticeInput, VerifyNoticeRejection, VerifyNoticeResult };

package/package.json

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