@botiverse/raft-sdk 0.3.0 → 0.3.2

package/README.md

@@ -363,6 +363,56 @@ record through `options.store`. It returns only non-secret identity metadata.
 Creates the explicit Node.js file store described above. Relative paths and
 unsafe stored-file permissions fail closed.
 
+### `readLatestReadThread(options?)`
+
+Node.js only. Returns the thread this agent read most recently with
+`raft message read` on this machine. It reads the record the Raft CLI keeps
+locally: no credential, no login, and no request to the Server.
+
+```ts
+import { readLatestReadThread } from "@botiverse/raft-sdk";
+
+const latest = await readLatestReadThread();
+if (latest.state === "thread") {
+  console.log(latest.target);       // "#general:1a2b3c4d"
+  console.log(latest.parentTarget); // "#general"
+} else {
+  console.log(latest.reason);
+}
+```
+
+Options, all optional:
+
+- `agentId`: whose reads to look at. Defaults to `SLOCK_AGENT_ID`, which the
+  Raft daemon sets for the agents it runs.
+- `home`: the Raft home directory. Defaults to what the CLI uses: `RAFT_HOME`,
+  then `SLOCK_HOME`, then `~/.slock`.
+- `env`: the environment to take those defaults from. Defaults to
+  `process.env`.
+
+When there is no thread to report, `state` is `"none"` and `reason` is one of:
+
+| `reason` | Meaning |
+| --- | --- |
+| `no_agent_id` | No `agentId` was given and `SLOCK_AGENT_ID` is not set. |
+| `no_record` | The CLI has kept no read record for this agent on this machine. |
+| `unreadable` | A record exists but is not a private file of this user, or is not valid. |
+| `no_reads` | The record holds no read. |
+| `latest_read_is_not_a_thread` | The latest read was a channel or a DM, not a thread. |
+
+What to keep in mind:
+
+- It reports what was read last, not what the work belongs to. An agent that
+  read an unrelated thread afterwards gets that thread. Use the answer as a
+  default to confirm.
+- An older thread is never substituted when the latest read was a channel or
+  a DM.
+- Only `raft message read` counts. `raft message check` and reads made
+  through this SDK's `messages.read()` are not in the CLI's record.
+- A thread target contains the channel name. Do not publish the target of a
+  private channel's thread.
+- The function only reads. It never creates or changes the CLI's record.
+
 ### `createRaftClientFromStore(options)`
 
 Loads and validates one `RaftCredentialStore` record, then creates the same

package/dist/cjs/index.cjs

