dsh-cherry-bridge 0.1.10 → 0.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +3 -3
- package/README.md +3 -3
- package/dist/index.mjs +458 -27
- package/docs/e2e-checklist.md +7 -0
- package/package.json +1 -1
- package/src/tools.ts +623 -43
- package/static/settings-devices.jpg +0 -0
- package/static/settings-pairing-scope.jpg +0 -0
package/src/tools.ts
CHANGED
|
@@ -291,9 +291,11 @@ export interface CherryReadPart {
|
|
|
291
291
|
toolName?: string
|
|
292
292
|
toolCallId?: string
|
|
293
293
|
/**
|
|
294
|
-
* The DESCRIPTIVE face of
|
|
295
|
-
*
|
|
296
|
-
*
|
|
294
|
+
* The DESCRIPTIVE face of an attachment — a `kind: 'file'` part, or the
|
|
295
|
+
* legacy `kind: 'data'` part the desktop labels `name: 'file'` and whose
|
|
296
|
+
* metadata is JSON in `content.text`: what the file is, never what it holds.
|
|
297
|
+
* `content` stays empty for such a part unless its record carries a key this
|
|
298
|
+
* face does not project — see {@link CherryToolEngine.#attachmentFace}.
|
|
297
299
|
*/
|
|
298
300
|
name?: string
|
|
299
301
|
mediaType?: string
|
|
@@ -862,6 +864,80 @@ const MESSAGE_CACHE_ENTRY_BYTES = 1_048_576
|
|
|
862
864
|
*/
|
|
863
865
|
const MESSAGE_CACHE_BYTES_PER_DEVICE = 33_554_432
|
|
864
866
|
|
|
867
|
+
/**
|
|
868
|
+
* One command the engine issued under a CALLER-SUPPLIED `commandId`, kept so a
|
|
869
|
+
* retry can replay it by receipt (issues #115, #118).
|
|
870
|
+
*
|
|
871
|
+
* The three fields answer the three questions a retry raises:
|
|
872
|
+
*
|
|
873
|
+
* - `method` — is this id being replayed by the tool that minted it? An id
|
|
874
|
+
* remembered for a send says nothing about a respond retry, and the reverse;
|
|
875
|
+
* - `fingerprint` — did the caller ask for the SAME command? The caller-owned
|
|
876
|
+
* arguments only, compared with {@link sameCommandValue}; the DERIVED body
|
|
877
|
+
* fields are deliberately excluded, because they are exactly what moved;
|
|
878
|
+
* - `body` — what the peer's ledger recorded, reproduced verbatim.
|
|
879
|
+
*/
|
|
880
|
+
interface RememberedCommand {
|
|
881
|
+
method: string
|
|
882
|
+
fingerprint: unknown
|
|
883
|
+
body: Record<string, unknown>
|
|
884
|
+
}
|
|
885
|
+
|
|
886
|
+
/**
|
|
887
|
+
* How many command bodies the engine remembers PER DEVICE, keyed by the
|
|
888
|
+
* CALLER-SUPPLIED `commandId` (issues #115, #118).
|
|
889
|
+
*
|
|
890
|
+
* Why a memory exists at all: a command's recovery path is RECEIPT. A reply
|
|
891
|
+
* lost on the wire is answered by re-sending the ORIGINAL body under the
|
|
892
|
+
* original id, and the desktop's ledger replays the recorded outcome. That
|
|
893
|
+
* promise was impossible for `cherry_send`, whose body carries a DERIVED field
|
|
894
|
+
* (`expectedIdleRevision`) that moves with every successful send: the retry
|
|
895
|
+
* quoted a fresh baseline, the body differed from the recorded one, and the peer
|
|
896
|
+
* answered IDEMPOTENCY_CONFLICT — on the one path where the caller cannot tell
|
|
897
|
+
* what already landed. So the engine remembers the EXACT body it emitted, per
|
|
898
|
+
* (device, caller id, method), and a same-id retry replays it verbatim. The
|
|
899
|
+
* same defect had a harder shape in `cherry_respond` / `cherry_cancel` (issue
|
|
900
|
+
* #118): their DERIVED fields were re-derived, and the retry usually met a
|
|
901
|
+
* pre-check (`unknown-interaction`, `no-active-execution`) before the body was
|
|
902
|
+
* ever compared — the memory is consulted before those, which is why it holds
|
|
903
|
+
* the whole issued body rather than a way to rebuild one.
|
|
904
|
+
*
|
|
905
|
+
* What an entry holds is one short body: a session id, the caller's text (at
|
|
906
|
+
* most the protocol's 32,768 characters, pre-validated before it is ever
|
|
907
|
+
* stored), one revision string — or, for respond/cancel, the interaction's
|
|
908
|
+
* staleness triple / the execution to abort, plus the caller-owned arguments
|
|
909
|
+
* the fingerprint compares. 128 is "more than any live retry window needs,
|
|
910
|
+
* small enough to be trivial": a caller retries a handful of command ids around
|
|
911
|
+
* a lost reply, and each is recoverable while it stays in this FIFO.
|
|
912
|
+
* Eviction costs a REQUEST, never correctness — an evicted id has NO entry, so
|
|
913
|
+
* a same-id retry re-derives a fresh baseline. For a SEND the re-derived body
|
|
914
|
+
* reaches the peer, which refuses the differing body exactly as it would
|
|
915
|
+
* without this memory; for a RESPOND or CANCEL the retry usually dies earlier,
|
|
916
|
+
* at the LOCAL pre-checks (`unknown-interaction`, `no-active-execution`,
|
|
917
|
+
* `execution-mismatch`) — the pre-fix failure mode, which names real state.
|
|
918
|
+
*
|
|
919
|
+
* PER DEVICE, like every engine cache: the id is the caller's, but the peer
|
|
920
|
+
* that settled it is not, and a second desktop must never be sent a body minted
|
|
921
|
+
* against the first.
|
|
922
|
+
*
|
|
923
|
+
* INJECTABLE for tests (`commandBodyEntriesPerDevice`), because the production
|
|
924
|
+
* value needs 129 live command ids before it evicts.
|
|
925
|
+
*/
|
|
926
|
+
const COMMAND_BODY_ENTRIES_PER_DEVICE = 128
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The three command methods whose bodies the engine remembers (see
|
|
930
|
+
* {@link COMMAND_BODY_ENTRIES_PER_DEVICE}).
|
|
931
|
+
*
|
|
932
|
+
* Named once, because they are used twice each by design: as the remembered
|
|
933
|
+
* entry's `method`, and as the method the entry is compared against on lookup.
|
|
934
|
+
* Spelling them at both ends is how a lookup could start matching the wrong
|
|
935
|
+
* tool without any type noticing.
|
|
936
|
+
*/
|
|
937
|
+
const SEND_METHOD = 'agent.messages.send'
|
|
938
|
+
const RESPOND_METHOD = 'agent.interactions.respond'
|
|
939
|
+
const CANCEL_METHOD = 'agent.executions.cancel'
|
|
940
|
+
|
|
865
941
|
/**
|
|
866
942
|
* EMPTY-PAGE RUN limit for every aggregate walk. The desktop's pinned-list walk
|
|
867
943
|
* legally answers ONE empty page with an advancing cursor (the pin→entity
|
|
@@ -1266,6 +1342,89 @@ const IDEMPOTENCY_HINT =
|
|
|
1266
1342
|
'a retry whose parameters changed — never reuse an id with a different body (re-send the ' +
|
|
1267
1343
|
'ORIGINAL body to replay the original receipt).'
|
|
1268
1344
|
|
|
1345
|
+
/**
|
|
1346
|
+
* The peer's own wording for `IDEMPOTENCY_CONFLICT` (its `agentHandlers` throws
|
|
1347
|
+
* exactly this), used when the ENGINE is the one that knows the body differs —
|
|
1348
|
+
* a caller-supplied `commandId` it has already emitted with other arguments
|
|
1349
|
+
* (issue #115).
|
|
1350
|
+
*
|
|
1351
|
+
* The refusal is LOCAL because the outcome is already decided: the peer's ledger
|
|
1352
|
+
* holds the recorded body, so a forwarded body would come back as this same
|
|
1353
|
+
* conflict, one round trip later, at the cost of a wire call that can never
|
|
1354
|
+
* succeed. Reusing the sentence keeps ONE vocabulary for one condition; callers
|
|
1355
|
+
* (and the existing conflict tests) match on the prefix.
|
|
1356
|
+
*/
|
|
1357
|
+
const COMMAND_BODY_DIFFERS_MESSAGE = 'Command body differs from the recorded command'
|
|
1358
|
+
|
|
1359
|
+
/**
|
|
1360
|
+
* The JSON-RPC error code the transport reserves for protocol failures (the
|
|
1361
|
+
* server answers every peer-refused request with it). Used for the LOCAL
|
|
1362
|
+
* {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal so it is the same currency a
|
|
1363
|
+
* forwarded one would have been: a `JsonRpcRequestError` carrying
|
|
1364
|
+
* `{reason: 'IDEMPOTENCY_CONFLICT'}`, distinguishable only by the fact that no
|
|
1365
|
+
* request was ever sent.
|
|
1366
|
+
*
|
|
1367
|
+
* A LOCAL twin of the literal `src/rpc/jsonRpcClient.ts` documents in its own
|
|
1368
|
+
* `JsonRpcRequestError` docblock: that module exports no code constant, and
|
|
1369
|
+
* adding one only to name this number would widen the published surface for it.
|
|
1370
|
+
*/
|
|
1371
|
+
const JSON_RPC_PROTOCOL_ERROR_CODE = 1000
|
|
1372
|
+
|
|
1373
|
+
/**
|
|
1374
|
+
* The LOCAL {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal — the peer's own
|
|
1375
|
+
* reason and sentence, wrapped with the same hints a forwarded conflict earns,
|
|
1376
|
+
* and never sent anywhere.
|
|
1377
|
+
*
|
|
1378
|
+
* ONE constructor for every command that remembers its body (send, respond,
|
|
1379
|
+
* cancel): the caller must not have to learn a second vocabulary for one
|
|
1380
|
+
* condition, and a test matches the prefix `Command body differs` whichever
|
|
1381
|
+
* tool produced it.
|
|
1382
|
+
*/
|
|
1383
|
+
function commandBodyDiffers(): Error {
|
|
1384
|
+
const conflict = new JsonRpcRequestError(JSON_RPC_PROTOCOL_ERROR_CODE, COMMAND_BODY_DIFFERS_MESSAGE, {
|
|
1385
|
+
reason: 'IDEMPOTENCY_CONFLICT',
|
|
1386
|
+
message: COMMAND_BODY_DIFFERS_MESSAGE,
|
|
1387
|
+
})
|
|
1388
|
+
// The two hint helpers pass an error through UNCHANGED (they only append to
|
|
1389
|
+
// a conflict's / a rate-limit's prose), so the identity is the object built
|
|
1390
|
+
// above; the return type keeps the `JsonRpcRequestError` the callers branch
|
|
1391
|
+
// on (the engine's command-failure currency).
|
|
1392
|
+
withRateLimitHint(withIdempotencyHint(conflict))
|
|
1393
|
+
return conflict
|
|
1394
|
+
}
|
|
1395
|
+
|
|
1396
|
+
/**
|
|
1397
|
+
* DEEP structural equality, for the caller-owned half of a remembered command
|
|
1398
|
+
* body (issue #118).
|
|
1399
|
+
*
|
|
1400
|
+
* `cherry_respond`'s `response.answers` is a RECORD: two callers sending the
|
|
1401
|
+
* same answers in a different KEY ORDER are sending the SAME answer, and a
|
|
1402
|
+
* plain `!==` (or a JSON string comparison) would refuse the retry as a
|
|
1403
|
+
* different body — turning the receipt recovery into a local conflict on the
|
|
1404
|
+
* exact shapes it exists for. Arrays stay ORDERED: `questions` is a list, and
|
|
1405
|
+
* reordering it really is a different value.
|
|
1406
|
+
*
|
|
1407
|
+
* Deliberately small: the values compared here are tool arguments decoded from
|
|
1408
|
+
* JSON, so only JSON's two container kinds, the primitives, and `undefined`
|
|
1409
|
+
* (an omitted optional argument) need to be understood.
|
|
1410
|
+
*/
|
|
1411
|
+
function sameCommandValue(left: unknown, right: unknown): boolean {
|
|
1412
|
+
if (left === right) return true
|
|
1413
|
+
if (Array.isArray(left) || Array.isArray(right)) {
|
|
1414
|
+
if (!Array.isArray(left) || !Array.isArray(right)) return false
|
|
1415
|
+
if (left.length !== right.length) return false
|
|
1416
|
+
return left.every((value, index) => sameCommandValue(value, right[index]))
|
|
1417
|
+
}
|
|
1418
|
+
if (isRecord(left) && isRecord(right)) {
|
|
1419
|
+
const leftKeys = Object.keys(left)
|
|
1420
|
+
if (leftKeys.length !== Object.keys(right).length) return false
|
|
1421
|
+
return leftKeys.every(
|
|
1422
|
+
(key) => Object.hasOwn(right, key) && sameCommandValue(left[key], right[key]),
|
|
1423
|
+
)
|
|
1424
|
+
}
|
|
1425
|
+
return false
|
|
1426
|
+
}
|
|
1427
|
+
|
|
1269
1428
|
/**
|
|
1270
1429
|
* Passes a command failure through UNCHANGED, except that `IDEMPOTENCY_CONFLICT`
|
|
1271
1430
|
* gets {@link IDEMPOTENCY_HINT} appended to its message.
|
|
@@ -1478,6 +1637,15 @@ export interface CherryToolEngineOptions {
|
|
|
1478
1637
|
* which no loopback suite should spend its run on.
|
|
1479
1638
|
*/
|
|
1480
1639
|
messageCacheBytesPerDevice?: number
|
|
1640
|
+
/**
|
|
1641
|
+
* Cap on the remembered `cherry_send` bodies for one device — issue #115.
|
|
1642
|
+
* Omitted uses {@link COMMAND_BODY_ENTRIES_PER_DEVICE}.
|
|
1643
|
+
*
|
|
1644
|
+
* Injectable so a test can drive the bound to one and observe the FIFO
|
|
1645
|
+
* arithmetic: at the production 128 a proof needs 129 live command ids, which
|
|
1646
|
+
* no loopback suite should spend its run on.
|
|
1647
|
+
*/
|
|
1648
|
+
commandBodyEntriesPerDevice?: number
|
|
1481
1649
|
/**
|
|
1482
1650
|
* How many `{ref}` contents may be assembled at once across the WHOLE engine
|
|
1483
1651
|
* — every tool call, every device. Omitted uses
|
|
@@ -1488,6 +1656,20 @@ export interface CherryToolEngineOptions {
|
|
|
1488
1656
|
* property under test ("no more than the limit at once") is the same at 1.
|
|
1489
1657
|
*/
|
|
1490
1658
|
contentReadConcurrency?: number
|
|
1659
|
+
/**
|
|
1660
|
+
* The `maxBytes` every `agent.content.read` slice asks for. Omitted uses
|
|
1661
|
+
* {@link CONTENT_READ_MAX_BYTES}, the protocol's `contentBytes`.
|
|
1662
|
+
*
|
|
1663
|
+
* TEST-ONLY, and it exists because the loopback fan-out caps a record at
|
|
1664
|
+
* 32 KiB: at the production 24 KiB no honest ref fits in TWO slices (one
|
|
1665
|
+
* full slice plus the `< 24 KiB` remainder), so a walk's SECOND slice — the
|
|
1666
|
+
* one that proves the ref's digest describes the whole of what is served,
|
|
1667
|
+
* rather than merely its first slice — is unreachable through the fake. A
|
|
1668
|
+
* smaller slice size makes any multi-slice behaviour testable. Never lowered
|
|
1669
|
+
* in production: the peer caps the slice anyway, and asking for less only
|
|
1670
|
+
* costs round trips.
|
|
1671
|
+
*/
|
|
1672
|
+
contentReadSliceBytes?: number
|
|
1491
1673
|
}
|
|
1492
1674
|
|
|
1493
1675
|
/**
|
|
@@ -1536,18 +1718,42 @@ export function registerCherryTools(
|
|
|
1536
1718
|
deps: CherryToolsDeps,
|
|
1537
1719
|
options: CherryToolEngineOptions = {},
|
|
1538
1720
|
): () => void {
|
|
1721
|
+
return registerCherryToolsWithEngine(ctx, deps, options).dispose
|
|
1722
|
+
}
|
|
1723
|
+
|
|
1724
|
+
/**
|
|
1725
|
+
* The same registration, with the ENGINE it built handed back.
|
|
1726
|
+
*
|
|
1727
|
+
* Exists for TESTS: the engine's memory bookkeeping (the remembered command
|
|
1728
|
+
* bodies, the bounds they obey) is private to it on purpose, and the only
|
|
1729
|
+
* honest way to pin "bounded" and "dropped with the device" is to observe it
|
|
1730
|
+
* through this one seam instead of inferring it from retry outcomes that are
|
|
1731
|
+
* identical for an evicted entry and for one that never existed.
|
|
1732
|
+
*
|
|
1733
|
+
* Both this function and `export class CherryToolEngine` are SHIPPED names
|
|
1734
|
+
* (`src` is published on purpose, see AGENTS.md → Build facts), so they are a
|
|
1735
|
+
* compatibility commitment — which is why this seam is kept minimal.
|
|
1736
|
+
*/
|
|
1737
|
+
export function registerCherryToolsWithEngine(
|
|
1738
|
+
ctx: CherryToolsContext,
|
|
1739
|
+
deps: CherryToolsDeps,
|
|
1740
|
+
options: CherryToolEngineOptions = {},
|
|
1741
|
+
): { dispose: () => void; engine: CherryToolEngine | undefined } {
|
|
1539
1742
|
const tools = ctx.tools
|
|
1540
1743
|
if (tools === undefined) {
|
|
1541
1744
|
// Headless deployments have no tool registry. Degrade to a warning rather
|
|
1542
1745
|
// than throwing: the assembly's HTTP/UI half must still come up.
|
|
1543
1746
|
console.warn('[cherry-remote] ctx.tools is unavailable; the cherry_* tools were not registered')
|
|
1544
|
-
return () => {}
|
|
1747
|
+
return { dispose: () => {}, engine: undefined }
|
|
1545
1748
|
}
|
|
1546
1749
|
|
|
1547
1750
|
const engine = new CherryToolEngine(deps, options)
|
|
1548
1751
|
const disposers = engine.definitions().map((definition) => tools.register(definition))
|
|
1549
|
-
return
|
|
1550
|
-
|
|
1752
|
+
return {
|
|
1753
|
+
engine,
|
|
1754
|
+
dispose: () => {
|
|
1755
|
+
for (const dispose of disposers) dispose()
|
|
1756
|
+
},
|
|
1551
1757
|
}
|
|
1552
1758
|
}
|
|
1553
1759
|
|
|
@@ -1574,7 +1780,7 @@ function defineCherryTool(definition: {
|
|
|
1574
1780
|
* share. Kept as one class (rather than per-face closures) so the per-session
|
|
1575
1781
|
* and per-device state the later faces add has an obvious home.
|
|
1576
1782
|
*/
|
|
1577
|
-
class CherryToolEngine {
|
|
1783
|
+
export class CherryToolEngine {
|
|
1578
1784
|
readonly #deps: CherryToolsDeps
|
|
1579
1785
|
/**
|
|
1580
1786
|
* Circuit-breaker for the parts walk. A LOCAL policy value, injectable so a
|
|
@@ -1649,6 +1855,12 @@ class CherryToolEngine {
|
|
|
1649
1855
|
* being read, shared by every tool call and every device this engine serves.
|
|
1650
1856
|
*/
|
|
1651
1857
|
readonly #contentGate: ContentReadGate
|
|
1858
|
+
/**
|
|
1859
|
+
* The `maxBytes` one `agent.content.read` slice asks for
|
|
1860
|
+
* ({@link CONTENT_READ_MAX_BYTES} in production; injectable so a test can
|
|
1861
|
+
* reach a walk's second slice, see `CherryToolEngineOptions`).
|
|
1862
|
+
*/
|
|
1863
|
+
readonly #contentReadSliceBytes: number
|
|
1652
1864
|
/**
|
|
1653
1865
|
* The parts pages already walked, keyed `<deviceId>\0<messageId>`.
|
|
1654
1866
|
*
|
|
@@ -1719,7 +1931,49 @@ class CherryToolEngine {
|
|
|
1719
1931
|
* not pinned by bookkeeping.
|
|
1720
1932
|
*/
|
|
1721
1933
|
readonly #watchedConnections = new WeakSet<DeviceConnection>()
|
|
1722
|
-
|
|
1934
|
+
/**
|
|
1935
|
+
* The EXACT command body emitted for each (device, caller id, method), so a
|
|
1936
|
+
* lost reply can be recovered by receipt (issues #115, #118).
|
|
1937
|
+
*
|
|
1938
|
+
* Keyed `<deviceId>\0<commandId>`, exactly like every other engine cache. The
|
|
1939
|
+
* value is a {@link RememberedCommand}: the METHOD it was minted for, the
|
|
1940
|
+
* caller-owned FINGERPRINT a retry must match, and the BODY the retry
|
|
1941
|
+
* replays verbatim. The fingerprint is what must MATCH — a same-id call whose
|
|
1942
|
+
* arguments differ is not a retry of this command at all, and is refused
|
|
1943
|
+
* locally rather than sent. The body is what must be REPLAYED, derived
|
|
1944
|
+
* fields included: that is the whole point, because those fields are the ones
|
|
1945
|
+
* a retry cannot re-derive the same way.
|
|
1946
|
+
*
|
|
1947
|
+
* Three tools remember: `agent.messages.send` (the baseline it quoted),
|
|
1948
|
+
* `agent.interactions.respond` (the staleness triple) and
|
|
1949
|
+
* `agent.executions.cancel` (the execution it was told to abort). Two of
|
|
1950
|
+
* them run PRE-CHECKS before composing a body — respond's
|
|
1951
|
+
* `unknown-interaction`, cancel's `no-active-execution`/`execution-mismatch` —
|
|
1952
|
+
* and after a lost reply those pre-checks are usually the first thing the
|
|
1953
|
+
* retry meets, because the first attempt is what SETTLED the interaction and
|
|
1954
|
+
* ENDED the run. So a caller-supplied id is consulted BEFORE any derivation:
|
|
1955
|
+
* a remembered retry is an answer, not a fresh call.
|
|
1956
|
+
*
|
|
1957
|
+
* WHAT IS REMEMBERED: only CALLER-SUPPLIED ids. An auto-generated uuid is a
|
|
1958
|
+
* one-shot identity — nobody can retry it, so an entry for it is pure leak.
|
|
1959
|
+
* The entry is written the moment the command is ISSUED, before the reply is
|
|
1960
|
+
* awaited: a reply lost on the wire must not cost the only copy of the bytes
|
|
1961
|
+
* the peer's ledger will accept.
|
|
1962
|
+
*
|
|
1963
|
+
* Which body an id holds: the LATEST attempt issued for it — the first
|
|
1964
|
+
* attempt, or the self-heal's fresh-uuid retry when one ran. After a heal, a
|
|
1965
|
+
* same-id retry is therefore answered with the peer's conflict, deliberately:
|
|
1966
|
+
* replaying the ledger's rejected receipt would re-run the healed admission
|
|
1967
|
+
* and duplicate the run, and a conflict is the safer failure.
|
|
1968
|
+
*
|
|
1969
|
+
* Bounded FIFO, per device; dropped when the PAIRING is invalidated (unpair,
|
|
1970
|
+
* identity-mismatch) but KEPT across an ordinary reconnect — see
|
|
1971
|
+
* {@link COMMAND_BODY_ENTRIES_PER_DEVICE} and
|
|
1972
|
+
* {@link CherryToolEngine.#forgetDevice}.
|
|
1973
|
+
*/
|
|
1974
|
+
readonly #commandBodies = new Map<string, RememberedCommand>()
|
|
1975
|
+
/** The per-device cap on {@link CherryToolEngine.#commandBodies}. */
|
|
1976
|
+
readonly #commandBodyEntriesPerDevice: number
|
|
1723
1977
|
constructor(deps: CherryToolsDeps, options: CherryToolEngineOptions = {}) {
|
|
1724
1978
|
this.#deps = deps
|
|
1725
1979
|
this.#partsSafetyBound = Math.max(
|
|
@@ -1743,7 +1997,15 @@ class CherryToolEngine {
|
|
|
1743
1997
|
1,
|
|
1744
1998
|
Math.floor(options.messageCacheBytesPerDevice ?? MESSAGE_CACHE_BYTES_PER_DEVICE),
|
|
1745
1999
|
)
|
|
2000
|
+
this.#commandBodyEntriesPerDevice = Math.max(
|
|
2001
|
+
1,
|
|
2002
|
+
Math.floor(options.commandBodyEntriesPerDevice ?? COMMAND_BODY_ENTRIES_PER_DEVICE),
|
|
2003
|
+
)
|
|
1746
2004
|
this.#contentGate = new ContentReadGate(options.contentReadConcurrency ?? DEFAULT_CONTENT_READ_CONCURRENCY)
|
|
2005
|
+
this.#contentReadSliceBytes = Math.max(
|
|
2006
|
+
1,
|
|
2007
|
+
Math.floor(options.contentReadSliceBytes ?? CONTENT_READ_MAX_BYTES),
|
|
2008
|
+
)
|
|
1747
2009
|
}
|
|
1748
2010
|
|
|
1749
2011
|
definitions(): CherryToolDefinition[] {
|
|
@@ -2596,8 +2858,11 @@ class CherryToolEngine {
|
|
|
2596
2858
|
'sha256-verified through `agent.content.read`. An unchanged message (same message ' +
|
|
2597
2859
|
'revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a ' +
|
|
2598
2860
|
'quiet session costs no `agent.parts.list` RPC; externalized content is still fetched ' +
|
|
2599
|
-
'and sha256-verified on every read, so unverified bytes are never served from memory.
|
|
2600
|
-
'
|
|
2861
|
+
'and sha256-verified on every read, so unverified bytes are never served from memory. An ' +
|
|
2862
|
+
'attachment is reported as METADATA, never as its bytes: a `kind: "file"` part, or a ' +
|
|
2863
|
+
'legacy `data` part named `file` (the metadata as JSON in `content.text`), comes back as ' +
|
|
2864
|
+
'`name`/`mediaType` (plus `byteLength` for the `file` kind) with `content` emptied — or ' +
|
|
2865
|
+
'kept verbatim when that record carries a key this projection does not report. The bytes ' +
|
|
2601
2866
|
'are deliberately not fetched into a text channel. Messages come NEWEST-first, so the ' +
|
|
2602
2867
|
'first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts ' +
|
|
2603
2868
|
'inside a retained message\'s parts; a message whose own parts could not be fully read ' +
|
|
@@ -3053,52 +3318,152 @@ class CherryToolEngine {
|
|
|
3053
3318
|
text = ''
|
|
3054
3319
|
}
|
|
3055
3320
|
|
|
3321
|
+
// A LEGACY ATTACHMENT is a `data` part whose metadata is JSON TEXT, not an
|
|
3322
|
+
// object (see {@link CherryToolEngine.#attachmentFace}). The face is lifted
|
|
3323
|
+
// here, from the ALREADY-RESOLVED text — the same text a `{ref}` payload
|
|
3324
|
+
// resolves to — so an externalized metadata record lifts identically.
|
|
3325
|
+
const legacy = this.#legacyAttachment(kind, raw, text)
|
|
3056
3326
|
return {
|
|
3057
3327
|
partId,
|
|
3058
3328
|
kind,
|
|
3059
3329
|
revision,
|
|
3060
|
-
|
|
3061
|
-
//
|
|
3062
|
-
//
|
|
3063
|
-
|
|
3064
|
-
|
|
3065
|
-
|
|
3330
|
+
// THE CONTENT RULE: the JSON text is emptied only when EVERY key of the
|
|
3331
|
+
// record is one the face projects; a record carrying keys we do not
|
|
3332
|
+
// project keeps its raw text, so nothing is silently dropped.
|
|
3333
|
+
content: legacy === undefined ? text : legacy.remainder,
|
|
3334
|
+
...(legacy === undefined
|
|
3335
|
+
? this.#attachmentFace(kind, raw, content)
|
|
3336
|
+
: this.#attachmentFace(kind, raw, content, legacy.record)),
|
|
3066
3337
|
...(typeof raw['state'] === 'string' ? { state: raw['state'] } : {}),
|
|
3067
3338
|
...(typeof raw['toolName'] === 'string' ? { toolName: raw['toolName'] } : {}),
|
|
3068
3339
|
...(typeof raw['toolCallId'] === 'string' ? { toolCallId: raw['toolCallId'] } : {}),
|
|
3069
3340
|
}
|
|
3070
3341
|
}
|
|
3071
3342
|
|
|
3343
|
+
/**
|
|
3344
|
+
* The ONE place a legacy `data` part is recognised as an attachment: the
|
|
3345
|
+
* structural discriminator, the JSON parse, and the lossless CONTENT rule.
|
|
3346
|
+
*
|
|
3347
|
+
* The legal legacy face is `{kind: 'data', name: 'file', content: {text:
|
|
3348
|
+
* '{\"mediaType\":…,\"filename\":…}'}}` — the metadata SERIALIZED AS JSON in
|
|
3349
|
+
* `content.text`, observed on the wire (2.1.7 desktop, image upload,
|
|
3350
|
+
* 2026-10-22). An OBJECT inside `content` is not producible by a conforming
|
|
3351
|
+
* peer at all: the pinned protocol 0.5.0 types `content` as a strict
|
|
3352
|
+
* `{text}` | `{ref}` union, so the old documentation described a shape no
|
|
3353
|
+
* peer can emit — and the real one was never lifted, which is how an image
|
|
3354
|
+
* upload reached a model as a JSON blob.
|
|
3355
|
+
*
|
|
3356
|
+
* WHY THE NAME IS THE DISCRIMINATOR, and why it is not a heuristic: the
|
|
3357
|
+
* desktop labels every `data` part with its data KIND in `name` — an
|
|
3358
|
+
* attachment is `'file'`, a task event is `'data-compaction-anchor'`, an
|
|
3359
|
+
* error is `'data-error'` — and the protocol types that field as an
|
|
3360
|
+
* `opaqueId`. This lift therefore REQUIRES the label to be the literal
|
|
3361
|
+
* `'file'` rather than ASSUMING every peer sets one: a `data` part that
|
|
3362
|
+
* carries no name reads as no name, is not lifted, and passes through
|
|
3363
|
+
* untouched. Several of those payloads are JSON too, so "the text parses"
|
|
3364
|
+
* proves nothing; `'file'` is the one label that means "this is an
|
|
3365
|
+
* attachment".
|
|
3366
|
+
*
|
|
3367
|
+
* NOTHING IS EVER DEGRADED: a text that does not parse, parses to a
|
|
3368
|
+
* non-record, or carries neither `mediaType` nor `filename` as a string is
|
|
3369
|
+
* not an attachment, and the part passes through COMPLETELY unchanged
|
|
3370
|
+
* (`remainder` is the raw text, no field is lifted) — this runs on every
|
|
3371
|
+
* `data` part of every read, so a throw here would take down the whole
|
|
3372
|
+
* snapshot.
|
|
3373
|
+
*
|
|
3374
|
+
* THE CONTENT RULE: `remainder` is EMPTY when every key of the record is one
|
|
3375
|
+
* this face projects (`mediaType`, `filename`) — the metadata is fully
|
|
3376
|
+
* represented, and a model sees structure rather than a blob. A record
|
|
3377
|
+
* carrying ANY other key keeps its raw text, so a field we do not project is
|
|
3378
|
+
* never silently dropped (lossless by default). That promise is about KEYS: a
|
|
3379
|
+
* key we DO project whose value is not a string (say `mediaType: 123`) is
|
|
3380
|
+
* counted as represented — the key survives — and reports no field, because
|
|
3381
|
+
* this face lifts strings only. Emptied text therefore means "every key was
|
|
3382
|
+
* one of ours", not "every value produced a field".
|
|
3383
|
+
*/
|
|
3384
|
+
#legacyAttachment(
|
|
3385
|
+
kind: string,
|
|
3386
|
+
raw: Record<string, unknown>,
|
|
3387
|
+
text: string,
|
|
3388
|
+
): { record: Record<string, unknown>; remainder: string } | undefined {
|
|
3389
|
+
if (kind !== 'data' || optionalString(raw['name']) !== 'file') return undefined
|
|
3390
|
+
let parsed: unknown
|
|
3391
|
+
try {
|
|
3392
|
+
parsed = JSON.parse(text) as unknown
|
|
3393
|
+
} catch {
|
|
3394
|
+
return undefined
|
|
3395
|
+
}
|
|
3396
|
+
if (!isRecord(parsed)) return undefined
|
|
3397
|
+
// At least ONE projected key must be a string: a record naming neither
|
|
3398
|
+
// `mediaType` nor `filename` says nothing about an attachment, whatever
|
|
3399
|
+
// its name label claims.
|
|
3400
|
+
if (optionalString(parsed['filename']) === undefined && optionalString(parsed['mediaType']) === undefined) {
|
|
3401
|
+
return undefined
|
|
3402
|
+
}
|
|
3403
|
+
const everythingLifted = Object.keys(parsed).every((key) => key === 'mediaType' || key === 'filename')
|
|
3404
|
+
return { record: parsed, remainder: everythingLifted ? '' : text }
|
|
3405
|
+
}
|
|
3406
|
+
|
|
3072
3407
|
/**
|
|
3073
3408
|
* The descriptive metadata of an attachment part — and deliberately NOT a
|
|
3074
3409
|
* way to reach its bytes.
|
|
3075
3410
|
*
|
|
3076
|
-
* Two
|
|
3077
|
-
*
|
|
3411
|
+
* Two legal faces are covered, because both are inside the verified range and
|
|
3412
|
+
* they disagree about where the metadata lives:
|
|
3078
3413
|
*
|
|
3079
3414
|
* - **Cherry ≥ 2.1.5** — `{kind: 'file', name, ref}`, ref at the TOP level.
|
|
3080
|
-
* - **
|
|
3415
|
+
* - **legacy** — `{kind: 'data', name: 'file', content: {text: '<JSON>'}}`,
|
|
3416
|
+
* the metadata as JSON TEXT. {@link CherryToolEngine.#legacyAttachment}
|
|
3417
|
+
* parses it and passes the record in here.
|
|
3418
|
+
*
|
|
3419
|
+
* A THIRD arm — a `data` part carrying `{mediaType, filename}` as an OBJECT
|
|
3420
|
+
* inside `content` — is schema-ILLEGAL under the pinned protocol (see the
|
|
3421
|
+
* docblock above) and stays as a DEFENSIVE lift for a peer that violates it.
|
|
3422
|
+
* It is not the 2.1.4 projection: that story was wrong, and a misbehaving
|
|
3423
|
+
* peer's parts are not re-validated client-side, so the guarded arm costs
|
|
3424
|
+
* nothing and covers exactly the peer it was written for.
|
|
3081
3425
|
*
|
|
3082
3426
|
* Only string fields are lifted: a null `filename` (the peer's explicit "no
|
|
3083
3427
|
* name") stays absent rather than becoming the string "null". Anything a
|
|
3084
3428
|
* caller needs beyond this — the bytes — stays behind `agent.content.read`,
|
|
3085
3429
|
* which this plugin does not call for a file part.
|
|
3430
|
+
*
|
|
3431
|
+
* WHEN A PARSED `metadata` RECORD IS PRESENT IT IS AUTHORITATIVE. A legacy
|
|
3432
|
+
* attachment's record can arrive externalized as `{ref}`, and that ref is the
|
|
3433
|
+
* peer's serialization ENVELOPE, not the attachment's description: its
|
|
3434
|
+
* `mediaType` is the literal `'text/plain'` the envelope is labelled with and
|
|
3435
|
+
* its `byteLength` is the JSON metadata's own byte count. Letting either
|
|
3436
|
+
* outrank the record would report `text/plain` as an image's media type and a
|
|
3437
|
+
* size that is not the file's — so the record wins the media type, and this
|
|
3438
|
+
* face reports NO `byteLength` at all (a legacy `data` part carries none). The
|
|
3439
|
+
* `file` arm is untouched: there the ref IS the file's own description.
|
|
3086
3440
|
*/
|
|
3087
3441
|
#attachmentFace(
|
|
3088
3442
|
kind: string,
|
|
3089
3443
|
raw: Record<string, unknown>,
|
|
3090
3444
|
content: Record<string, unknown>,
|
|
3445
|
+
metadata?: Record<string, unknown>,
|
|
3091
3446
|
): { name?: string; mediaType?: string; byteLength?: string } {
|
|
3092
3447
|
if (kind !== 'file' && kind !== 'data') return {}
|
|
3093
3448
|
const ref = isRecord(raw['ref']) ? raw['ref'] : isRecord(content['ref']) ? content['ref'] : {}
|
|
3094
3449
|
// WHERE the name lives is part of the shape, not a matter of preference: on
|
|
3095
3450
|
// a `file` part `name` IS the filename, while a `data` part's `name` is the
|
|
3096
|
-
// data KIND label
|
|
3097
|
-
//
|
|
3098
|
-
// the data kind would report "file" as the attachment's name.
|
|
3099
|
-
const name =
|
|
3100
|
-
|
|
3101
|
-
|
|
3451
|
+
// data KIND label (the attachment's is the literal `'file'`), so a legacy
|
|
3452
|
+
// filename can only come from the metadata record's `filename`. Reading
|
|
3453
|
+
// `name` for the data kind would report "file" as the attachment's name.
|
|
3454
|
+
const name =
|
|
3455
|
+
kind === 'file'
|
|
3456
|
+
? optionalString(raw['name'])
|
|
3457
|
+
: (optionalString(metadata?.['filename']) ?? optionalString(content['filename']))
|
|
3458
|
+
const mediaType =
|
|
3459
|
+
kind === 'data' && metadata !== undefined
|
|
3460
|
+
? (optionalString(metadata['mediaType']) ?? optionalString(content['mediaType']))
|
|
3461
|
+
: (optionalString(ref['mediaType']) ??
|
|
3462
|
+
optionalString(metadata?.['mediaType']) ??
|
|
3463
|
+
optionalString(content['mediaType']))
|
|
3464
|
+
// A legacy `data` part carries no `byteLength`: the only ref it can have is
|
|
3465
|
+
// the metadata envelope's, whose length describes the RECORD.
|
|
3466
|
+
const byteLength = kind === 'file' ? optionalString(ref['byteLength']) : undefined
|
|
3102
3467
|
return {
|
|
3103
3468
|
...(name === undefined ? {} : { name }),
|
|
3104
3469
|
...(mediaType === undefined ? {} : { mediaType }),
|
|
@@ -3209,7 +3574,7 @@ class CherryToolEngine {
|
|
|
3209
3574
|
const refusal = this.#externalizedRefusal(ref)
|
|
3210
3575
|
if (refusal !== undefined) throw refusal
|
|
3211
3576
|
const maxSlices = Number.isSafeInteger(declaredBytes)
|
|
3212
|
-
? Math.max(1, Math.ceil(declaredBytes /
|
|
3577
|
+
? Math.max(1, Math.ceil(declaredBytes / this.#contentReadSliceBytes))
|
|
3213
3578
|
: DEFAULT_CONTENT_SLICE_BOUND
|
|
3214
3579
|
|
|
3215
3580
|
let offset = '0'
|
|
@@ -3238,7 +3603,9 @@ class CherryToolEngine {
|
|
|
3238
3603
|
contentId,
|
|
3239
3604
|
revision,
|
|
3240
3605
|
offset,
|
|
3241
|
-
|
|
3606
|
+
// The protocol's slice size in production; injectable for tests that
|
|
3607
|
+
// must reach a walk's SECOND slice (see the option's docblock).
|
|
3608
|
+
maxBytes: this.#contentReadSliceBytes,
|
|
3242
3609
|
},
|
|
3243
3610
|
deadline === undefined ? undefined : { deadline: deadline.instant },
|
|
3244
3611
|
)) as Record<string, unknown>
|
|
@@ -3774,12 +4141,37 @@ class CherryToolEngine {
|
|
|
3774
4141
|
request: { args: Record<string, unknown>; text: string },
|
|
3775
4142
|
): Promise<{ receipt: Record<string, unknown>; baselineSeq: number }> {
|
|
3776
4143
|
const { args, text } = request
|
|
4144
|
+
const callerId = optionalString(args['commandId'])
|
|
3777
4145
|
const attempt = async (
|
|
3778
4146
|
commandId: string,
|
|
3779
4147
|
revisionOverride?: string,
|
|
3780
4148
|
): Promise<{ receipt: Record<string, unknown>; baselineSeq: number }> => {
|
|
4149
|
+
// The memory belongs to the id it was MINTED for, so the lookup is gated
|
|
4150
|
+
// on `commandId === callerId`: the self-heal's fresh-uuid attempt derives
|
|
4151
|
+
// its own baseline instead of inheriting the caller's.
|
|
4152
|
+
const remembered =
|
|
4153
|
+
callerId === undefined || commandId !== callerId
|
|
4154
|
+
? undefined
|
|
4155
|
+
: this.#recallCommandBody(deviceId, callerId)
|
|
4156
|
+
// A remembered id that belongs to ANOTHER method is a mismatch, not a
|
|
4157
|
+
// miss: refusing locally keeps the decision off the wire.
|
|
4158
|
+
if (remembered !== undefined && remembered.method !== SEND_METHOD) throw commandBodyDiffers()
|
|
4159
|
+
// A same-id call whose caller-owned arguments differ from the remembered
|
|
4160
|
+
// body is not a retry of that command: the peer holds the original body,
|
|
4161
|
+
// so the conflict is already decided and is answered LOCALLY, in the
|
|
4162
|
+
// peer's own words, with no wire call.
|
|
4163
|
+
const rememberedBody = remembered?.body
|
|
4164
|
+
const mismatched =
|
|
4165
|
+
remembered !== undefined &&
|
|
4166
|
+
(rememberedBody?.['sessionId'] !== sessionId || rememberedBody['text'] !== text)
|
|
4167
|
+
if (mismatched) throw commandBodyDiffers()
|
|
4168
|
+
// THE REMEMBERED BODY IS REPLAYED, derived field included. Rebuilding it
|
|
4169
|
+
// from a derived `expectedIdleRevision` instead is what #115's memory
|
|
4170
|
+
// exists to stop, so the value is read back rather than recomputed.
|
|
3781
4171
|
const expectedIdleRevision =
|
|
3782
|
-
|
|
4172
|
+
optionalString(rememberedBody?.['expectedIdleRevision']) ??
|
|
4173
|
+
revisionOverride ??
|
|
4174
|
+
(await this.#idleRevision(connection, subscriptions, deviceId, sessionId))
|
|
3783
4175
|
// THE BASELINE IS TAKEN BEFORE THE COMMAND IS ISSUED, and that ordering
|
|
3784
4176
|
// is what makes a fast run observable at all. The waiter's baseline is
|
|
3785
4177
|
// the cut that decides which events belong to THIS run; taking it after
|
|
@@ -3791,7 +4183,16 @@ class CherryToolEngine {
|
|
|
3791
4183
|
// Nothing before this point can emit this run's events: the command has
|
|
3792
4184
|
// not been sent yet.
|
|
3793
4185
|
const baselineSeq = this.#newestSeq(subscriptions, sessionId)
|
|
3794
|
-
|
|
4186
|
+
// The body is remembered the moment it is ISSUED — a reply lost on the wire
|
|
4187
|
+
// must not cost the only copy of the bytes the peer's ledger will accept.
|
|
4188
|
+
if (callerId !== undefined) {
|
|
4189
|
+
this.#rememberCommandBody(deviceId, callerId, {
|
|
4190
|
+
method: SEND_METHOD,
|
|
4191
|
+
fingerprint: { sessionId, text },
|
|
4192
|
+
body: { commandId, sessionId, text, expectedIdleRevision },
|
|
4193
|
+
})
|
|
4194
|
+
}
|
|
4195
|
+
const receipt = await this.#command(connection, SEND_METHOD, {
|
|
3795
4196
|
commandId,
|
|
3796
4197
|
sessionId,
|
|
3797
4198
|
text,
|
|
@@ -4187,6 +4588,26 @@ class CherryToolEngine {
|
|
|
4187
4588
|
}
|
|
4188
4589
|
}
|
|
4189
4590
|
|
|
4591
|
+
const callerId = optionalString(args['commandId'])
|
|
4592
|
+
const answer: Record<string, unknown> = response === undefined ? { decision } : { response }
|
|
4593
|
+
// A RETRY IS ANSWERED BEFORE ANYTHING IS DERIVED. The staleness triple
|
|
4594
|
+
// below is derived from what the plugin has observed, and after a lost
|
|
4595
|
+
// reply that observation has MOVED (the first answer settled the card)
|
|
4596
|
+
// or vanished (the peer no longer serves it). Re-deriving would either
|
|
4597
|
+
// quote a body the ledger never recorded or — the usual case — stop at
|
|
4598
|
+
// the `unknown-interaction` verdict below, before the body is ever
|
|
4599
|
+
// compared. So a caller-supplied id is consulted FIRST: same id, same
|
|
4600
|
+
// caller-owned arguments and same method replays the remembered body
|
|
4601
|
+
// verbatim, and the snapshot is not asked at all.
|
|
4602
|
+
const remembered =
|
|
4603
|
+
callerId === undefined ? undefined : this.#recallCommandBody(record.deviceId, callerId)
|
|
4604
|
+
if (remembered !== undefined && remembered.method !== RESPOND_METHOD) throw commandBodyDiffers()
|
|
4605
|
+
if (remembered !== undefined) {
|
|
4606
|
+
const fingerprint = { sessionId, interactionId, ...answer }
|
|
4607
|
+
if (!sameCommandValue(remembered.fingerprint, fingerprint)) throw commandBodyDiffers()
|
|
4608
|
+
return this.#command(connection, RESPOND_METHOD, remembered.body)
|
|
4609
|
+
}
|
|
4610
|
+
|
|
4190
4611
|
await this.#ensureSubscription(record.deviceId, sessionId)
|
|
4191
4612
|
const subscriptions = this.#deps.subs(record.deviceId)
|
|
4192
4613
|
|
|
@@ -4209,15 +4630,27 @@ class CherryToolEngine {
|
|
|
4209
4630
|
} satisfies Record<string, unknown>
|
|
4210
4631
|
}
|
|
4211
4632
|
|
|
4212
|
-
|
|
4213
|
-
|
|
4633
|
+
const commandId = this.#commandId(args)
|
|
4634
|
+
const body = {
|
|
4635
|
+
commandId,
|
|
4214
4636
|
sessionId,
|
|
4215
4637
|
interactionId,
|
|
4216
4638
|
expectedRevision: snapshot.revision,
|
|
4217
4639
|
expectedExecutionId: snapshot.executionId,
|
|
4218
4640
|
inputDigest: snapshot.inputDigest,
|
|
4219
|
-
...
|
|
4220
|
-
}
|
|
4641
|
+
...answer,
|
|
4642
|
+
}
|
|
4643
|
+
// ISSUE-TIME WRITE: the body is fully composed here, so it is remembered
|
|
4644
|
+
// before the reply is awaited — a reply lost on the wire must not cost
|
|
4645
|
+
// the only copy of the bytes the peer's ledger will accept.
|
|
4646
|
+
if (callerId !== undefined) {
|
|
4647
|
+
this.#rememberCommandBody(record.deviceId, callerId, {
|
|
4648
|
+
method: RESPOND_METHOD,
|
|
4649
|
+
fingerprint: { sessionId, interactionId, ...answer },
|
|
4650
|
+
body,
|
|
4651
|
+
})
|
|
4652
|
+
}
|
|
4653
|
+
return this.#command(connection, RESPOND_METHOD, body)
|
|
4221
4654
|
},
|
|
4222
4655
|
})
|
|
4223
4656
|
}
|
|
@@ -4259,6 +4692,27 @@ class CherryToolEngine {
|
|
|
4259
4692
|
if (resolved.link === undefined) return resolved.verdict
|
|
4260
4693
|
const { connection, record } = resolved.link
|
|
4261
4694
|
const sessionId = requiredString(args, 'sessionId')
|
|
4695
|
+
const callerId = optionalString(args['commandId'])
|
|
4696
|
+
// The caller's own value is a PRE-CHECK, not a body field — but it is
|
|
4697
|
+
// part of what the caller ASKED FOR, so it belongs in the fingerprint: a
|
|
4698
|
+
// retry asserting a different execution is not a retry of this cancel.
|
|
4699
|
+
const supplied = optionalString(args['expectedExecutionId'])
|
|
4700
|
+
|
|
4701
|
+
// A RETRY IS ANSWERED BEFORE THE PRE-CHECKS — the same ordering (and
|
|
4702
|
+
// the same reason) as `agent.interactions.respond`'s consult above;
|
|
4703
|
+
// what differs here is only which verdicts would otherwise eat the
|
|
4704
|
+
// retry: `no-active-execution` and `execution-mismatch` describe the
|
|
4705
|
+
// state RIGHT NOW, and a lost reply left the run the first attempt
|
|
4706
|
+
// cancelled already finished.
|
|
4707
|
+
const remembered =
|
|
4708
|
+
callerId === undefined ? undefined : this.#recallCommandBody(record.deviceId, callerId)
|
|
4709
|
+
if (remembered !== undefined && remembered.method !== CANCEL_METHOD) throw commandBodyDiffers()
|
|
4710
|
+
if (remembered !== undefined) {
|
|
4711
|
+
if (!sameCommandValue(remembered.fingerprint, { sessionId, expectedExecutionId: supplied })) {
|
|
4712
|
+
throw commandBodyDiffers()
|
|
4713
|
+
}
|
|
4714
|
+
return this.#command(connection, CANCEL_METHOD, remembered.body)
|
|
4715
|
+
}
|
|
4262
4716
|
|
|
4263
4717
|
await this.#ensureSubscription(record.deviceId, sessionId)
|
|
4264
4718
|
const subscriptions = this.#deps.subs(record.deviceId)
|
|
@@ -4274,7 +4728,6 @@ class CherryToolEngine {
|
|
|
4274
4728
|
message: `session ${sessionId} has no in-flight execution to cancel`,
|
|
4275
4729
|
} satisfies Record<string, unknown>
|
|
4276
4730
|
}
|
|
4277
|
-
const supplied = optionalString(args['expectedExecutionId'])
|
|
4278
4731
|
if (supplied !== undefined && supplied !== expectedExecutionId) {
|
|
4279
4732
|
return {
|
|
4280
4733
|
error: 'execution-mismatch',
|
|
@@ -4286,11 +4739,18 @@ class CherryToolEngine {
|
|
|
4286
4739
|
} satisfies Record<string, unknown>
|
|
4287
4740
|
}
|
|
4288
4741
|
|
|
4289
|
-
|
|
4290
|
-
|
|
4291
|
-
|
|
4292
|
-
|
|
4293
|
-
|
|
4742
|
+
const commandId = this.#commandId(args)
|
|
4743
|
+
const body = { commandId, sessionId, expectedExecutionId }
|
|
4744
|
+
// ISSUE-TIME WRITE, as respond's: the derived execution id is exactly
|
|
4745
|
+
// the field a retry cannot re-derive once the run has ended.
|
|
4746
|
+
if (callerId !== undefined) {
|
|
4747
|
+
this.#rememberCommandBody(record.deviceId, callerId, {
|
|
4748
|
+
method: CANCEL_METHOD,
|
|
4749
|
+
fingerprint: { sessionId, expectedExecutionId: supplied },
|
|
4750
|
+
body,
|
|
4751
|
+
})
|
|
4752
|
+
}
|
|
4753
|
+
return this.#command(connection, CANCEL_METHOD, body)
|
|
4294
4754
|
},
|
|
4295
4755
|
})
|
|
4296
4756
|
}
|
|
@@ -4451,7 +4911,7 @@ class CherryToolEngine {
|
|
|
4451
4911
|
// pairing's idle revisions and execution ids, and would grow the maps
|
|
4452
4912
|
// for the lifetime of the process. The store record is untouched by
|
|
4453
4913
|
// this — the caches are pure derived state and can always be rebuilt.
|
|
4454
|
-
this.#forgetDevice(record.deviceId)
|
|
4914
|
+
this.#forgetDevice(record.deviceId, { dropCommandBodies: true })
|
|
4455
4915
|
await this.#deps.evict(record.deviceId)
|
|
4456
4916
|
// The remove is GUARDED, not merely ordered. `#selectRecords` already
|
|
4457
4917
|
// rejects a quarantined store before a record can be named, so reaching
|
|
@@ -4812,7 +5272,8 @@ class CherryToolEngine {
|
|
|
4812
5272
|
* the stored credential no longer describes a valid pairing. A transient
|
|
4813
5273
|
* network drop ALSO lands here and clears the caches unnecessarily; that
|
|
4814
5274
|
* is accepted, because the cost is one round trip per session on reuse and
|
|
4815
|
-
* the alternative is keeping snapshots across an identity change.
|
|
5275
|
+
* the alternative is keeping snapshots across an identity change. (The
|
|
5276
|
+
* remembered command BODIES are the one exception: see `#forgetDevice`.)
|
|
4816
5277
|
* - `identity-mismatch` — the peer's pinned key changed: the pairing is over.
|
|
4817
5278
|
*
|
|
4818
5279
|
* {@link CherryToolEngine.#resolve} installs the watch on every tool call that
|
|
@@ -4840,7 +5301,8 @@ class CherryToolEngine {
|
|
|
4840
5301
|
this.#watchedConnections.add(connection)
|
|
4841
5302
|
watch(deviceId, (state) => {
|
|
4842
5303
|
if (state !== 'offline' && state !== 'identity-mismatch') return
|
|
4843
|
-
|
|
5304
|
+
// A plain `offline` keeps the remembered command bodies: see `#forgetDevice`.
|
|
5305
|
+
this.#forgetDevice(deviceId, { dropCommandBodies: state === 'identity-mismatch' })
|
|
4844
5306
|
})
|
|
4845
5307
|
}
|
|
4846
5308
|
|
|
@@ -4853,8 +5315,16 @@ class CherryToolEngine {
|
|
|
4853
5315
|
* leaves the archive (`cherry_unpair`), so a re-paired device cannot inherit
|
|
4854
5316
|
* the previous pairing's snapshots and a long-lived process does not
|
|
4855
5317
|
* accumulate entries for devices that no longer exist.
|
|
5318
|
+
*
|
|
5319
|
+
* The remembered command bodies obey a NARROWER seam than the read caches:
|
|
5320
|
+
* `dropCommandBodies` is passed by the callers that invalidate the PAIRING
|
|
5321
|
+
* (unpair, identity-mismatch), never by an ordinary `offline`. What a body
|
|
5322
|
+
* replays against — the peer's command ledger — survives a reconnect, and the
|
|
5323
|
+
* body is the only local copy of the exact bytes that ledger will accept, so
|
|
5324
|
+
* a link drop that emptied it would cost the recovery itself, where the read
|
|
5325
|
+
* caches merely pay one re-walk.
|
|
4856
5326
|
*/
|
|
4857
|
-
#forgetDevice(deviceId: string): void {
|
|
5327
|
+
#forgetDevice(deviceId: string, options: { dropCommandBodies?: boolean } = {}): void {
|
|
4858
5328
|
const prefix = `${deviceId}\u0000`
|
|
4859
5329
|
for (const key of [...this.#revisionCache.keys()]) {
|
|
4860
5330
|
if (key.startsWith(prefix)) this.#forget(this.#revisionCache, key)
|
|
@@ -4875,6 +5345,116 @@ class CherryToolEngine {
|
|
|
4875
5345
|
for (const key of [...this.#messageCache.keys()]) {
|
|
4876
5346
|
if (key.startsWith(prefix)) this.#dropCachedMessage(key)
|
|
4877
5347
|
}
|
|
5348
|
+
// The remembered command bodies (issues #115/#118) differ from every cache above:
|
|
5349
|
+
// what they replay against is the peer's command LEDGER, and that survives
|
|
5350
|
+
// an ordinary reconnect — so they are dropped only when the PAIRING is
|
|
5351
|
+
// invalidated (`dropCommandBodies`: unpair, identity-mismatch), because a
|
|
5352
|
+
// body minted against one pairing must not be replayed to whatever desktop
|
|
5353
|
+
// answers under this device id next.
|
|
5354
|
+
//
|
|
5355
|
+
// The residual, stated rather than closed: GRANT_REVOKED also surfaces as
|
|
5356
|
+
// `offline`, so a voided pairing's entries survive until the re-pair path
|
|
5357
|
+
// (unpair / identity-mismatch) or the 128-entry FIFO retires them; a same-id
|
|
5358
|
+
// retry across a silent re-pair replays a body the new peer admits as a NEW
|
|
5359
|
+
// command — and the caller asked for that send.
|
|
5360
|
+
if (options.dropCommandBodies === true) {
|
|
5361
|
+
for (const key of [...this.#commandBodies.keys()]) {
|
|
5362
|
+
if (key.startsWith(prefix)) this.#forget(this.#commandBodies, key)
|
|
5363
|
+
}
|
|
5364
|
+
}
|
|
5365
|
+
}
|
|
5366
|
+
|
|
5367
|
+
/**
|
|
5368
|
+
* The command remembered for one caller-supplied `commandId`, keyed
|
|
5369
|
+
* `<deviceId>\0<commandId>` — or `undefined` when this device has never
|
|
5370
|
+
* emitted one (a first attempt, or an entry the FIFO evicted).
|
|
5371
|
+
*
|
|
5372
|
+
* The METHOD is the caller's to judge, and it is a THREE-WAY decision, never
|
|
5373
|
+
* a miss:
|
|
5374
|
+
*
|
|
5375
|
+
* - no entry → a fresh call;
|
|
5376
|
+
* - an entry under the caller's own method → match the fingerprint, then
|
|
5377
|
+
* replay or refuse;
|
|
5378
|
+
* - an entry under a DIFFERENT method → a MISMATCH, refused locally. An id
|
|
5379
|
+
* minted for `agent.messages.send` is not a respond retry, and collapsing
|
|
5380
|
+
* that case into "no entry" would send a respond under a send's id and
|
|
5381
|
+
* let the PEER answer the conflict one round trip later.
|
|
5382
|
+
*/
|
|
5383
|
+
#recallCommandBody(deviceId: string, commandId: string): RememberedCommand | undefined {
|
|
5384
|
+
return this.#commandBodies.get(this.#cacheKey(deviceId, commandId))
|
|
5385
|
+
}
|
|
5386
|
+
|
|
5387
|
+
/**
|
|
5388
|
+
* TEST SEAM — the remembered bodies, as one `commandId` per device.
|
|
5389
|
+
*
|
|
5390
|
+
* The memory itself is PRIVATE, and stays that way for callers. What a test
|
|
5391
|
+
* needs to assert is its bookkeeping — that the bound evicts the oldest entry
|
|
5392
|
+
* and that {@link CherryToolEngine.#forgetDevice} drops a device's entries —
|
|
5393
|
+
* and neither can be observed through a real retry: a retry of an evicted id
|
|
5394
|
+
* is indistinguishable from a retry of an absent one, because both are refused
|
|
5395
|
+
* locally by the same rule. Keys are rendered WITHOUT the device component so
|
|
5396
|
+
* a test reads ids, not cache internals.
|
|
5397
|
+
*/
|
|
5398
|
+
rememberedCommandIds(deviceId: string): string[] {
|
|
5399
|
+
const prefix = `${deviceId}${CACHE_KEY_SEPARATOR}`
|
|
5400
|
+
return [...this.#commandBodies.keys()]
|
|
5401
|
+
.filter((key) => key.startsWith(prefix))
|
|
5402
|
+
.map((key) => key.slice(prefix.length))
|
|
5403
|
+
}
|
|
5404
|
+
|
|
5405
|
+
/**
|
|
5406
|
+
* TEST SEAM — fill the memory the way a long-lived process would: one entry
|
|
5407
|
+
* per id, WITHOUT spending a wire call on each. The bound and the FIFO order
|
|
5408
|
+
* are the engine's own ({@link CherryToolEngine.#rememberCommandBody}), which
|
|
5409
|
+
* is what makes this a test of the real policy rather than of a mock of it.
|
|
5410
|
+
*/
|
|
5411
|
+
rememberCommandBodyForTest(deviceId: string, commandId: string): void {
|
|
5412
|
+
this.#rememberCommandBody(deviceId, commandId, {
|
|
5413
|
+
method: 'agent.messages.send',
|
|
5414
|
+
fingerprint: { sessionId: 'session-for-test', text: 'text-for-test' },
|
|
5415
|
+
body: {
|
|
5416
|
+
commandId,
|
|
5417
|
+
sessionId: 'session-for-test',
|
|
5418
|
+
text: 'text-for-test',
|
|
5419
|
+
expectedIdleRevision: '0',
|
|
5420
|
+
},
|
|
5421
|
+
})
|
|
5422
|
+
}
|
|
5423
|
+
|
|
5424
|
+
/**
|
|
5425
|
+
* Remembers the exact body one caller-supplied `commandId` was ISSUED with,
|
|
5426
|
+
* evicting this device's oldest entry when it is at the bound.
|
|
5427
|
+
*
|
|
5428
|
+
* FIFO, per device: `Map` insertion order IS the policy, the same deliberate
|
|
5429
|
+
* choice the session caches document, and a `set` on an EXISTING key keeps its
|
|
5430
|
+
* position — a refresh is a rewrite, not a use, so the policy stays
|
|
5431
|
+
* insert-order rather than becoming LRU. One line per eviction, naming the
|
|
5432
|
+
* device and the bound only.
|
|
5433
|
+
*/
|
|
5434
|
+
#rememberCommandBody(
|
|
5435
|
+
deviceId: string,
|
|
5436
|
+
commandId: string,
|
|
5437
|
+
remembered: RememberedCommand,
|
|
5438
|
+
): void {
|
|
5439
|
+
const key = this.#cacheKey(deviceId, commandId)
|
|
5440
|
+
if (!this.#commandBodies.has(key)) {
|
|
5441
|
+
let own = 0
|
|
5442
|
+
let oldest: string | undefined
|
|
5443
|
+
for (const candidate of this.#commandBodies.keys()) {
|
|
5444
|
+
if (!candidate.startsWith(`${deviceId}\u0000`)) continue
|
|
5445
|
+
own += 1
|
|
5446
|
+
if (oldest === undefined) oldest = candidate
|
|
5447
|
+
}
|
|
5448
|
+
if (own >= this.#commandBodyEntriesPerDevice && oldest !== undefined) {
|
|
5449
|
+
this.#commandBodies.delete(oldest)
|
|
5450
|
+
console.warn(
|
|
5451
|
+
`[cherry-remote] remembered command bodies for device ${deviceId} reached their ` +
|
|
5452
|
+
`${this.#commandBodyEntriesPerDevice}-commandId bound; evicted the oldest (a retry of ` +
|
|
5453
|
+
'that commandId now re-derives its body, and the peer decides whether it replays)',
|
|
5454
|
+
)
|
|
5455
|
+
}
|
|
5456
|
+
}
|
|
5457
|
+
this.#commandBodies.set(key, remembered)
|
|
4878
5458
|
}
|
|
4879
5459
|
|
|
4880
5460
|
/**
|