dsh-cherry-bridge 0.1.10 → 0.1.11

package/dist/index.mjs

@@ -4881,6 +4881,59 @@ const MESSAGE_CACHE_ENTRY_BYTES = 1048576;
 */
 const MESSAGE_CACHE_BYTES_PER_DEVICE = 33554432;
 /**
+* How many command bodies the engine remembers PER DEVICE, keyed by the
+* CALLER-SUPPLIED `commandId` (issues #115, #118).
+*
+* Why a memory exists at all: a command's recovery path is RECEIPT. A reply
+* lost on the wire is answered by re-sending the ORIGINAL body under the
+* original id, and the desktop's ledger replays the recorded outcome. That
+* promise was impossible for `cherry_send`, whose body carries a DERIVED field
+* (`expectedIdleRevision`) that moves with every successful send: the retry
+* quoted a fresh baseline, the body differed from the recorded one, and the peer
+* answered IDEMPOTENCY_CONFLICT — on the one path where the caller cannot tell
+* what already landed. So the engine remembers the EXACT body it emitted, per
+* (device, caller id, method), and a same-id retry replays it verbatim. The
+* same defect had a harder shape in `cherry_respond` / `cherry_cancel` (issue
+* #118): their DERIVED fields were re-derived, and the retry usually met a
+* pre-check (`unknown-interaction`, `no-active-execution`) before the body was
+* ever compared — the memory is consulted before those, which is why it holds
+* the whole issued body rather than a way to rebuild one.
+*
+* What an entry holds is one short body: a session id, the caller's text (at
+* most the protocol's 32,768 characters, pre-validated before it is ever
+* stored), one revision string — or, for respond/cancel, the interaction's
+* staleness triple / the execution to abort, plus the caller-owned arguments
+* the fingerprint compares. 128 is "more than any live retry window needs,
+* small enough to be trivial": a caller retries a handful of command ids around
+* a lost reply, and each is recoverable while it stays in this FIFO.
+* Eviction costs a REQUEST, never correctness — an evicted id has NO entry, so
+* a same-id retry re-derives a fresh baseline. For a SEND the re-derived body
+* reaches the peer, which refuses the differing body exactly as it would
+* without this memory; for a RESPOND or CANCEL the retry usually dies earlier,
+* at the LOCAL pre-checks (`unknown-interaction`, `no-active-execution`,
+* `execution-mismatch`) — the pre-fix failure mode, which names real state.
+*
+* PER DEVICE, like every engine cache: the id is the caller's, but the peer
+* that settled it is not, and a second desktop must never be sent a body minted
+* against the first.
+*
+* INJECTABLE for tests (`commandBodyEntriesPerDevice`), because the production
+* value needs 129 live command ids before it evicts.
+*/
+const COMMAND_BODY_ENTRIES_PER_DEVICE = 128;
+/**
+* The three command methods whose bodies the engine remembers (see
+* {@link COMMAND_BODY_ENTRIES_PER_DEVICE}).
+*
+* Named once, because they are used twice each by design: as the remembered
+* entry's `method`, and as the method the entry is compared against on lookup.
+* Spelling them at both ends is how a lookup could start matching the wrong
+* tool without any type noticing.
+*/
+const SEND_METHOD = "agent.messages.send";
+const RESPOND_METHOD = "agent.interactions.respond";
+const CANCEL_METHOD = "agent.executions.cancel";
+/**
 * EMPTY-PAGE RUN limit for every aggregate walk. The desktop's pinned-list walk
 * legally answers ONE empty page with an advancing cursor (the pin→entity
 * section transition, `{items: [], nextCursor: 'entity:'}`), so a single empty
@@ -5093,6 +5146,79 @@ function unavailableReason(error) {
 */
 const IDEMPOTENCY_HINT = "the peer already recorded this commandId with a different body; regenerate the commandId for a retry whose parameters changed — never reuse an id with a different body (re-send the ORIGINAL body to replay the original receipt).";
 /**
+* The peer's own wording for `IDEMPOTENCY_CONFLICT` (its `agentHandlers` throws
+* exactly this), used when the ENGINE is the one that knows the body differs —
+* a caller-supplied `commandId` it has already emitted with other arguments
+* (issue #115).
+*
+* The refusal is LOCAL because the outcome is already decided: the peer's ledger
+* holds the recorded body, so a forwarded body would come back as this same
+* conflict, one round trip later, at the cost of a wire call that can never
+* succeed. Reusing the sentence keeps ONE vocabulary for one condition; callers
+* (and the existing conflict tests) match on the prefix.
+*/
+const COMMAND_BODY_DIFFERS_MESSAGE = "Command body differs from the recorded command";
+/**
+* The JSON-RPC error code the transport reserves for protocol failures (the
+* server answers every peer-refused request with it). Used for the LOCAL
+* {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal so it is the same currency a
+* forwarded one would have been: a `JsonRpcRequestError` carrying
+* `{reason: 'IDEMPOTENCY_CONFLICT'}`, distinguishable only by the fact that no
+* request was ever sent.
+*
+* A LOCAL twin of the literal `src/rpc/jsonRpcClient.ts` documents in its own
+* `JsonRpcRequestError` docblock: that module exports no code constant, and
+* adding one only to name this number would widen the published surface for it.
+*/
+const JSON_RPC_PROTOCOL_ERROR_CODE = 1e3;
+/**
+* The LOCAL {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal — the peer's own
+* reason and sentence, wrapped with the same hints a forwarded conflict earns,
+* and never sent anywhere.
+*
+* ONE constructor for every command that remembers its body (send, respond,
+* cancel): the caller must not have to learn a second vocabulary for one
+* condition, and a test matches the prefix `Command body differs` whichever
+* tool produced it.
+*/
+function commandBodyDiffers() {
+	const conflict = new JsonRpcRequestError(JSON_RPC_PROTOCOL_ERROR_CODE, COMMAND_BODY_DIFFERS_MESSAGE, {
+		reason: "IDEMPOTENCY_CONFLICT",
+		message: COMMAND_BODY_DIFFERS_MESSAGE
+	});
+	withRateLimitHint(withIdempotencyHint(conflict));
+	return conflict;
+}
+/**
+* DEEP structural equality, for the caller-owned half of a remembered command
+* body (issue #118).
+*
+* `cherry_respond`'s `response.answers` is a RECORD: two callers sending the
+* same answers in a different KEY ORDER are sending the SAME answer, and a
+* plain `!==` (or a JSON string comparison) would refuse the retry as a
+* different body — turning the receipt recovery into a local conflict on the
+* exact shapes it exists for. Arrays stay ORDERED: `questions` is a list, and
+* reordering it really is a different value.
+*
+* Deliberately small: the values compared here are tool arguments decoded from
+* JSON, so only JSON's two container kinds, the primitives, and `undefined`
+* (an omitted optional argument) need to be understood.
+*/
+function sameCommandValue(left, right) {
+	if (left === right) return true;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right)) return false;
+		if (left.length !== right.length) return false;
+		return left.every((value, index) => sameCommandValue(value, right[index]));
+	}
+	if (isRecord(left) && isRecord(right)) {
+		const leftKeys = Object.keys(left);
+		if (leftKeys.length !== Object.keys(right).length) return false;
+		return leftKeys.every((key) => Object.hasOwn(right, key) && sameCommandValue(left[key], right[key]));
+	}
+	return false;
+}
+/**
 * Passes a command failure through UNCHANGED, except that `IDEMPOTENCY_CONFLICT`
 * gets {@link IDEMPOTENCY_HINT} appended to its message.
 *
@@ -5275,14 +5401,37 @@ const CHERRY_TOOL_NAMES = [
 * those tasks add mutating tools without touching the host seam.
 */
 function registerCherryTools(ctx, deps, options = {}) {
+	return registerCherryToolsWithEngine(ctx, deps, options).dispose;
+}
+/**
+* The same registration, with the ENGINE it built handed back.
+*
+* Exists for TESTS: the engine's memory bookkeeping (the remembered command
+* bodies, the bounds they obey) is private to it on purpose, and the only
+* honest way to pin "bounded" and "dropped with the device" is to observe it
+* through this one seam instead of inferring it from retry outcomes that are
+* identical for an evicted entry and for one that never existed.
+*
+* Both this function and `export class CherryToolEngine` are SHIPPED names
+* (`src` is published on purpose, see AGENTS.md → Build facts), so they are a
+* compatibility commitment — which is why this seam is kept minimal.
+*/
+function registerCherryToolsWithEngine(ctx, deps, options = {}) {
 	const tools = ctx.tools;
 	if (tools === void 0) {
 		console.warn("[cherry-remote] ctx.tools is unavailable; the cherry_* tools were not registered");
-		return () => {};
+		return {
+			dispose: () => {},
+			engine: void 0
+		};
 	}
-	const disposers = new CherryToolEngine(deps, options).definitions().map((definition) => tools.register(definition));
-	return () => {
-		for (const dispose of disposers) dispose();
+	const engine = new CherryToolEngine(deps, options);
+	const disposers = engine.definitions().map((definition) => tools.register(definition));
+	return {
+		engine,
+		dispose: () => {
+			for (const dispose of disposers) dispose();
+		}
 	};
 }
 /** One tool declaration, in the exact shape the host registry consumes. */
@@ -5378,6 +5527,12 @@ var CherryToolEngine = class {
 	*/
 	#contentGate;
 	/**
+	* The `maxBytes` one `agent.content.read` slice asks for
+	* ({@link CONTENT_READ_MAX_BYTES} in production; injectable so a test can
+	* reach a walk's second slice, see `CherryToolEngineOptions`).
+	*/
+	#contentReadSliceBytes;
+	/**
 	* The parts pages already walked, keyed `<deviceId>\0<messageId>`.
 	*
 	* WHAT IS HELD is the RESULT of `agent.parts.list` — the raw part records plus
@@ -5444,6 +5599,49 @@ var CherryToolEngine = class {
 	* not pinned by bookkeeping.
 	*/
 	#watchedConnections = /* @__PURE__ */ new WeakSet();
+	/**
+	* The EXACT command body emitted for each (device, caller id, method), so a
+	* lost reply can be recovered by receipt (issues #115, #118).
+	*
+	* Keyed `<deviceId>\0<commandId>`, exactly like every other engine cache. The
+	* value is a {@link RememberedCommand}: the METHOD it was minted for, the
+	* caller-owned FINGERPRINT a retry must match, and the BODY the retry
+	* replays verbatim. The fingerprint is what must MATCH — a same-id call whose
+	* arguments differ is not a retry of this command at all, and is refused
+	* locally rather than sent. The body is what must be REPLAYED, derived
+	* fields included: that is the whole point, because those fields are the ones
+	* a retry cannot re-derive the same way.
+	*
+	* Three tools remember: `agent.messages.send` (the baseline it quoted),
+	* `agent.interactions.respond` (the staleness triple) and
+	* `agent.executions.cancel` (the execution it was told to abort). Two of
+	* them run PRE-CHECKS before composing a body — respond's
+	* `unknown-interaction`, cancel's `no-active-execution`/`execution-mismatch` —
+	* and after a lost reply those pre-checks are usually the first thing the
+	* retry meets, because the first attempt is what SETTLED the interaction and
+	* ENDED the run. So a caller-supplied id is consulted BEFORE any derivation:
+	* a remembered retry is an answer, not a fresh call.
+	*
+	* WHAT IS REMEMBERED: only CALLER-SUPPLIED ids. An auto-generated uuid is a
+	* one-shot identity — nobody can retry it, so an entry for it is pure leak.
+	* The entry is written the moment the command is ISSUED, before the reply is
+	* awaited: a reply lost on the wire must not cost the only copy of the bytes
+	* the peer's ledger will accept.
+	*
+	* Which body an id holds: the LATEST attempt issued for it — the first
+	* attempt, or the self-heal's fresh-uuid retry when one ran. After a heal, a
+	* same-id retry is therefore answered with the peer's conflict, deliberately:
+	* replaying the ledger's rejected receipt would re-run the healed admission
+	* and duplicate the run, and a conflict is the safer failure.
+	*
+	* Bounded FIFO, per device; dropped when the PAIRING is invalidated (unpair,
+	* identity-mismatch) but KEPT across an ordinary reconnect — see
+	* {@link COMMAND_BODY_ENTRIES_PER_DEVICE} and
+	* {@link CherryToolEngine.#forgetDevice}.
+	*/
+	#commandBodies = /* @__PURE__ */ new Map();
+	/** The per-device cap on {@link CherryToolEngine.#commandBodies}. */
+	#commandBodyEntriesPerDevice;
 	constructor(deps, options = {}) {
 		this.#deps = deps;
 		this.#partsSafetyBound = Math.max(1, Math.floor(options.partsSafetyBound ?? DEFAULT_PARTS_SAFETY_BOUND));
@@ -5452,7 +5650,9 @@ var CherryToolEngine = class {
 		this.#cacheEntriesPerDevice = Math.max(1, Math.floor(options.cacheEntriesPerDevice ?? CACHE_ENTRIES_PER_DEVICE));
 		this.#messageCacheEntryBytes = Math.max(1, Math.floor(options.messageCacheEntryBytes ?? MESSAGE_CACHE_ENTRY_BYTES));
 		this.#messageCacheBytesPerDevice = Math.max(1, Math.floor(options.messageCacheBytesPerDevice ?? MESSAGE_CACHE_BYTES_PER_DEVICE));
+		this.#commandBodyEntriesPerDevice = Math.max(1, Math.floor(options.commandBodyEntriesPerDevice ?? COMMAND_BODY_ENTRIES_PER_DEVICE));
 		this.#contentGate = new ContentReadGate(options.contentReadConcurrency ?? DEFAULT_CONTENT_READ_CONCURRENCY);
+		this.#contentReadSliceBytes = Math.max(1, Math.floor(options.contentReadSliceBytes ?? CONTENT_READ_MAX_BYTES));
 	}
 	definitions() {
 		return [
@@ -6015,7 +6215,7 @@ var CherryToolEngine = class {
 	#readTool() {
 		return defineCherryTool({
 			name: "cherry_read",
-			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A failed message (`status: \"error\"`) may carry `failure: {reasonCode, retryable, message}` when the peer sent one — its classification, whether it judged a retry worthwhile, and a bounded summary; the peer's `source` and `context.responseBody` are never projected. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
+			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. An attachment is reported as METADATA, never as its bytes: a `kind: \"file\"` part, or a legacy `data` part named `file` (the metadata as JSON in `content.text`), comes back as `name`/`mediaType` (plus `byteLength` for the `file` kind) with `content` emptied — or kept verbatim when that record carries a key this projection does not report. The bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A failed message (`status: \"error\"`) may carry `failure: {reasonCode, retryable, message}` when the peer sent one — its classification, whether it judged a retry worthwhile, and a bounded summary; the peer's `source` and `context.responseBody` are never projected. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6276,38 +6476,115 @@ var CherryToolEngine = class {
 				releaseSlot?.();
 			}
 		} else text = "";
+		const legacy = this.#legacyAttachment(kind, raw, text);
 		return {
 			partId,
 			kind,
 			revision,
-			content: text,
-			...this.#attachmentFace(kind, raw, content),
+			content: legacy === void 0 ? text : legacy.remainder,
+			...legacy === void 0 ? this.#attachmentFace(kind, raw, content) : this.#attachmentFace(kind, raw, content, legacy.record),
 			...typeof raw["state"] === "string" ? { state: raw["state"] } : {},
 			...typeof raw["toolName"] === "string" ? { toolName: raw["toolName"] } : {},
 			...typeof raw["toolCallId"] === "string" ? { toolCallId: raw["toolCallId"] } : {}
 		};
 	}
 	/**
+	* The ONE place a legacy `data` part is recognised as an attachment: the
+	* structural discriminator, the JSON parse, and the lossless CONTENT rule.
+	*
+	* The legal legacy face is `{kind: 'data', name: 'file', content: {text:
+	* '{\"mediaType\":…,\"filename\":…}'}}` — the metadata SERIALIZED AS JSON in
+	* `content.text`, observed on the wire (2.1.7 desktop, image upload,
+	* 2026-10-22). An OBJECT inside `content` is not producible by a conforming
+	* peer at all: the pinned protocol 0.5.0 types `content` as a strict
+	* `{text}` | `{ref}` union, so the old documentation described a shape no
+	* peer can emit — and the real one was never lifted, which is how an image
+	* upload reached a model as a JSON blob.
+	*
+	* WHY THE NAME IS THE DISCRIMINATOR, and why it is not a heuristic: the
+	* desktop labels every `data` part with its data KIND in `name` — an
+	* attachment is `'file'`, a task event is `'data-compaction-anchor'`, an
+	* error is `'data-error'` — and the protocol types that field as an
+	* `opaqueId`. This lift therefore REQUIRES the label to be the literal
+	* `'file'` rather than ASSUMING every peer sets one: a `data` part that
+	* carries no name reads as no name, is not lifted, and passes through
+	* untouched. Several of those payloads are JSON too, so "the text parses"
+	* proves nothing; `'file'` is the one label that means "this is an
+	* attachment".
+	*
+	* NOTHING IS EVER DEGRADED: a text that does not parse, parses to a
+	* non-record, or carries neither `mediaType` nor `filename` as a string is
+	* not an attachment, and the part passes through COMPLETELY unchanged
+	* (`remainder` is the raw text, no field is lifted) — this runs on every
+	* `data` part of every read, so a throw here would take down the whole
+	* snapshot.
+	*
+	* THE CONTENT RULE: `remainder` is EMPTY when every key of the record is one
+	* this face projects (`mediaType`, `filename`) — the metadata is fully
+	* represented, and a model sees structure rather than a blob. A record
+	* carrying ANY other key keeps its raw text, so a field we do not project is
+	* never silently dropped (lossless by default). That promise is about KEYS: a
+	* key we DO project whose value is not a string (say `mediaType: 123`) is
+	* counted as represented — the key survives — and reports no field, because
+	* this face lifts strings only. Emptied text therefore means "every key was
+	* one of ours", not "every value produced a field".
+	*/
+	#legacyAttachment(kind, raw, text) {
+		if (kind !== "data" || optionalString(raw["name"]) !== "file") return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (!isRecord(parsed)) return void 0;
+		if (optionalString(parsed["filename"]) === void 0 && optionalString(parsed["mediaType"]) === void 0) return;
+		const everythingLifted = Object.keys(parsed).every((key) => key === "mediaType" || key === "filename");
+		return {
+			record: parsed,
+			remainder: everythingLifted ? "" : text
+		};
+	}
+	/**
 	* The descriptive metadata of an attachment part — and deliberately NOT a
 	* way to reach its bytes.
 	*
-	* Two peer generations are covered, because both are inside the verified
-	* range and they disagree about where the metadata lives:
+	* Two legal faces are covered, because both are inside the verified range and
+	* they disagree about where the metadata lives:
 	*
 	*  - **Cherry ≥ 2.1.5** — `{kind: 'file', name, ref}`, ref at the TOP level.
-	*  - **Cherry 2.1.4** — `{kind: 'data', name, content: {mediaType, filename}}`.
+	*  - **legacy** — `{kind: 'data', name: 'file', content: {text: '<JSON>'}}`,
+	*    the metadata as JSON TEXT. {@link CherryToolEngine.#legacyAttachment}
+	*    parses it and passes the record in here.
+	*
+	* A THIRD arm — a `data` part carrying `{mediaType, filename}` as an OBJECT
+	* inside `content` — is schema-ILLEGAL under the pinned protocol (see the
+	* docblock above) and stays as a DEFENSIVE lift for a peer that violates it.
+	* It is not the 2.1.4 projection: that story was wrong, and a misbehaving
+	* peer's parts are not re-validated client-side, so the guarded arm costs
+	* nothing and covers exactly the peer it was written for.
 	*
 	* Only string fields are lifted: a null `filename` (the peer's explicit "no
 	* name") stays absent rather than becoming the string "null". Anything a
 	* caller needs beyond this — the bytes — stays behind `agent.content.read`,
 	* which this plugin does not call for a file part.
-	*/
-	#attachmentFace(kind, raw, content) {
+	*
+	* WHEN A PARSED `metadata` RECORD IS PRESENT IT IS AUTHORITATIVE. A legacy
+	* attachment's record can arrive externalized as `{ref}`, and that ref is the
+	* peer's serialization ENVELOPE, not the attachment's description: its
+	* `mediaType` is the literal `'text/plain'` the envelope is labelled with and
+	* its `byteLength` is the JSON metadata's own byte count. Letting either
+	* outrank the record would report `text/plain` as an image's media type and a
+	* size that is not the file's — so the record wins the media type, and this
+	* face reports NO `byteLength` at all (a legacy `data` part carries none). The
+	* `file` arm is untouched: there the ref IS the file's own description.
+	*/
+	#attachmentFace(kind, raw, content, metadata) {
 		if (kind !== "file" && kind !== "data") return {};
 		const ref = isRecord(raw["ref"]) ? raw["ref"] : isRecord(content["ref"]) ? content["ref"] : {};
-		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(content["filename"]);
-		const mediaType = optionalString(ref["mediaType"]) ?? optionalString(content["mediaType"]);
-		const byteLength = optionalString(ref["byteLength"]);
+		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(metadata?.["filename"]) ?? optionalString(content["filename"]);
+		const mediaType = kind === "data" && metadata !== void 0 ? optionalString(metadata["mediaType"]) ?? optionalString(content["mediaType"]) : optionalString(ref["mediaType"]) ?? optionalString(metadata?.["mediaType"]) ?? optionalString(content["mediaType"]);
+		const byteLength = kind === "file" ? optionalString(ref["byteLength"]) : void 0;
 		return {
 			...name === void 0 ? {} : { name },
 			...mediaType === void 0 ? {} : { mediaType },
@@ -6395,7 +6672,7 @@ var CherryToolEngine = class {
 		const declaredBytes = Number(ref["byteLength"]);
 		const refusal = this.#externalizedRefusal(ref);
 		if (refusal !== void 0) throw refusal;
-		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / CONTENT_READ_MAX_BYTES)) : DEFAULT_CONTENT_SLICE_BOUND;
+		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / this.#contentReadSliceBytes)) : DEFAULT_CONTENT_SLICE_BOUND;
 		let offset = "0";
 		let sha;
 		let complete = false;
@@ -6408,7 +6685,7 @@ var CherryToolEngine = class {
 				contentId,
 				revision,
 				offset,
-				maxBytes: CONTENT_READ_MAX_BYTES
+				maxBytes: this.#contentReadSliceBytes
 			}, deadline === void 0 ? void 0 : { deadline: deadline.instant });
 			const data = typeof slice["dataBase64"] === "string" ? slice["dataBase64"] : "";
 			const cap = this.#externalizedByteCap;
@@ -6701,11 +6978,29 @@ var CherryToolEngine = class {
 	*/
 	async #admitSend(connection, subscriptions, deviceId, sessionId, request) {
 		const { args, text } = request;
+		const callerId = optionalString(args["commandId"]);
 		const attempt = async (commandId, revisionOverride) => {
-			const expectedIdleRevision = revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
+			const remembered = callerId === void 0 || commandId !== callerId ? void 0 : this.#recallCommandBody(deviceId, callerId);
+			if (remembered !== void 0 && remembered.method !== SEND_METHOD) throw commandBodyDiffers();
+			const rememberedBody = remembered?.body;
+			if (remembered !== void 0 && (rememberedBody?.["sessionId"] !== sessionId || rememberedBody["text"] !== text)) throw commandBodyDiffers();
+			const expectedIdleRevision = optionalString(rememberedBody?.["expectedIdleRevision"]) ?? revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
 			const baselineSeq = this.#newestSeq(subscriptions, sessionId);
+			if (callerId !== void 0) this.#rememberCommandBody(deviceId, callerId, {
+				method: SEND_METHOD,
+				fingerprint: {
+					sessionId,
+					text
+				},
+				body: {
+					commandId,
+					sessionId,
+					text,
+					expectedIdleRevision
+				}
+			});
 			return {
-				receipt: await this.#command(connection, "agent.messages.send", {
+				receipt: await this.#command(connection, SEND_METHOD, {
 					commandId,
 					sessionId,
 					text,
@@ -6956,6 +7251,19 @@ var CherryToolEngine = class {
 						message: "`response` must be {kind:\"answer\", answers:{<question text>: <answer>}}"
 					};
 				}
+				const callerId = optionalString(args["commandId"]);
+				const answer = response === void 0 ? { decision } : { response };
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== RESPOND_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					const fingerprint = {
+						sessionId,
+						interactionId,
+						...answer
+					};
+					if (!sameCommandValue(remembered.fingerprint, fingerprint)) throw commandBodyDiffers();
+					return this.#command(connection, RESPOND_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const snapshot = await this.#interactionSnapshot(connection, subscriptions, record.deviceId, sessionId, interactionId);
@@ -6963,15 +7271,25 @@ var CherryToolEngine = class {
 					error: "unknown-interaction",
 					message: `no interaction ${interactionId} is known for session ${sessionId}`
 				};
-				return this.#command(connection, "agent.interactions.respond", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					interactionId,
 					expectedRevision: snapshot.revision,
 					expectedExecutionId: snapshot.executionId,
 					inputDigest: snapshot.inputDigest,
-					...response === void 0 ? { decision } : { response }
+					...answer
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: RESPOND_METHOD,
+					fingerprint: {
+						sessionId,
+						interactionId,
+						...answer
+					},
+					body
 				});
+				return this.#command(connection, RESPOND_METHOD, body);
 			}
 		});
 	}
