HTTP binding

This document is part of the sessionpipe protocol and is licensed under CC BY 4.0. The words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119. Status: Draft (see VERSIONING.md).

The protocol's events (PROTOCOL.md) travel to a receiver over HTTPS. This document is the binding: discovery, the batch request, responses and errors, retry, idempotency, the control long-poll and the native lane. The header names and signature scheme are those of Standard Webhooks, verbatim.

1. Discovery: GET /.well-known/sessionpipe

At the receiver's origin root. A sender reads it when a sink is added and re-reads it at most daily (24 h cache); a receiver MAY set Cache-Control.

{
  "protocol": [1],
  "max_tier": 2,
  "capabilities": ["events", "backfill", "forget", "control", "native"],
  "auth": ["bearer"],
  "endpoints": {
    "events":  "/api/sessionpipe/v1/events",
    "control": "/api/sessionpipe/v1/control",
    "native":  "/api/sessionpipe/v1/native"
  },
  "batch":   { "max_events": 50, "max_bytes": 262144 },
  "control": { "wait_max_s": 25, "signing": { "rp_id": "receiver.example", "algs": [-7, -257], "key_types": ["passkey", "device"] }, "files": true }
}

Schema: well-known.json.

2. Events: POST {events}

Body {"events":[…]} — 1 to batch.max_events events, at most batch.max_bytes bytes (batch.json).

Request headers:

Response 202 with batch-response.json:

{ "accepted": 47, "duplicates": 3, "rejected": [{ "id": "01K6…", "reason": "tier_type" }], "max_tier": 2 }

accepted + duplicates + rejected.length MUST equal the number of events sent. A rejected event is one the receiver will never store (its reason says why); the batch as a whole still succeeded and the sender's cursor moves past it. max_tier repeats the well-known value so a sender learns a lowered cap without a discovery round trip.

Errors

Bodies of 4xx/5xx responses SHOULD be error.json. The sender's cursor moves only on 202.

Idempotency

A receiver MUST deduplicate on (harness.name, session.id, session.seq) and count a repeat in duplicates. Order of arrival is not guaranteed; seq is the order. A receiver SHOULD keep at least the highest seq per session plus a window of recent values, so a replay after an outage costs nothing.

Time

A receiver MUST record its own arrival time beside time. The difference is the delivery latency the project measures (target: p50 under 2 s on a laptop).

3. Control: {control}

Only when the well-known file lists control. The messages, keys and checks are CONTROL.md; this section is the wire. One machine daemon holds one long-poll per receiver, whatever the number of sessions.

• The machine's token opens these machine calls (hello, poll, ack, off, files) for that one machine and nothing else of the account. A receiver MUST refuse a sink token on them, and the machine's token everywhere else.
• A receiver MUST keep re-delivering a message on every poll until it is acked or its expires_at passes, then drop it. A taken ack pauses redelivery for 35 minutes (CONTROL.md §10); a final ack ends it. A machine MAY receive the same message twice; the signed nonce makes the second one a replay.
• A poll is also the machine's heartbeat: a receiver MAY show a machine that polled within 2 × wait_max_s as online, and SHOULD hand a session the waiter (CONTROL.md §8) only while its machine is online.
• Files. A receiver that accepts files on a start or a prompt (CONTROL.md §3.1) holds each file's bytes, named by the base64url SHA-256 the command carries, and serves them at GET {control}/files/{sha256} to the machines of the account that uploaded them and to no one else. It MUST keep them at least until the command's expires_at. How the bytes reach the receiver is the receiver's business. The machine checks length and hash itself (CONTROL.md §6) and stops reading past the signed size; a receiver SHOULD send content-length. A receiver SHOULD NOT queue a start with files for a machine whose hello did not say files: true, nor a prompt with files for one whose hello did not say prompt_files: true.
• 401 on a machine call means the token is gone (the machine was removed): the daemon stops polling that receiver and says so. 404 on /pair?code= means no such pairing.

4. Native lane: POST {native}/<harness>

Raw hook JSON exactly as a harness's own HTTP hook handler sends it (Claude Code type: "http", Copilot CLI). The receiver normalises it with core's adapter, stores it at the tier it declared for the lane (≤ 1), and records privacy.rulesets: [] — no redaction ran at source. This lane exists for a receiver you own on a machine you own; a public receiver SHOULD NOT advertise native.

5. Forget

A session.forgotten event (any tier) asks the receiver to delete everything it holds for that session: events, transcripts, derived data. A receiver that lists forget MUST do so before answering 202 (or within a stated retention window, documented on its /.well-known origin), and MUST answer later reads of the session as though it never existed.

6. Transport requirements

• HTTPS on any host that is not localhost / 127.0.0.1 / [::1].
• A sender's request timeout is 15 s; a worker that cannot reach a sink leaves the backlog for the next worker.
• A sender MUST send session.* and turn.* events of one session in seq order within a batch; across batches order is best effort.
• A sender SHOULD start at most one request a second per machine, and send in it everything that arrived while it waited: a busy machine is then one request a second with a full batch, not one per hook (sessionpipe issue #208). A lone event still goes at once, and the full batches of a backlog MAY follow one another. A receiver that limits requests per machine SHOULD allow at least one a second.
• A sender MAY thin a sink's tool events (PROTOCOL.md §4): the seq of one session then has gaps, which a receiver accepts like any other.

7. Delivery scenarios (conformance)

The runner sends and expects, in this order; each is a fixture under conformance/delivery/: