@botiverse/raft-sdk 0.3.0 → 0.3.1

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,
@@ -11192,6 +11195,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) {
@@ -12308,7 +12378,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 +12413,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 +13994,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 +14260,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,
@@ -11191,6 +11194,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) {
@@ -12307,7 +12377,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 +12412,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 +13993,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 +14234,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

@@ -1857,6 +1857,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 +2121,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 +2200,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 +7294,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 +7416,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 +7608,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 +9311,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 +9580,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.1",
   "license": "FSL-1.1-ALv2",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",