Cross-Session Messaging — Agent-to-Agent HTTP (part 3)
Part 3 of the cross-session messaging page: the delivery limits and retry safety, the plain-language boundaries of the feature, and the full request and response reference with the code that implements it.
On this page
What it is
This is part 3 of the Cross-Session Messaging — Agent-to-Agent HTTP page. It covers the mechanics and limits of delivery — how often you may send, and how to make a send safe to retry — the plain-language boundaries of the feature, and the full request and response reference for anyone calling these routes or maintaining them.
Where to find it
There is no button for any of this in the app: the surface is the local control server Omniscio runs on your own machine, which trusted scripts and other sessions talk to. The routes below are that surface, and the retired route that used to sit beside them is described in the same reference.
How it behaves
Rate limiting
Per-bearer-token sliding window: 120 calls per hour, shared across the peer routes. Hitting the cap returns:
429 Too Many Requests
{ "ok": false, "error": "rate_limited", "retryAfterMs": <ms-until-oldest-call-ages-out> }
A message the person sends from the phone (the web-remote send response and deliver message doors) has its own window of 120 per hour, and nothing else. It never shares the agent fleet's all-senders ceiling, so a busy fleet can never refuse the owner's own words with "Too many messages from this device" (seen on 2026-11-11, when fleet peer traffic kept that ceiling full for hours while the phone had sent 15 messages).
In-memory only (process restart resets the bucket). Acceptable because this is a developer-tool feature, not a billing gate. An idempotent replay (see below) is served before the rate-limit check, so a retry of an already-succeeded call never consumes a slot or 429s.
Idempotency (retry-safe)
peer-message delivers a real, non-reversible side effect — an operator turn the target session then processes (burning tokens; it can also wake + re-spawn a stopped session). A network/LB retry, a double-click, or a queue redelivery would otherwise deliver it twice.
To make a call retry-safe, send an idempotency key as a header:
X-Client-Request-Id: <a unique id per logical request>
The first delivery is recorded; a retry with the same key replays the original result instead of delivering again — the response is byte-identical plus "idempotent": true:
{ "ok": true, "delivered": true, "wokenFrom": null, "idempotent": true }
Rules:
- Key-only. With no header, behaviour is exactly as before (no dedup) — Omniscio never silently drops an un-keyed repeat.
- One key per logical request. Reusing a key for a different payload replays the original result (the standard idempotency-key contract). Mint a fresh UUID per request.
- Concurrent duplicate — a retry that arrives while the first is still being delivered returns
409 duplicate_in_flightinstead of delivering twice. - Failures aren't cached — a call that returns an error (or times out) releases the key, so a genuine retry can still succeed.
- In-memory, ~10-min window. Like the rate-limit bucket, the store is in-memory (a process restart clears it). It covers the realistic trigger — a retry within seconds against the live app — not a cross-restart replay.
- A held answer replays whole. The replay repeats the first answer exactly,
bodyIdand thedetailsentence included. A message can wait far longer than ten minutes behind a busy target, and a re-POST after the window is a new send, not a replay (measured: a re-POST 55 minutes later delivered a second message) — before re-sending a held message, readGET /sessions/<your session id>/peer-messages-sentand check whether the first one was delivered or is still held.
What this is NOT
- No sender-side UI (yet). There's no "Send peer message" button in the Omniscio sidebar — the v1 SEND surface is HTTP-only for agent-to-agent use. (The RECEIVING side DOES render: a directed peer-message shows as a tagged "injected by …" operator bubble.) A send UI can come later if humans want to drive it.
- Not approval-gated. Unlike
POST /agent/sessions(which spawns a brand-new session and lands in the inbox for approval), peer messaging assumes the target session already exists and the bearer-token holder already has authority over the Omniscio instance — same trust boundary as the/sessions/:id/follow-upendpoint. - Not loop-protected beyond rate limit. Two agents sending peer-messages back and forth will hit the 120/hour cap quickly — that's the only loop-break.
- Not silent-flag-aware. Silent recipe sessions (the ones hidden from sidebar/inbox while running) stay silent on receive. The injected turn still lands; surface visibility is unchanged.
- Not persistent across restart — the RATE-LIMIT BUCKET and the idempotency store only. Process restart resets both. Acceptable for a developer-tool feature; if this ever becomes a billing gate, persist to SQLite. An UNDELIVERED payload is a different matter and IS durable — it goes to
peer_message_dead_lettersand survives restart (see "When it CAN'T be delivered" above).
Why peer-aside is gone
The retired route below is documented here so nobody rebuilds it under another name; the reasoning behind the retirement, and what to do instead, is on the parent page.
Related
The overview of the feature is on the Cross-Session Messaging — Agent-to-Agent HTTP page, and what happens to an undelivered message plus how arrivals render is in part 2. The other agent-control endpoint family is agent-driven sessions, and the gating rules for every control-server endpoint are in cli-control.
Last verified 2026-10-05