Behaviour for per-agent webhook delivery persistence and dispatch.

An inbox implementation owns three responsibilities:

• persistence — storing verified inbound deliveries so an agent can read them back later via the webhook_inbox tool
• dispatch — deciding when (immediately, debounced, throttled) and how (single pointer, coalesced batch) to notify the receiving agent via SkillKit.send_event/3
• retention — bounding storage (LRU, TTL) so unbounded inbound traffic doesn't leak memory

The default implementation is SkillKit.Webhook.Inbox.Memory (ETS-backed, immediate dispatch). Hosts can swap in File, S3, or custom impls by passing {inbox: {MyInbox, opts}} to SkillKit.Webhook.Supervisor.start_link/1.

Entry shape

The Plug hands off a single map containing everything the inbox needs to both persist the delivery and, when it decides to emit, call SkillKit.send_event/3 on the agent:

%{
  agent: %SkillKit.AgentRef{},           # how to address the receiving agent
  prompt: String.t(),                     # user-authored webhook intent
  delivery: %{
    id: String.t(),
    webhook_id: String.t(),
    agent_name: String.t(),
    received_at: DateTime.t(),
    method: String.t(),
    headers: %{String.t() => String.t()},
    query: %{String.t() => String.t()},
    body: binary()
  }
}

Read semantics

read/4 resolves opts[:selector] against the delivery's structure, then optionally sub-slices:

• when the resolved value is an array: offset + limit select a range
• when the resolved value is multi-line text: line_start + line_end (exclusive) select a line range
• when the resolved value is a string/binary: offset_bytes + limit_bytes select a byte range

The limit_bytes option is the final safety net: regardless of what slicing ran, the serialized result is capped at limit_bytes (default from inbox config) and truncated: true is set when clipped.

Opts that don't apply to the resolved value type are silently ignored.

Selector syntax

• "" or "." — the whole delivery (rare; usually select a sub-tree)
• "body" — the parsed body (JSON-decoded if applicable, else raw text)
• "headers" — header map
• "body.commits[0].message" — dot-walk + array indexing
• "body.commits[].message" — array projection (map across array)
• "headers.x-github-event" — header lookup