@@ -7011,6 +7329,17 @@ var CherryToolEngine = class {
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
+				const callerId = optionalString(args["commandId"]);
+				const supplied = optionalString(args["expectedExecutionId"]);
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== CANCEL_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					if (!sameCommandValue(remembered.fingerprint, {
+						sessionId,
+						expectedExecutionId: supplied
+					})) throw commandBodyDiffers();
+					return this.#command(connection, CANCEL_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const expectedExecutionId = await this.#activeExecutionId(connection, subscriptions, record.deviceId, sessionId);
@@ -7018,18 +7347,26 @@ var CherryToolEngine = class {
 					error: "no-active-execution",
 					message: `session ${sessionId} has no in-flight execution to cancel`
 				};
-				const supplied = optionalString(args["expectedExecutionId"]);
 				if (supplied !== void 0 && supplied !== expectedExecutionId) return {
 					error: "execution-mismatch",
 					expectedExecutionId,
 					supplied,
 					message: `the cached active execution is ${expectedExecutionId}, not ${supplied}; re-read the session before cancelling`
 				};
-				return this.#command(connection, "agent.executions.cancel", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					expectedExecutionId
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: CANCEL_METHOD,
+					fingerprint: {
+						sessionId,
+						expectedExecutionId: supplied
+					},
+					body
 				});
