Agent Inbox

Messages for this machine that this agent has not read yet.

lmcp-mac#543: with peek=true it is a read and nothing else. It serves what this reader has not ACKNOWLEDGED (a delivered message comes back until agent_ack names it) and writes nothing about the messages; the delivered mark is then written by the acknowledgement. Without peek (every client up to 3.0.420, and a tray's background poll) nothing changes: the same statements, and serving a message stamps it delivered, which is what keeps those clients from getting it twice.

Reads are per agent, so a broadcast to the machine reaches every agent on it instead of the first one to poll swallowing it.

Delivery is at-least-once, not exactly-once: the SELECT and the read-marking INSERT are separate statements under READ COMMITTED, so two concurrent polls by the same agent_id can both return the same message. Nothing is lost; a message can repeat. Coordination messages are idempotent to act on (a second freeze means what the first one meant), so this is left as is rather than paying for SELECT ... FOR UPDATE SKIP LOCKED.

get/agent/inbox

Request

  • Base URL: https://api.local-mcp.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.local-mcp.com/agent/inbox
  • Auth: none declared

Query parameters

agent_idstring required

Who reads (an agent session)

limitinteger
backgroundboolean

true when the client's automatic consumer makes the call, not the agent: it does not count as activity and does not renew presence.

peekboolean

true to read without marking: the messages this agent has not acknowledged are served and nothing is written about them; agent_ack then marks them delivered and acknowledged. Without it, serving a message marks it delivered.

wake_tokenstring nullable

The token of an auto-wake prompt (MESH_WAKE_STATES only).

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.