@@ -3,6 +3,7 @@ let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
+let node_os = require("node:os");
 Object.freeze({ status: "aborted" });
 function $constructor(name, initializer, params) {
 	function init(inst, def) {
@@ -5443,6 +5444,7 @@ const agentApiIntegrationAppUpdateBodySchema = passthroughObject({
 	clientKey: string().trim().min(1),
 	name: optionalStringSchema,
 	description: optionalStringSchema,
+	whenToUse: optionalStringSchema,
 	category: string().trim().min(1).optional(),
 	homepageUrl: optionalStringSchema,
 	returnUrl: optionalStringSchema,
@@ -5623,6 +5625,7 @@ const agentApiIntegrationServiceSchema = passthroughObject({
 	]).optional(),
 	name: string(),
 	description: nullableStringSchema,
+	whenToUse: nullableStringSchema.optional(),
 	homepageUrl: nullableStringSchema,
 	returnUrl: nullableStringSchema,
 	agentManifestUrl: nullableStringSchema,
@@ -11099,6 +11102,43 @@ function sortBySeq(messages) {
 function projectRaftMessages(envelopes) {
 	return envelopes.map(projectRaftMessage).filter((m) => m !== null);
 }
+/** The conversation fields a target string names; `null` for a shape this cannot read. */
+function identityFromTarget(target) {
+	const dm = /^dm:@([^:\s]+)(?::([^:\s]+))?$/.exec(target);
+	if (dm) return dm[2] ? {
+		channel_type: "thread",
+		channel_name: dm[2],
+		parent_channel_name: dm[1],
+		parent_channel_type: "dm"
+	} : {
+		channel_type: "dm",
+		channel_name: dm[1]
+	};
+	const channel = /^#([^:\s]+)(?::([^:\s]+))?$/.exec(target);
+	if (channel) return channel[2] ? {
+		channel_type: "thread",
+		channel_name: channel[2],
+		parent_channel_name: channel[1],
+		parent_channel_type: "channel"
+	} : {
+		channel_type: "channel",
+		channel_name: channel[1]
+	};
+	return null;
+}
+/**
+* Project envelopes that all belong to one known conversation. Some Server
+* responses (held previews) send envelopes without conversation fields
+* because the request already named the target; fill them from `target`
+* instead of dropping the message.
+*/
+function projectRaftMessagesInTarget(envelopes, target) {
+	const identity = identityFromTarget(target);
+	return envelopes.map((envelope) => projectRaftMessage(identity && !hasAgentMessageIdentity(envelope) ? {
+		...envelope,
+		...identity
+	} : envelope)).filter((m) => m !== null);
+}
 //#endregion
 //#region ../shared/src/agentOps/frontier.ts
 const MAX_EXACT_SEQS = 2500;
@@ -11154,10 +11194,11 @@ var SeenFrontier = class SeenFrontier {
 	* 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.
+	* nothing when the context was withheld, not fully shown
+	* (`contextComplete: false`), or the Server sent no boundary.
 	*/
 	recordHeld(held) {
-		if (held.withheld || held.seenUpToSeq === null) return false;
+		if (held.withheld || held.contextComplete === false || held.seenUpToSeq === null) return false;
 		this.recordUpTo(held.target, held.seenUpToSeq);
 		return true;
 	}
@@ -11192,6 +11233,73 @@ var SeenFrontier = class SeenFrontier {
 	}
 };
 //#endregion
+//#region ../shared/src/agentOps/latestReadThread.ts
+const CLI_READ_STATE_NAMESPACE = "slock-cli-consumed-seq";
+const CLI_READ_STATE_FILENAME = "consumed-seqs.json";
+const RAFT_HOME_ENVS = ["RAFT_HOME", "SLOCK_HOME"];
+/** The Raft home the environment configures, or undefined when the default (`~/.slock`) applies. */
+function configuredRaftHome(env) {
+	for (const name of RAFT_HOME_ENVS) {
+		const value = env[name]?.trim();
+		if (value) return value;
+	}
+}
+/** The base directory the environment configures for the read record, or undefined when the default applies. */
+function configuredCliReadStateBase(env) {
+	return env["SLOCK_CLI_CONSUMED_SEQ_STATE_DIR"]?.trim() || configuredRaftHome(env);
+}
+/** An agent id is a path segment of the record's location, so it must be a plain one. */
+function isLocalStateAgentId(agentId) {
+	return /^[A-Za-z0-9_-]+$/.test(agentId);
+}
+/** The record's location under the base directory, as path segments. */
+function cliReadStatePathSegments(agentId) {
+	if (!isLocalStateAgentId(agentId)) throw new Error("Invalid local state agent identity");
+	return [
+		CLI_READ_STATE_NAMESPACE,
+		agentId,
+		CLI_READ_STATE_FILENAME
+	];
+}
+function positiveFinite(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+/** `#channel:thread` → `#channel`, `dm:@peer:thread` → `dm:@peer`; null for a channel or DM root. */
+function parentTargetOfThread(target) {
+	const from = target.startsWith("dm:@") ? 4 : target.startsWith("#") ? 1 : -1;
+	if (from < 0) return null;
+	const separator = target.indexOf(":", from);
+	return separator > 0 && separator < target.length - 1 ? target.slice(0, separator) : null;
+}
+function latestReadThreadFromCliReadState(raw) {
+	const targets = raw && typeof raw === "object" ? raw.targets : void 0;
+	let latestTarget;
+	let latestOrder = 0;
+	if (targets && typeof targets === "object" && !Array.isArray(targets)) for (const [target, value] of Object.entries(targets)) {
+		if (target.length === 0) continue;
+		const record = typeof value === "number" ? { seq: value } : value && typeof value === "object" ? value : {};
+		const order = positiveFinite(record.readOrder) ?? positiveFinite(record.seq);
+		if (order !== void 0 && order > latestOrder) {
+			latestOrder = order;
+			latestTarget = target;
+		}
+	}
+	if (latestTarget === void 0) return {
+		state: "none",
+		reason: "no_reads"
+	};
+	const parentTarget = parentTargetOfThread(latestTarget);
+	if (parentTarget === null) return {
+		state: "none",
+		reason: "latest_read_is_not_a_thread"
+	};
+	return {
+		state: "thread",
+		target: latestTarget,
+		parentTarget
+	};
+}
+//#endregion
 //#region ../shared/src/agentOps/inbox.ts
 const MAX_DRAIN_ROUNDS = 50;
 function batchNext(batch) {
@@ -11487,6 +11595,7 @@ function heldText(held, action) {
 	if (held.formalMentionCount > 0) lines.push(`Note: ${held.formalMentionCount} of these messages formally @mention you.`);
 	if (held.omittedMessageCount > 0) lines.push(`${held.omittedMessageCount} earlier ${held.omittedMessageCount === 1 ? "message" : "messages"} not shown.`);
 	if (held.heldMessages.length > 0) lines.push(formatAgentMessages(held.heldMessages.map((m) => toAgentMessageLike(m.raw))));
+	if (!held.contextComplete) lines.push("Not all of them are shown here; read the conversation before sending again.");
 	lines.push(`Full text: raft message read --target "${held.target}"`);
 	return lines.join("\n");
 }
@@ -11498,26 +11607,30 @@ function heldNext(held) {
 			target: held.target,
 			...held.continuation
 		},
-		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)."
+		why: held.withheld ? "Newer messages exist in this conversation but were withheld; read them, then send again with the same idempotencyKey." : !held.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, 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, idempotencyKey) {
 	const withheld = data.freshnessContextMode === "withheld";
-	const heldMessages = projectRaftMessages(data.heldMessages ?? []);
+	const heldMessages = projectRaftMessagesInTarget(data.heldMessages ?? [], target);
 	const seenUpToSeq = typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null;
+	const newMessageCount = withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length;
+	const omittedMessageCount = data.omittedMessageCount ?? 0;
+	const contextComplete = !withheld && heldMessages.length + omittedMessageCount >= newMessageCount;
 	return {
 		target,
 		idempotencyKey,
 		continuation: {
 			idempotencyKey,
-			...!withheld && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
+			...contextComplete && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
 		},
-		newMessageCount: withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length,
+		newMessageCount,
 		heldMessages,
-		omittedMessageCount: data.omittedMessageCount ?? 0,
+		omittedMessageCount,
 		formalMentionCount: data.mentionAnnotation?.formalMentionCount ?? 0,
 		seenUpToSeq,
-		withheld
+		withheld,
+		contextComplete
 	};
 }
 function isHeldResponse(data) {
@@ -11574,9 +11687,10 @@ async function sendMessage(client, request, frontier, internal = {}) {
 			...request,
 			idempotencyKey
 		};
+		const base = projectHeld(request.target, data, idempotencyKey);
 		const held = {
-			...projectHeld(request.target, data, idempotencyKey),
-			resend: (options) => sendMessage(client, options.seen === "held" && typeof data.seenUpToSeq === "number" ? {
+			...base,
+			resend: (options) => sendMessage(client, options.seen === "held" && base.contextComplete && typeof data.seenUpToSeq === "number" ? {
 				...keyed,
 				seen: {
 					upToSeq: data.seenUpToSeq,
@@ -12308,7 +12422,7 @@ function formatAgentServerInfo(data) {
 	text += "Server-profile changes still use raft server update and remain server-role gated.\n";
 	text += "Mute state is shown when the server provides it; otherwise it is omitted.\n";
 	if (channels.length > 0) for (const t of channels) {
-		const statusParts = [t.type === "private" || t.type === "dm" ? "private" : "public", t.joined ? "joined" : "not joined"];
+		const statusParts = [channelVisibility(t), t.joined ? "joined" : "not joined"];
 		if (t.channelRole) statusParts.push(`channel role=${t.channelRole}`);
 		if (t.channelAdminBasis) statusParts.push(`admin via=${t.channelAdminBasis}`);
 		const muted = channelMuted(t);
@@ -12343,6 +12457,7 @@ function agentChannelRef(name, type) {
 }
 function channelVisibility(channel) {
 	const type = channel.type?.trim();
+	if (type === "joint") return "joint";
 	return type === "private" || type === "dm" ? "private" : "public";
 }
 function channelMuted(channel) {
@@ -13923,12 +14038,67 @@ async function prepareActionCard(client, request) {
 				target: request.target,
 				messageId: card.messageId
 			},
-			why: "A human must click the card to commit it; its outcome arrives in your inbox."
+			why: "A human must click the card to commit it. You are not notified of the result yet; read the card message to see its state instead of waiting."
 		},
 		text: formatAgentActionCardPosted(request.target, card.messageId)
 	};
 }
 //#endregion
+//#region src/latestReadThread.ts
+const MAX_READ_STATE_BYTES = 33554432;
+function firstNonEmpty(...values) {
+	for (const value of values) {
+		const trimmed = value?.trim();
+		if (trimmed) return trimmed;
+	}
+}
+/**
+* The thread this agent read most recently with `raft message read`, when
+* that read is still the latest read of any conversation.
+*
+* It is a fact about what was read, not about what the work belongs to: an
+* agent that read an unrelated thread afterwards gets that thread. Treat the
+* answer as a default to confirm, and keep private channel names out of
+* public places.
+*/
+async function readLatestReadThread(options = {}) {
+	const env = options.env ?? process.env;
+	const agentId = firstNonEmpty(options.agentId, env.SLOCK_AGENT_ID);
+	if (!agentId || !isLocalStateAgentId(agentId)) return {
+		state: "none",
+		reason: "no_agent_id"
+	};
+	const base = firstNonEmpty(options.home, configuredCliReadStateBase(env)) ?? (0, node_path.join)((0, node_os.homedir)(), ".slock");
+	const filePath = (0, node_path.join)(base, ...cliReadStatePathSegments(agentId));
+	let handle;
+	try {
+		handle = await (0, node_fs_promises.open)(filePath, node_fs.constants.O_RDONLY | node_fs.constants.O_NOFOLLOW);
+	} catch (error) {
+		return {
+			state: "none",
+			reason: error.code === "ENOENT" ? "no_record" : "unreadable"
+		};
+	}
+	let raw;
+	try {
+		const stat = await handle.stat();
+		const ownedByUser = typeof process.getuid !== "function" || stat.uid === process.getuid() && (stat.mode & 63) === 0;
+		if (!stat.isFile() || !ownedByUser || stat.size > MAX_READ_STATE_BYTES) return {
+			state: "none",
+			reason: "unreadable"
+		};
+		raw = JSON.parse(await handle.readFile("utf8"));
+	} catch {
+		return {
+			state: "none",
+			reason: "unreadable"
+		};
+	} finally {
+		await handle.close();
+	}
+	return latestReadThreadFromCliReadState(raw);
+}
+//#endregion
 //#region src/raft.ts
 function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
@@ -14134,4 +14304,5 @@ exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
 exports.parseRaftState = parseRaftState;
 exports.projectRaftMessage = projectRaftMessage;
 exports.projectRaftMessages = projectRaftMessages;
+exports.readLatestReadThread = readLatestReadThread;
 exports.verifyInboxNotice = verifyInboxNotice;

package/dist/esm/index.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, link, lstat, mkdir, open, unlink } from "node:fs/promises";
-import { dirname, isAbsolute } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
+import { homedir } from "node:os";
 Object.freeze({ status: "aborted" });
 function $constructor(name, initializer, params) {
 	function init(inst, def) {
@@ -5442,6 +5443,7 @@ const agentApiIntegrationAppUpdateBodySchema = passthroughObject({
 	clientKey: string().trim().min(1),
 	name: optionalStringSchema,
 	description: optionalStringSchema,
+	whenToUse: optionalStringSchema,
 	category: string().trim().min(1).optional(),
 	homepageUrl: optionalStringSchema,
 	returnUrl: optionalStringSchema,
@@ -5622,6 +5624,7 @@ const agentApiIntegrationServiceSchema = passthroughObject({
 	]).optional(),
 	name: string(),
 	description: nullableStringSchema,
+	whenToUse: nullableStringSchema.optional(),
 	homepageUrl: nullableStringSchema,
 	returnUrl: nullableStringSchema,
 	agentManifestUrl: nullableStringSchema,
@@ -11098,6 +11101,43 @@ function sortBySeq(messages) {
 function projectRaftMessages(envelopes) {
 	return envelopes.map(projectRaftMessage).filter((m) => m !== null);
 }
+/** The conversation fields a target string names; `null` for a shape this cannot read. */
+function identityFromTarget(target) {
+	const dm = /^dm:@([^:\s]+)(?::([^:\s]+))?$/.exec(target);
+	if (dm) return dm[2] ? {
+		channel_type: "thread",
+		channel_name: dm[2],
+		parent_channel_name: dm[1],
+		parent_channel_type: "dm"
+	} : {
+		channel_type: "dm",
+		channel_name: dm[1]
+	};
+	const channel = /^#([^:\s]+)(?::([^:\s]+))?$/.exec(target);
+	if (channel) return channel[2] ? {
+		channel_type: "thread",
+		channel_name: channel[2],
+		parent_channel_name: channel[1],
+		parent_channel_type: "channel"
+	} : {
+		channel_type: "channel",
+		channel_name: channel[1]
+	};
+	return null;
+}
+/**
+* Project envelopes that all belong to one known conversation. Some Server
+* responses (held previews) send envelopes without conversation fields
+* because the request already named the target; fill them from `target`
+* instead of dropping the message.
+*/
+function projectRaftMessagesInTarget(envelopes, target) {
+	const identity = identityFromTarget(target);
+	return envelopes.map((envelope) => projectRaftMessage(identity && !hasAgentMessageIdentity(envelope) ? {
+		...envelope,
+		...identity
+	} : envelope)).filter((m) => m !== null);
+}
 //#endregion
 //#region ../shared/src/agentOps/frontier.ts
 const MAX_EXACT_SEQS = 2500;
@@ -11153,10 +11193,11 @@ var SeenFrontier = class SeenFrontier {
 	* 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.
+	* nothing when the context was withheld, not fully shown
+	* (`contextComplete: false`), or the Server sent no boundary.
 	*/
 	recordHeld(held) {
-		if (held.withheld || held.seenUpToSeq === null) return false;
+		if (held.withheld || held.contextComplete === false || held.seenUpToSeq === null) return false;
 		this.recordUpTo(held.target, held.seenUpToSeq);
 		return true;
 	}
@@ -11191,6 +11232,73 @@ var SeenFrontier = class SeenFrontier {
 	}
 };
 //#endregion
+//#region ../shared/src/agentOps/latestReadThread.ts
+const CLI_READ_STATE_NAMESPACE = "slock-cli-consumed-seq";
+const CLI_READ_STATE_FILENAME = "consumed-seqs.json";
+const RAFT_HOME_ENVS = ["RAFT_HOME", "SLOCK_HOME"];
+/** The Raft home the environment configures, or undefined when the default (`~/.slock`) applies. */
+function configuredRaftHome(env) {
+	for (const name of RAFT_HOME_ENVS) {
+		const value = env[name]?.trim();
+		if (value) return value;
+	}
+}
+/** The base directory the environment configures for the read record, or undefined when the default applies. */
+function configuredCliReadStateBase(env) {
+	return env["SLOCK_CLI_CONSUMED_SEQ_STATE_DIR"]?.trim() || configuredRaftHome(env);
+}
+/** An agent id is a path segment of the record's location, so it must be a plain one. */
+function isLocalStateAgentId(agentId) {
+	return /^[A-Za-z0-9_-]+$/.test(agentId);
+}
+/** The record's location under the base directory, as path segments. */
+function cliReadStatePathSegments(agentId) {
+	if (!isLocalStateAgentId(agentId)) throw new Error("Invalid local state agent identity");
+	return [
+		CLI_READ_STATE_NAMESPACE,
+		agentId,
+		CLI_READ_STATE_FILENAME
+	];
+}
+function positiveFinite(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+/** `#channel:thread` → `#channel`, `dm:@peer:thread` → `dm:@peer`; null for a channel or DM root. */
+function parentTargetOfThread(target) {
+	const from = target.startsWith("dm:@") ? 4 : target.startsWith("#") ? 1 : -1;
+	if (from < 0) return null;
+	const separator = target.indexOf(":", from);
+	return separator > 0 && separator < target.length - 1 ? target.slice(0, separator) : null;
+}
+function latestReadThreadFromCliReadState(raw) {
+	const targets = raw && typeof raw === "object" ? raw.targets : void 0;
+	let latestTarget;
+	let latestOrder = 0;
+	if (targets && typeof targets === "object" && !Array.isArray(targets)) for (const [target, value] of Object.entries(targets)) {
+		if (target.length === 0) continue;
+		const record = typeof value === "number" ? { seq: value } : value && typeof value === "object" ? value : {};
+		const order = positiveFinite(record.readOrder) ?? positiveFinite(record.seq);
+		if (order !== void 0 && order > latestOrder) {
+			latestOrder = order;
+			latestTarget = target;
+		}
+	}
+	if (latestTarget === void 0) return {
+		state: "none",
+		reason: "no_reads"
+	};
+	const parentTarget = parentTargetOfThread(latestTarget);
+	if (parentTarget === null) return {
+		state: "none",
+		reason: "latest_read_is_not_a_thread"
+	};
+	return {
+		state: "thread",
+		target: latestTarget,
+		parentTarget
+	};
+}
+//#endregion
 //#region ../shared/src/agentOps/inbox.ts
 const MAX_DRAIN_ROUNDS = 50;
 function batchNext(batch) {
@@ -11486,6 +11594,7 @@ function heldText(held, action) {
 	if (held.formalMentionCount > 0) lines.push(`Note: ${held.formalMentionCount} of these messages formally @mention you.`);
 	if (held.omittedMessageCount > 0) lines.push(`${held.omittedMessageCount} earlier ${held.omittedMessageCount === 1 ? "message" : "messages"} not shown.`);
 	if (held.heldMessages.length > 0) lines.push(formatAgentMessages(held.heldMessages.map((m) => toAgentMessageLike(m.raw))));
+	if (!held.contextComplete) lines.push("Not all of them are shown here; read the conversation before sending again.");
 	lines.push(`Full text: raft message read --target "${held.target}"`);
 	return lines.join("\n");
 }
@@ -11497,26 +11606,30 @@ function heldNext(held) {
 			target: held.target,
 			...held.continuation
 		},
-		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)."
+		why: held.withheld ? "Newer messages exist in this conversation but were withheld; read them, then send again with the same idempotencyKey." : !held.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, 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, idempotencyKey) {
 	const withheld = data.freshnessContextMode === "withheld";
-	const heldMessages = projectRaftMessages(data.heldMessages ?? []);
+	const heldMessages = projectRaftMessagesInTarget(data.heldMessages ?? [], target);
 	const seenUpToSeq = typeof data.seenUpToSeq === "number" ? data.seenUpToSeq : null;
+	const newMessageCount = withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length;
+	const omittedMessageCount = data.omittedMessageCount ?? 0;
+	const contextComplete = !withheld && heldMessages.length + omittedMessageCount >= newMessageCount;
 	return {
 		target,
 		idempotencyKey,
 		continuation: {
 			idempotencyKey,
-			...!withheld && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
+			...contextComplete && seenUpToSeq !== null ? { seen: { upToSeq: seenUpToSeq } } : {}
 		},
-		newMessageCount: withheld ? data.withheldMessageCount ?? 0 : data.newMessageCount ?? heldMessages.length,
+		newMessageCount,
 		heldMessages,
-		omittedMessageCount: data.omittedMessageCount ?? 0,
+		omittedMessageCount,
 		formalMentionCount: data.mentionAnnotation?.formalMentionCount ?? 0,
 		seenUpToSeq,
-		withheld
+		withheld,
+		contextComplete
 	};
 }
 function isHeldResponse(data) {
@@ -11573,9 +11686,10 @@ async function sendMessage(client, request, frontier, internal = {}) {
 			...request,
 			idempotencyKey
 		};
+		const base = projectHeld(request.target, data, idempotencyKey);
 		const held = {
-			...projectHeld(request.target, data, idempotencyKey),
-			resend: (options) => sendMessage(client, options.seen === "held" && typeof data.seenUpToSeq === "number" ? {
+			...base,
+			resend: (options) => sendMessage(client, options.seen === "held" && base.contextComplete && typeof data.seenUpToSeq === "number" ? {
 				...keyed,
 				seen: {
 					upToSeq: data.seenUpToSeq,
@@ -12307,7 +12421,7 @@ function formatAgentServerInfo(data) {
 	text += "Server-profile changes still use raft server update and remain server-role gated.\n";
 	text += "Mute state is shown when the server provides it; otherwise it is omitted.\n";
 	if (channels.length > 0) for (const t of channels) {
-		const statusParts = [t.type === "private" || t.type === "dm" ? "private" : "public", t.joined ? "joined" : "not joined"];
+		const statusParts = [channelVisibility(t), t.joined ? "joined" : "not joined"];
 		if (t.channelRole) statusParts.push(`channel role=${t.channelRole}`);
 		if (t.channelAdminBasis) statusParts.push(`admin via=${t.channelAdminBasis}`);
 		const muted = channelMuted(t);
@@ -12342,6 +12456,7 @@ function agentChannelRef(name, type) {
 }
 function channelVisibility(channel) {
 	const type = channel.type?.trim();
+	if (type === "joint") return "joint";
 	return type === "private" || type === "dm" ? "private" : "public";
 }
 function channelMuted(channel) {
@@ -13922,12 +14037,67 @@ async function prepareActionCard(client, request) {
 				target: request.target,
 				messageId: card.messageId
 			},
-			why: "A human must click the card to commit it; its outcome arrives in your inbox."
+			why: "A human must click the card to commit it. You are not notified of the result yet; read the card message to see its state instead of waiting."
 		},
 		text: formatAgentActionCardPosted(request.target, card.messageId)
 	};
 }
 //#endregion
+//#region src/latestReadThread.ts
+const MAX_READ_STATE_BYTES = 33554432;
+function firstNonEmpty(...values) {
+	for (const value of values) {
+		const trimmed = value?.trim();
+		if (trimmed) return trimmed;
+	}
+}
+/**
+* The thread this agent read most recently with `raft message read`, when
+* that read is still the latest read of any conversation.
+*
+* It is a fact about what was read, not about what the work belongs to: an
+* agent that read an unrelated thread afterwards gets that thread. Treat the
+* answer as a default to confirm, and keep private channel names out of
+* public places.
+*/
+async function readLatestReadThread(options = {}) {
+	const env = options.env ?? process.env;
+	const agentId = firstNonEmpty(options.agentId, env.SLOCK_AGENT_ID);
+	if (!agentId || !isLocalStateAgentId(agentId)) return {
+		state: "none",
+		reason: "no_agent_id"
+	};
+	const base = firstNonEmpty(options.home, configuredCliReadStateBase(env)) ?? join(homedir(), ".slock");
+	const filePath = join(base, ...cliReadStatePathSegments(agentId));
+	let handle;
+	try {
+		handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+	} catch (error) {
+		return {
+			state: "none",
+			reason: error.code === "ENOENT" ? "no_record" : "unreadable"
+		};
+	}
+	let raw;
+	try {
+		const stat = await handle.stat();
+		const ownedByUser = typeof process.getuid !== "function" || stat.uid === process.getuid() && (stat.mode & 63) === 0;
+		if (!stat.isFile() || !ownedByUser || stat.size > MAX_READ_STATE_BYTES) return {
+			state: "none",
+			reason: "unreadable"
+		};
+		raw = JSON.parse(await handle.readFile("utf8"));
+	} catch {
+		return {
+			state: "none",
+			reason: "unreadable"
+		};
+	} finally {
+		await handle.close();
+	}
+	return latestReadThreadFromCliReadState(raw);
+}
+//#endregion
 //#region src/raft.ts
 function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
@@ -14108,4 +14278,4 @@ function createRaft(options) {
 	};
 }
 //#endregion
-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 };
+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, readLatestReadThread, verifyInboxNotice };

package/dist/index.d.ts

@@ -457,12 +457,14 @@ export declare class SeenFrontier {
    * 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.
+   * nothing when the context was withheld, not fully shown
+   * (`contextComplete: false`), or the Server sent no boundary.
    */
   recordHeld(held: {
     target: string;
     seenUpToSeq: number | null;
     withheld: boolean;
+    contextComplete?: boolean;
   }): boolean;
   /** What to attest on a send or claim to `target`; omits `seenUpToSeq` when nothing contiguous is known. */
   attestation(target: string): SeenAttestation;
@@ -625,6 +627,13 @@ interface RaftHeldBase {
   seenUpToSeq: number | null;
   /** Reviewer isolation: bodies withheld, only a count. */
   withheld: boolean;
+  /**
+   * Whether `heldMessages` plus `omittedMessageCount` account for every one of
+   * `newMessageCount`. When false the model cannot have seen all of them, so
+   * no `seen` is offered and `frontier.recordHeld` records nothing; read the
+   * conversation instead.
+   */
+  contextComplete: boolean;
 }
 interface RaftHeld extends RaftHeldBase {
   /**
@@ -1857,6 +1866,7 @@ declare const agentApiIntegrationAppUpdateBodySchema: z.ZodObject<{
   clientKey: z.ZodString;
   name: z.ZodOptional<z.ZodString>;
   description: z.ZodOptional<z.ZodString>;
+  whenToUse: z.ZodOptional<z.ZodString>;
   category: z.ZodOptional<z.ZodString>;
   homepageUrl: z.ZodOptional<z.ZodString>;
   returnUrl: z.ZodOptional<z.ZodString>;
@@ -2120,6 +2130,7 @@ declare const agentApiIntegrationListResponseSchema: z.ZodObject<{
     }>>;
     name: z.ZodString;
     description: z.ZodNullable<z.ZodString>;
+    whenToUse: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     homepageUrl: z.ZodNullable<z.ZodString>;
     returnUrl: z.ZodNullable<z.ZodString>;
     agentManifestUrl: z.ZodNullable<z.ZodString>;
@@ -2198,6 +2209,7 @@ declare const agentApiIntegrationLoginResponseSchema: z.ZodObject<{
     }>>;
     name: z.ZodString;
     description: z.ZodNullable<z.ZodString>;
+    whenToUse: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     homepageUrl: z.ZodNullable<z.ZodString>;
     returnUrl: z.ZodNullable<z.ZodString>;
     agentManifestUrl: z.ZodNullable<z.ZodString>;
@@ -7291,6 +7303,7 @@ declare const agentApiContract: {
           }>>;
           name: z.ZodString;
           description: z.ZodNullable<z.ZodString>;
+          whenToUse: z.ZodOptional<z.ZodNullable<z.ZodString>>;
           homepageUrl: z.ZodNullable<z.ZodString>;
           returnUrl: z.ZodNullable<z.ZodString>;
           agentManifestUrl: z.ZodNullable<z.ZodString>;
@@ -7412,6 +7425,7 @@ declare const agentApiContract: {
           }>>;
           name: z.ZodString;
           description: z.ZodNullable<z.ZodString>;
+          whenToUse: z.ZodOptional<z.ZodNullable<z.ZodString>>;
           homepageUrl: z.ZodNullable<z.ZodString>;
           returnUrl: z.ZodNullable<z.ZodString>;
           agentManifestUrl: z.ZodNullable<z.ZodString>;
@@ -7603,6 +7617,7 @@ declare const agentApiContract: {
         clientKey: z.ZodString;
         name: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        whenToUse: z.ZodOptional<z.ZodString>;
         category: z.ZodOptional<z.ZodString>;
         homepageUrl: z.ZodOptional<z.ZodString>;
         returnUrl: z.ZodOptional<z.ZodString>;
@@ -9305,6 +9320,46 @@ export declare function createRaftClientFromStore(options: CreateRaftClientFromS
  */
 export declare function createFileCredentialStore(filePath: string): RaftCredentialStore;
 //#endregion
+//#region src/latestReadThread.d.ts
+interface ReadLatestReadThreadOptions {
+  /** The agent whose reads to look at. Defaults to `SLOCK_AGENT_ID` from `env`. */
+  agentId?: string;
+  /**
+   * The Raft home directory the CLI uses. Defaults to what the CLI resolves
+   * from `env`: `RAFT_HOME`, then `SLOCK_HOME`, then `~/.slock`.
+   */
+  home?: string;
+  /** Environment to resolve the defaults from. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+}
+type RaftLatestReadThread = {
+  state: "thread";
+  /** The thread target, as `raft message read --target` takes it, for example `#general:1a2b3c4d`. */
+  target: string;
+  /** The channel or DM the thread belongs to, for example `#general`. */
+  parentTarget: string;
+} | {
+  state: "none";
+  /**
+   * - `no_agent_id`: no `agentId` was given and `SLOCK_AGENT_ID` is not set (or is not a valid id).
+   * - `no_record`: the CLI has kept no read record for this agent here.
+   * - `unreadable`: a record exists but is not a private regular file of this user, is too large, or is not JSON.
+   * - `no_reads`: the record holds no read.
+   * - `latest_read_is_not_a_thread`: the latest read was a channel or DM root. An older thread is never substituted.
+   */
+  reason: "no_agent_id" | "no_record" | "unreadable" | "no_reads" | "latest_read_is_not_a_thread";
+};
+/**
+ * The thread this agent read most recently with `raft message read`, when
+ * that read is still the latest read of any conversation.
+ *
+ * It is a fact about what was read, not about what the work belongs to: an
+ * agent that read an unrelated thread afterwards gets that thread. Treat the
+ * answer as a default to confirm, and keep private channel names out of
+ * public places.
+ */
+export declare function readLatestReadThread(options?: ReadLatestReadThreadOptions): Promise<RaftLatestReadThread>;
+//#endregion
 //#region src/raft.d.ts
 interface CreateRaftOptions {
   /** Raft Server origin, for example `https://api.raft.build`. */
@@ -9534,4 +9589,4 @@ interface Raft {
 }
 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, 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 };
+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, RaftLatestReadThread, 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, ReadLatestReadThreadOptions, 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": "0.3.0",
+  "version": "0.3.2",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",