+				return this.#command(connection, CANCEL_METHOD, body);
 			}
 		});
 	}
@@ -7120,7 +7457,7 @@ var CherryToolEngine = class {
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
 				const record = selected[0];
-				this.#forgetDevice(record.deviceId);
+				this.#forgetDevice(record.deviceId, { dropCommandBodies: true });
 				await this.#deps.evict(record.deviceId);
 				try {
 					this.#deps.store.remove(record.deviceId);
@@ -7388,7 +7725,8 @@ var CherryToolEngine = class {
 	*    the stored credential no longer describes a valid pairing. A transient
 	*    network drop ALSO lands here and clears the caches unnecessarily; that
 	*    is accepted, because the cost is one round trip per session on reuse and
-	*    the alternative is keeping snapshots across an identity change.
+	*    the alternative is keeping snapshots across an identity change. (The
+	*    remembered command BODIES are the one exception: see `#forgetDevice`.)
 	*  - `identity-mismatch` — the peer's pinned key changed: the pairing is over.
 	*
 	* {@link CherryToolEngine.#resolve} installs the watch on every tool call that
@@ -7411,7 +7749,7 @@ var CherryToolEngine = class {
 		this.#watchedConnections.add(connection);
 		watch(deviceId, (state) => {
 			if (state !== "offline" && state !== "identity-mismatch") return;
-			this.#forgetDevice(deviceId);
+			this.#forgetDevice(deviceId, { dropCommandBodies: state === "identity-mismatch" });
 		});
 	}
 	/**
@@ -7423,13 +7761,106 @@ var CherryToolEngine = class {
 	* leaves the archive (`cherry_unpair`), so a re-paired device cannot inherit
 	* the previous pairing's snapshots and a long-lived process does not
 	* accumulate entries for devices that no longer exist.
+	*
+	* The remembered command bodies obey a NARROWER seam than the read caches:
+	* `dropCommandBodies` is passed by the callers that invalidate the PAIRING
+	* (unpair, identity-mismatch), never by an ordinary `offline`. What a body
+	* replays against — the peer's command ledger — survives a reconnect, and the
+	* body is the only local copy of the exact bytes that ledger will accept, so
+	* a link drop that emptied it would cost the recovery itself, where the read
+	* caches merely pay one re-walk.
 	*/
-	#forgetDevice(deviceId) {
+	#forgetDevice(deviceId, options = {}) {
 		const prefix = `${deviceId}\u0000`;
 		for (const key of [...this.#revisionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#revisionCache, key);
 		for (const key of [...this.#executionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#executionCache, key);
 		for (const key of [...this.#interactionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#interactionCache, key);
 		for (const key of [...this.#messageCache.keys()]) if (key.startsWith(prefix)) this.#dropCachedMessage(key);
+		if (options.dropCommandBodies === true) {
+			for (const key of [...this.#commandBodies.keys()]) if (key.startsWith(prefix)) this.#forget(this.#commandBodies, key);
+		}
+	}
+	/**
+	* The command remembered for one caller-supplied `commandId`, keyed
+	* `<deviceId>\0<commandId>` — or `undefined` when this device has never
+	* emitted one (a first attempt, or an entry the FIFO evicted).
+	*
+	* The METHOD is the caller's to judge, and it is a THREE-WAY decision, never
+	* a miss:
+	*
+	*  - no entry → a fresh call;
+	*  - an entry under the caller's own method → match the fingerprint, then
+	*    replay or refuse;
+	*  - an entry under a DIFFERENT method → a MISMATCH, refused locally. An id
+	*    minted for `agent.messages.send` is not a respond retry, and collapsing
+	*    that case into "no entry" would send a respond under a send's id and
+	*    let the PEER answer the conflict one round trip later.
+	*/
+	#recallCommandBody(deviceId, commandId) {
+		return this.#commandBodies.get(this.#cacheKey(deviceId, commandId));
+	}
+	/**
+	* TEST SEAM — the remembered bodies, as one `commandId` per device.
+	*
+	* The memory itself is PRIVATE, and stays that way for callers. What a test
+	* needs to assert is its bookkeeping — that the bound evicts the oldest entry
+	* and that {@link CherryToolEngine.#forgetDevice} drops a device's entries —
+	* and neither can be observed through a real retry: a retry of an evicted id
+	* is indistinguishable from a retry of an absent one, because both are refused
+	* locally by the same rule. Keys are rendered WITHOUT the device component so
+	* a test reads ids, not cache internals.
+	*/
+	rememberedCommandIds(deviceId) {
+		const prefix = `${deviceId}${CACHE_KEY_SEPARATOR}`;
+		return [...this.#commandBodies.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+	}
+	/**
+	* TEST SEAM — fill the memory the way a long-lived process would: one entry
+	* per id, WITHOUT spending a wire call on each. The bound and the FIFO order
+	* are the engine's own ({@link CherryToolEngine.#rememberCommandBody}), which
+	* is what makes this a test of the real policy rather than of a mock of it.
+	*/
+	rememberCommandBodyForTest(deviceId, commandId) {
+		this.#rememberCommandBody(deviceId, commandId, {
+			method: "agent.messages.send",
+			fingerprint: {
+				sessionId: "session-for-test",
+				text: "text-for-test"
+			},
+			body: {
+				commandId,
+				sessionId: "session-for-test",
+				text: "text-for-test",
+				expectedIdleRevision: "0"
+			}
+		});
+	}
+	/**
+	* Remembers the exact body one caller-supplied `commandId` was ISSUED with,
+	* evicting this device's oldest entry when it is at the bound.
+	*
+	* FIFO, per device: `Map` insertion order IS the policy, the same deliberate
+	* choice the session caches document, and a `set` on an EXISTING key keeps its
+	* position — a refresh is a rewrite, not a use, so the policy stays
+	* insert-order rather than becoming LRU. One line per eviction, naming the
+	* device and the bound only.
+	*/
+	#rememberCommandBody(deviceId, commandId, remembered) {
+		const key = this.#cacheKey(deviceId, commandId);
+		if (!this.#commandBodies.has(key)) {
+			let own = 0;
+			let oldest;
+			for (const candidate of this.#commandBodies.keys()) {
+				if (!candidate.startsWith(`${deviceId}\u0000`)) continue;
+				own += 1;
+				if (oldest === void 0) oldest = candidate;
+			}
+			if (own >= this.#commandBodyEntriesPerDevice && oldest !== void 0) {
+				this.#commandBodies.delete(oldest);
+				console.warn(`[cherry-remote] remembered command bodies for device ${deviceId} reached their ${this.#commandBodyEntriesPerDevice}-commandId bound; evicted the oldest (a retry of that commandId now re-derives its body, and the peer decides whether it replays)`);
+			}
+		}
+		this.#commandBodies.set(key, remembered);
 	}
 	/**
 	* The session's current idle revision, from the SUBSCRIPTION CACHE.