# Assist

A visitor asks for help from the page they are on, and someone from support takes the request from a list. Or support sees a live recording and offers help. With [Holler for Laravel](https://github.com/packstub/holler) installed, the two are put on a call between the visitor's page and the agent; without it, the requests are a plain queue your app answers through its own channels.

Everything lives in this package: the requests and their routes, the "Get help" API and button on the visitor's page, and the agent's side in the built-in viewer (the Live tab, Offer help, the Requests page and the live stage). [Filament Session Replay](https://github.com/packstub/filament-session-replay/blob/main/docs/assist.md) brings the same into a panel and hosts the same stage ([Hosting the stage](#hosting-the-stage-in-a-page-of-your-own)).

**What the live view needs.** The queue works with this package alone. The live view (the call, the mirror, remote control, audio) runs on [Holler for Laravel](https://github.com/packstub/holler) 1.x (`packstub/holler`), and in a Filament panel on [Filament Holler](https://github.com/packstub/filament-holler) (`packstub/filament-holler`) as well. Assist turns the live view on by itself once Holler is installed; [With Holler](#with-holler) has the steps.

## Turning it on

```env
SESSION_REPLAY_ASSIST=true
```

Assist is off by default: once on, every recorded page can open requests. Run `php artisan migrate` for the `replay_assist_requests` table.

Who may help is your gate's decision by default: whoever may watch a recording may help its person. To narrow it:

```php
use Packstub\SessionReplay\Facades\SessionReplay;
use Packstub\SessionReplay\Models\AssistRequest;
use Packstub\SessionReplay\Models\ReplaySession;

SessionReplay::canAssistUsing(fn ($agent, ?ReplaySession $session, AssistRequest $request): bool => $agent->hasRole('support'));
```

`canAssist` is asked on every agent endpoint, not only when the list is drawn. Nobody assists their own visit: a request of the agent's own recording is refused whatever the rule says. The list also follows `SessionReplay::visibleUsing()`, like the recordings list.

### Several workspaces

- **Requests without a recording.** `$session` is null for a request from a tab that records nothing, so `visibleUsing()` has nothing to look at. While you have a `visibleUsing()` rule and no `canAssistUsing()` rule, those requests are shown to nobody and cannot be claimed: one workspace's agents never see another's visitors by accident. To take them, register `canAssistUsing()` and check `$request->tenant_type` and `$request->tenant_id` there.
- **Requests of a workspace without a recording.** Even without a `visibleUsing()` rule, the gate alone never hands them out: such a request is shown only to an agent placed in its workspace (by `tenantUsing()`, or by a caller that passes the agent's workspace, as the Filament package does for a panel scoped to its tenant), to the agent who already holds it, or under a `canAssistUsing()` rule. An operator console that should see every workspace's requests registers `canAssistUsing()`.
- **The agent's workspace.** When the app registered `SessionReplay::tenantUsing()`, it is asked for the agent's own request too: if it names a workspace (the team in the URL, the panel's tenant), the agent sees and acts on that workspace's requests only, with or without a recording. When it names none (an operator console), the other rules decide alone.
- **Limits.** `assist.max_open_requests` counts per workspace, so a flood in one workspace never fills another's list.

### With Holler

Install [Holler for Laravel](https://github.com/packstub/holler) and run its migrations:

```bash
composer require packstub/holler
php artisan migrate
```

Register Holler's routes in `routes/web.php` (the live stage talks to them, see [The live stage](#the-live-stage)) and schedule Holler's cleanup:

```php
use Packstub\Holler\Facades\Holler;

Holler::routes();

// routes/console.php
Schedule::command('holler:prune')->daily();
```

Holler's widget and buttons are not needed for Assist: the visitor's page and the stage bring their own call client. In a Filament panel, Filament Holler registers the routes in the panel instead; see [Filament Session Replay's Assist docs](https://github.com/packstub/filament-session-replay/blob/main/docs/assist.md).

Assist uses Holler on its own once it is there (`assist.calls` turns that off). The agent is the viewer guard's user, and Holler rings them by the same id, so in a plain Laravel app `session-replay.viewer.guard` and `holler.guard` must name the same guard (in Filament both are the panel's). Claiming a request refuses with a clear message when the two see different people (`guard_mismatch`), instead of creating a call the agent's browser never sees.

The call itself is created later, in the visitor's request, where no panel is active. So the claim (or the offer) stores who the agent is to the place they acted from: their model's morph class, the guard's name and Holler's scope there. The visitor's request loads the agent from those and starts the call in that scope, never through the app's default guard: an agent on a panel's `admin` guard is rung as that admin, and their panel's Holler poll sees the call.

With a database per tenant, `session-replay.storage.connection` points at the central database; set `holler.connection` to the same connection. The visitor's request and the agent's panel run on different default connections, and a call on either one's would never reach the other. While `storage.connection` is set and `holler.connection` differs, claiming and offering refuse (`connection_mismatch`).

An assist call has the kind `assist`: the Holler widget, which polls for `kind=call`, never sees it. An agent helps one visitor at a time: starting another call ends the assist.

**One call at a time per person, whatever its kind.** Holler keeps a person on a single call (one microphone, one camera), across kinds: starting a call leaves the one you are on. So an agent who is on a Holler widget call with a colleague leaves it when a visitor's page picks up their claim, and a colleague who rings an agent during an assist hears they are busy. Ask agents to hang up before they claim, or check `Holler::openCallsOf($agentId)` in your own UI first.

**ICE servers for both ends.** The visitor's page gets its ICE servers in its own request, outside any panel, so it reads Holler's config (`holler.ice_servers`, the `HOLLER_TURN_*` variables), not a Filament panel's `->iceServers()`. Put a TURN server in the config, not only on the panel, or a visitor behind a strict NAT (and every visitor with `ice_transport_policy` set to `relay`) cannot connect. The visitor's browser receives those TURN credentials, like any caller's; mention the STUN or TURN provider in your privacy notice when it is a third party.

**Versions.** Holler for Laravel needs Laravel 12.69+ or 13.30+, and Filament Holler needs Filament 5.8.3+ (or 4.13.3+), which is more than Session Replay alone asks for.

### Without Holler

A request goes `open`, then `claimed` by an agent, then `ended` by the agent. `AssistClaimed` is where your app reaches out (a chat message, an email). Offering help from a live recording needs Holler.

## How a request moves

| From → to | By | When |
| --- | --- | --- |
| `open` → `claimed` | agent | an agent takes a visitor's request; two agents cannot both get it |
| `open` → `active` | visitor | the visitor accepts an agent's offer; the call is created then |
| `claimed` → `active` | visitor's page | its next poll acknowledges the claim while the agent's stage is open (it polled in the last 10 seconds); the call is created then |
| `active` → `claimed` | Holler | the agent left the live view for longer than `holler.reconnect_timeout` (15 s) and Holler dropped their side: the request stays the agent's, without a call, and the visitor's page says they are reconnecting ([Leaving the live view](#leaving-the-live-view)) |
| `claimed` → `open` | timeout, agent | the page did not acknowledge within `assist.claim_timeout_seconds` (30), the agent who left the live view did not come back within it, or the agent let go of the claim or may no longer help (the visitor still waits; someone else may take it) |
| `open`, `claimed` → `cancelled` | visitor | Cancel, or the page is signed in as someone else now |
| `open` → `declined` | visitor | "Not now" on an agent's offer |
| `open`, `claimed` → `expired` | timeout | an offer unanswered for `assist.proposal_timeout_seconds` (60), or a page that stopped polling for `assist.visitor_timeout_seconds` (60) |
| `open` → `withdrawn` | agent | the agent takes the offer back, or may no longer help (`canAssist` is asked again when the visitor accepts; `end_reason` `not_allowed`) |
| `claimed`, `active` → `ended` | agent, Holler, timeout | the agent ends it, the call ended (Holler's reason: `hung_up`, or `dropped` when the visitor's page went away), the visitor hung up, the page went quiet, `assist.max_duration_minutes` (120, counted from the first start) passed, or the agent may no longer help (`not_allowed`: the viewer gate, `visibleUsing()` and `canAssist` asked again on the stage's status poll, the gate also on any of the agent's request routes, and `canAssist` every 10 seconds on the visitor's poll) |

A recording has at most one request going at a time (a tab without a recording, one per tab: the recorder keeps an id per tab in `sessionStorage` and sends it with the request, so pages served from a full-page cache, which share a nonce, still get one each): asking again returns the one that is going. The timeouts run inside the visitor's poll and the agent's list, the way Holler expires calls inside its poll: no scheduler needed. Over the list they run at most once every 5 seconds per workspace, however many agents have it open.

When a request finishes, the server puts an `assist` marker on the recording: how it was opened, how it ended, how long it ran and what the visitor allowed, with how long each was on ("control 2 min, audio 45 s"), never who the agent is. It sits on the recording's own clock (the browser's, read off its last upload), so it lines up with the events around it. A browser cannot send an `assist` marker itself.

## On the visitor's page

With Assist on, the recorder brings everything the visitor sees; nothing to add to your pages.

The recorder itself only carries a small hook (about 4 KB): the heartbeat, the offer in the upload answer and `SessionReplay.assist`. The rest, the calls engine and the visitor's panel, is a separate script (`{path}/scripts/assist.js`, about 70 KB, 23 KB gzipped) that the recorder loads with a dynamic `import()` the first time it is needed: an agent's offer arrives, the tab has a request going (after a reload), the "Get help" button is on, or the page calls `SessionReplay.assist.request()`. A page where nobody asks for help never downloads it.

**Content Security Policy.** The module comes from the same origin and route as the recorder, with the package's version in the URL; the recorder refuses to `import()` a module URL on another origin. A policy that allows the recorder by host (`script-src 'self'`) allows it too. A policy that allows scripts by nonce only needs `'strict-dynamic'` (a script with the nonce may then import), or `'self'` next to the nonce. The poll timer runs in a Web Worker made from a `blob:` URL (`worker-src blob:`); without it, plain timers take over.

### Asking for help

From your own "Contact support" button:

```js
await SessionReplay.assist.request({ message: 'The checkout button does nothing' })
SessionReplay.assist.status()   // { id, status: 'open' | 'claimed' | 'active' | null, agent: { name, avatar } | null }
SessionReplay.assist.cancel()   // stop waiting
SessionReplay.assist.end()      // end a live assist (or stop waiting)

window.addEventListener('session-replay:assist', ({ detail }) => updateMyButton(detail.status))
```

Or turn on the floating "Get help" button (`assist.button`, off by default; most apps have a place for it already), which opens a small form with an optional message. With the button on, every recorded page loads the Assist module up front, since the button is part of it.

While the request waits, a panel in the corner says so, with Cancel. A tab in mode `on_error` starts uploading when it asks (as `SessionReplay.send()` does), so the agent has a recording to look at. A tab that records nothing (not sampled, no consent) can still ask: the request is queue-only, the agent sees no live page.

### Guests

Guests (nobody signed in, recorded with `session-replay.guests`) may ask while `assist.guests` is on (the default). Anyone can get a guest token by loading a page, so guests have a budget of their own: `assist.guest_requests_per_hour` (20) new requests per hour for all guests of a workspace together, on top of the per-page limit. While that budget is set, a guest asks only from a recording that has events on the server; a request from a tab that records nothing, or before the first upload, is refused (`no_recording`). Set `assist.guests` to `false` to take requests from signed-in people only (`guests`).

### An offer of help

When an agent offers help from a live recording, the page hears of it in the answer to its next upload, or to the heartbeat a visible tab sends every `assist.heartbeat_seconds` (15). The visitor sees "Ana would like to help you with this page", with Accept and Not now. A hidden tab hears of the offer when the visitor comes back to it.

### While an agent is with the visitor

- **The pointer.** While the agent watches, the visitor sees where they point: the agent's named cursor, at the place the agent's pointer is on their view of the page ("look here"). No question, like annotations: it is only drawn and changes nothing on the page; a click still needs remote control and its own yes. It goes when the agent's pointer leaves the page, after three seconds without moving, while a question is up and while the tab is hidden.
- **Watching.** The agent sees the page as the recording has it, masked the same way: the recorder's own events, sent peer to peer over a WebRTC data channel as they happen. Starting the live view takes one more full snapshot, which the stored recording gets too (one per start and reconnect; [Storage](https://packstub.dev/docs/session-replay/storage#assist) has the sizes).
- **Questions.** Audio (or video, where Holler allows it), remote control, typing into masked fields and screen share are each asked for separately; a question left for 30 seconds counts as no. A question takes the focus to its card, never to Allow, and its buttons take a press only half a second after it shows, so a visitor typing on the page cannot answer it by accident with Enter or Space; screen readers announce it (`alertdialog`). One question of a kind is up at a time (the agent asking again while it is up changes nothing), and after a no the agent cannot ask the same for 10 seconds: the stage says the visitor said no a moment ago. Audio, video and the Accept of an offer are remembered in the tab for the request and its agent, so a reload does not ask again; another agent on the same request (after a claim lapsed) asks again. Remote control, once allowed, goes on across pages (below). Every answer, and every revocation, goes to the request's grants log (also the screen share the agent stops).
- **Remote control.** The same cursor now acts (one cursor, never two), and a dashed outline frames the page while the agent has control. Clicks, scrolls, drags and typing are synthetic events, so what needs a real gesture of the visitor's (a popup, a file picker, the clipboard, fullscreen) is refused by the browser, and the package does not work around it. A password field is never filled, also one a show-password button turned into plain text (rrweb's `data-rr-is-password`, or `autocomplete="current-password"` / `"new-password"`). Nothing the agent cannot see is acted on: an element outside the visitor's viewport or hidden by CSS, or inside `data-replay-skip`, `privacy.block_selector` or rrweb's `.rr-block` (those also count as masked for typing). Typing into a field: with the default `privacy.mask_all_inputs`, every field is masked for the agent, so remote typing needs `assist.control_masked` on and the visitor's yes to its own question ("type into fields hidden from them"); otherwise clicks, scrolling and drags work and typing is refused (`masked`). Turning `privacy.mask_all_inputs` off makes ordinary fields visible and typeable without that question, for every recording, so weigh it as a privacy setting. `data-replay-unmask` does not help here: it keeps text readable under `privacy.mask_all_text` and never touches input values. The visitor always wins: their own mouse or keys pause the agent for a second, Escape or "End remote control" takes control back, and control ends when the tab is hidden and when the connection drops.
- **Control across pages.** A flow that spans pages (a checkout, settings, finding something in an account) takes one Allow: control lasts for the request in the same tab, across the site's pages (a link, a form and its redirect, a reload, `wire:navigate`), until the visitor or the agent ends it. It adds nothing the agent could not do already: on the first page they could click any link. Every rule above holds on every page, and the masked-typing yes goes along with control and ends with it. On each new page the outline is back at once with "Ana still controls this page. Press Escape to stop.", and nothing the agent sends is acted on until the agent's mirror has that page: control messages during the load are dropped, never queued, and the stage waits for the new page's snapshot to play. Control ends instead on a page the app does not record or another site (the next page must be reached straight from the one that had control: its referrer, or a reload of the same URL; a `Referrer-Policy` that strips same-origin referrers, the back and forward buttons and a page more than 30 seconds later end it too), on a hidden tab, on an identity change (which ends the request) and when the live connection is not back within 30 seconds. The grants log keeps one control period across the pages. `assist.control_across_pages` off brings back one Allow per page.
- **Annotations.** The agent's strokes are drawn over the page and fade after about four seconds. No question: they change nothing. They never cover a question.
- **Audio.** Once the visitor allows the microphone, the call bar in the panel has Mute and End. The agent is heard only after that answer. A microphone the visitor muted stays muted until their own Unmute (also across a reload): the agent asking again, with audio remembered for the request, never unmutes it. When the agent ends the audio, it comes back only after a new question and the visitor's Allow.
- **Screen share.** The browser's own picker follows the visitor's yes. The panel says "Ana sees your screen" while it runs.

### What the agent never sees

The panel, the questions, the agent's cursor and the strokes are left out of the recording entirely: they sit in an element carrying `data-replay-skip` (a closed shadow root inside it), which the recorder drops with everything inside it. Use the attribute for your own elements too; it must be on the element when it is inserted.

Names are text and an avatar is shown only for an `http(s)` URL. The visitor's UI needs no CSS framework: it brings its own small stylesheet, follows the system's light or dark mode, and its strings come in the five languages of the package (`session-replay::recorder.assist.*`).

### The channel protocol

One ordered data channel labelled `assist` per call, JSON messages `{ t, ... }`, implemented in `resources/js/lib/assist-protocol.js` for both sides. Each side opens with `{ t: 'hello', v: 1, role, can }`; a side on another major version stops. `can` lists the optional message types a side takes on top of version 1's own (today `point`, from the visitor's page); the other side sends one only when it was named. An unknown `t` counts as a bad message, so this is how a type is added without a new major version: a visitor's page still on an older build names nothing and is sent nothing new. A message above 64 KB goes as `{ t: 'part', id, i, n, d }` pieces; a sender waits for the channel's buffer to drain and drops queued pointer samples first. Every message is checked against the sender's schema (known `t`, finite coordinates inside the visitor's viewport, node ids the visitor's page knows, values under 4 KB); too many bad messages close the channel. Control messages count only while control is granted; annotations and the pointer need no control, and are not drawn while a question is up. `point` is sent at most about 30 times a second and is the first thing dropped when the channel falls behind, like the mirror's own pointer samples.

The agent's stage bounds what one channel may cost it: at most 1000 stylesheets and 32 MB of stylesheet text (`MAX_LIVE_CSS_KEYS`, `MAX_LIVE_CSS_CHARS` in `lib/assist-stage.js`; past either, a new sheet is dropped and its events show an empty one), and a byte budget for everything the visitor's page sends, 4 MB a second with bursts up to 48 MB for a large snapshot (`AGENT_RATE` in `lib/assist-protocol.js`). A page past the budget is let go (the channel closes with `too_fast`, the stage says so).

| From | Messages |
| --- | --- |
| visitor | `rr` (`e`: one rrweb event), `css` (`key`, `text`: a stylesheet the events point at as `/*sr-live:<key>*/`, sent once per channel), `state` (`hidden`, `url`, `width`, `height`), `control.granted`, `control.released` (`reason`), `control.refused` (`reason`: `password`, `masked`, `blocked`, `not_visible`, `readonly`, `unsupported`, `own_ui`, `declined`, `cooldown`…), `media.granted` / `media.refused` / `media.stopped` (`kind`; refused also `reason`: `declined`, `cooldown`), `screen.granted` / `screen.refused` (`reason`) / `screen.stopped`, `bye` |
| agent | `point` (`x`, `y` in the visitor's viewport pixels: the agent's pointer while they only watch) / `point.hide`, both only to a page whose hello has `can: ['point']`; `control.request`, `control.release`, `move` / `click` / `drag.start` / `drag` (`x`, `y` in the visitor's viewport pixels), `drag.stop`, `scroll` (`dx`, `dy`, under the cursor), `focus` (`id`, an rrweb node id), `input` / `select` (`id`, `value`), `annot.start` / `annot.move` (`x`, `y`), `annot.stop`, `media.request` / `media.stop` (`kind`: `audio`, `video`), `screen.request`, `screen.stop`, `bye` |

Attach the endpoint in the call's `datachannel` event, synchronously, so the other side's hello is not missed.

## The agent's side, in the built-in viewer

Everything below sits behind the viewer's middleware and the `viewSessionReplay` gate, asks `visibleUsing()` and `canAssist` again on every request, and posts with the CSRF token. The Filament package brings the same into a panel.

### Live recordings and Offer help

The recordings list has a **Live now** tab: recordings with an upload or a heartbeat in the last two minutes (`ReplaySession::live()`, the window `isLive()` uses). Live is a window, not a promise, so every live row says when the page was last heard from: "last seen 40 s ago". A visible tab sends a heartbeat every `assist.heartbeat_seconds` (15), a hidden one sends nothing, so a page someone left open in the background looks older and older until it drops out.

With Holler installed, a live row (and a live recording's page) has **Offer help**, the propose route as a form. It leads to the stage, where the agent waits for the visitor's Accept. A recording with a request going shows that instead (the agent's own: **Open live view**), and nobody is offered their own visit.

### The Requests page

`/session-replay/assist` (linked from the recordings list while Assist is on) lists the requests that wait and your own: the person, their message (shown as text), the page, how long they have waited, whether the page is still polling, and Claim, Withdraw and End buttons. **Claim** leads to the stage when Holler is installed (without it, back to the list: the request is a queue entry your app answers its own way). Your own requests that are going have **Open live view**.

### The live stage

`/session-replay/assist/requests/{id}/stage`, for the agent who holds the request (claimed, offered or live); anyone else gets a 403, a request that is over sends you back to the list.

- **The status line** says what is happening in words: waiting for the visitor to accept, waiting for their page to pick up, connecting, live, live with the visitor's tab hidden (the page waits until they come back), on hold, reconnecting (also when the agent comes back after leaving the live view and the new call is on its way), over and why. It polls the request's status route every two seconds and stops everything once the request ends, whoever ended it, or once it is no longer yours (`mine` false: let go of, or taken by someone else). Who holds a request is the same person by key, model type and guard: Admin #12 is not User #12.
- **The mirror.** The visitor's page replayed live by rrweb's `Replayer` (no player controls), in rrweb's sandboxed iframe without scripts: the same masked events the recording stores, so a masked field shows asterisks and a blocked element an empty box. It plays about 300 ms behind the visitor, with the visitor's clock lined up with the agent's on the first event. A reconnect (either side reloads) starts from a fresh snapshot. Text typed into a field shows when the visitor leaves the field, like in the recording (`size.sampling.input` is `last`; set it to `all` to see every keystroke, live and stored).
- **Show my pointer** (on by default): while you watch, your pointer over the page view is drawn on the visitor's page as your named cursor, so "the button up here" needs no drawing and no control. It is not sent while you have control (your cursor is then the control cursor), on their screen share or while their tab is hidden. A page still on a build from before the pointer cannot show it: the button is then disabled and says so, until they reload. Turn it off to look around unseen.
- **Request control** asks the visitor (logged in the grants log as asked). Once allowed, the stage gets a dashed frame and the pointer drives the visitor's page: click, drag, the wheel and the arrow and page keys scroll. A click on a field opens a small box over it for typing (Enter sends, Escape closes); the visitor sees each change. Their page refuses a password field always, a masked field unless `assist.control_masked` and their own yes, and says so; the stage shows the reason. With `assist.control_masked`, a click on a masked field puts the question to the visitor and the box waits, read-only, saying so; their yes opens it for typing, and a no, a question left unanswered or a no a moment ago each say which it was. The visitor's own press on Allow never pauses the agent, and typing that comes while the visitor's mouse or keys pause the agent is applied, with its latest value, once the pause is over. **Release control** gives it back; the visitor may take it back any time (Escape), and control ends when their tab is hidden and on a reconnect. When the visitor's page goes to the next one, control goes on there (the notes say "Control went on to the visitor's next page") once its mirror is in; on a page that is not recorded the notes say control ended. With `assist.control_across_pages` off it ends on every navigation.
- **Draw** turns the pointer into a pen: strokes show on the stage and on the visitor's page and fade after a few seconds. No question asked, nothing on the page changes.
- **Start audio** asks the visitor for their microphone; once they allow it, the agent's own microphone joins and a small audio bar has Mute and End audio. **Start video** is there while Holler's `video` setting allows it.
- **Their screen** asks the visitor to share their screen (the browser's own picker follows their yes); while they share, the stage shows it as video and the view switch goes between their page and their screen. Control and drawing work on the page view only. **Share my screen** shares the agent's.
- **Put on hold** (with Holler's hold routes) steps out of the call without ending the assist, to ring a colleague from the Holler widget, say; **Resume** comes back. See [On hold](#on-hold).
- **End assist** ends the request and the call; **Withdraw** takes an offer back or lets go of a claim.
- Every button that cannot be used now is disabled with the reason under it (the live view is still connecting, the visitor's tab is hidden, the visitor has not answered yet, only on the page view, video is off). What the visitor answered, refused or took back is listed under **What happened**.

The stage runs its own Holler client as the agent (`kind=assist` polls, so it never touches the Holler widget's calls, and the Holler widget never touches it) over **Holler's own routes**. In a plain Laravel app register them, in `routes/web.php` so they get the `web` middleware:

```php
use Packstub\Holler\Facades\Holler;

Holler::routes();
```

With another name prefix (`Holler::routes(as: 'support.calls.')`), set `session-replay.assist.calls_routes` to it. The stage polls Holler during the call as often as Holler's own `poll.active` says (`HOLLER_POLL_ACTIVE`, 1000 ms; kept between 250 ms and 4000 ms, a second under the 5 seconds Holler keeps a window's claim on its side of a call, `Call::CLAIM_SECONDS`, so the agent's side is never free between two polls). Without the routes the stage says so instead of trying to connect. Holler's guard must be the viewer's (see [With Holler](#with-holler)).

`stage.js` and `stage.css` come from the package's script route, like the player (about 260 KB: rrweb's replayer and the calls engine), only on the stage page.

### Leaving the live view

An agent may leave the stage in the middle of an assist: follow a link, reload, lose the network for a moment. The request stays theirs.

- **Back within `holler.reconnect_timeout`** (15 s): the stage picks up the same call, with a fresh snapshot.
- **Away for longer:** Holler drops the agent's side and the call ends, but the request does not. It goes back to `claimed`, without a call, and the visitor's page says "Ana stepped away and is reconnecting…" (End still works). When the agent opens the stage again, its status poll tells the server they are there, and the visitor's next poll puts both on a new call: live again, from a fresh snapshot. Remote control and screen share are asked again; audio and video allowed before are remembered for the same agent. If the agent does not come back within `claim_timeout_seconds`, a visitor's request goes back to the list and an agent's offer ends (`agent_left`); either way, the server writes a revocation (`by: server`) in the grants log for everything the visitor still had on, so the log and the marker's durations stop when the agent left, and the next agent asks again. `AssistStarted` is not sent again, and `max_duration_minutes` still counts from the first start.
- **Not back within `assist.claim_timeout_seconds`** (30) after the drop: the claim lapses and the request is back in the list, waiting, like a claim the page never picked up.

When it is the visitor's page that goes away for longer than Holler waits, the assist ends (`dropped`), as before.

### On hold

Holler lets someone put a call on hold: they step out of it without leaving, and come back with Resume. Assist goes along with it rather than around it.

- **From the stage.** Put on hold closes the agent's side of the connection; the request stays live and the call stays the same one. The stage says "On hold", the visitor's page says "Ana put this session on hold and will be right back" (End still works), and nothing is mirrored, heard or controlled meanwhile. Resume connects again from a fresh snapshot, as after a reload: remote control and screen share are asked again, audio and video allowed before come back without a question.
- **With a call in the Holler widget.** A call the agent put on hold in the widget before claiming waits for them through the assist (a call they are still *in* is left when the assist starts, as before). Resuming it during the assist is Holler's swap: the assist goes on hold in its place and the stage shows it; Resume on the stage swaps back. One call on hold per person is Holler's rule, so Put on hold is refused while a widget call is already on hold.
- **The widget never sees the assist**, on hold or not: it polls for `kind=call`, the stage for `kind=assist`, and each is told only about calls of its kind.
- **A hold lasts while the live view is open.** Holler keeps a call on hold for as long as any window of that person polls, which a panel tab left open would do for good. So an agent whose stage has not polled the request's status for Holler's `hold_timeout` (`HOLLER_HOLD_TIMEOUT`, 120 seconds; never less than `reconnect_timeout`) while the assist is on hold has left the live view: their side is withdrawn, and the request goes back to `claimed` exactly as in [Leaving the live view](#leaving-the-live-view) (a new call when they come back, the list for someone else after `claim_timeout_seconds`). That is longer than the 15 seconds a dropped side gets, on purpose: the agent stepped away, and a browser may slow or freeze a hidden tab for a while (the stage polls on a Web Worker timer, which most throttling leaves alone). With `hold_timeout` at 0, Holler's "for good", only `assist.max_duration_minutes` ends a hold; it counts through one either way.
- **One assist at a time, unless the other is on hold.** Starting a call takes the agent out of every call they are in, so an agent who is live on one assist cannot claim or offer another (409, `busy`: "You are in another assist. Put it on hold or end it first."). The same holds for a request that comes back for a new call while they are live elsewhere (its hold lapsed and they opened its live view again): no call is made, the stage says why (`blocked: other_assist` in the status), and it starts on the visitor's next poll once the other assist is on hold or over. Until then it waits like any claim, for `claim_timeout_seconds`.
- **Not to be confused with a window's claim.** What a window does to keep its side of a call (the visitor's page and the stage both do, on every poll) is a *claim* in Holler, kept for 5 seconds after the window's last poll. The poll ceilings above come from that, not from the hold.

### Hosting the stage in a page of your own

The Filament package puts the stage in a panel page with the panel's own buttons; any page can do the same. The script mounts on every `[data-session-replay-stage]` element and reads its `data-config` (the JSON the built-in view writes: the request as the agent sees it, the agent routes, Holler's routes, `video`, `csrf` and the strings). Inside that element it only looks for attributes, so the markup is yours:

- `data-ref`: `status`, `seen`, `screen`, `mirror`, `video`, `ink`, `overlay`, `placeholder`, `editor`, `editor-text`, `editor-select`, `notes`, `url`, `audiobar`, `audio`, `face`, `mute`, `end-audio` (see `resources/views/viewer/stage.blade.php` for what each is).
- `data-action` on the buttons: `mirror`, `screen`, `control`, `draw`, `pointer`, `audio`, `video`, `share`, `hold`, `withdraw`, `end`. `pointer` and `hold` are optional: without a `pointer` button the pointer is simply on, without a `hold` button the assist can still go on hold through the Holler widget's swap, and the status line says so. The script sets `disabled`, `hidden` and `aria-pressed` on them and their label: into the button's `[data-label]` element when it has one (so an icon beside the text stays), else the whole button.
- `data-why="<action>"`: where the reason a button is disabled goes.
- Send the mirror's policy with the page: `app(\Packstub\SessionReplay\Support\Assist::class)->mirrorPolicy()` as its `Content-Security-Policy` header (null when `assist.mirror_sources` is `*`). See [Privacy](#privacy).

After every change the root dispatches `session-replay:stage` with the state in `event.detail` (`phase`: `waiting`, `connecting`, `live`, `hidden`, `on_hold`, `reconnecting` (also while a new call is on its way after the agent left), `ended` or `unavailable`; `request`, `call`, `connected`, `control`, `audio`, `video`, `screen`, `mode`, `drawing`, `pointing`, `held`, `events`, `finished`), for a status badge of your own. `root.sessionReplayStage.state` reads the same at any time.

In an app that navigates with `wire:navigate`, the stage leaves the call on `livewire:navigating`, as a page unload does (the request stays the agent's; reopening the stage picks it up with a fresh snapshot, or a new call after a longer absence, see [Leaving the live view](#leaving-the-live-view)), and mounts any stage on the new page on `livewire:navigated`. It is not meant to be kept with `@persist`: a frame moved in the page reloads, which blanks the mirror.

### Measured

On the package's workbenches, 2026-10-28:

- **The extra snapshot** at each live-view start and reconnect: 37 KB stored (gzip; 650 KB before compression) on a Filament panel's 50-row table page, 1.2 KB on a small Blade page. [Storage](https://packstub.dev/docs/session-replay/storage#assist) has the table.
- **A visitor's tab in the background for ten minutes.** Google Chrome 156 on macOS, a real window with a second tab brought to the front, so the visitor's tab was `hidden` the whole time (no automation focus emulation, Chrome's own background throttling on). The page held its side of the call all along: it polled every 2 seconds (median 2.04 s, longest gap 3.0 s, 305 polls), Holler never dropped it, the agent's stage stayed connected and showed "the visitor's tab is hidden", and when the tab came back to the front a click on it reached the agent's mirror within a few seconds, with no reconnect. Two things keep it so: the poll timer runs in a Web Worker, which Chrome does not slow down like a hidden page's own timers, and Chrome leaves pages with an open WebRTC connection out of its intensive throttling.

## Events

| Event | When |
| --- | --- |
| `AssistRequested` | a visitor asked (`$request->opened_by === 'visitor'`) or an agent offered help (`'agent'`) |
| `AssistClaimed` | an agent took a visitor's request (`$request->agent_id`, `agent_name`) |
| `AssistStarted` | the call exists (`$request->call_id`); once per assist, not again for the new call after the agent left the live view |
| `AssistEnded` | every finish: `$request->status`, `end_reason`, and `grants`, the log of what the visitor allowed |

Each carries the `AssistRequest` as `$event->request`.

## The visitor's routes

Stateless, like the upload endpoints: no session, cookie or CSRF token, throttled by `ingest.requests_per_minute` per person (for guests: per rendered page), on the same key as the uploads. With Assist on, a visible tab adds a heartbeat about 4 times a minute; a tab with a request going polls every 3 seconds while it waits and every 2 seconds during an assist (about 30 a minute, plus a burst of WebRTC signals when the call starts). The default of 240 a minute has room for that next to the uploads (about 12 a minute); if you lowered it, leave that room, and on cached guest pages, where every visitor shares one key, raise it.

- A request is created with the recording's triple: `token` (the signed token the page was rendered with), `session` (the recording's id) and `key` (its write key). Only the browser that makes the recording can attach a request to it. A tab that records nothing sends the token alone.
- The answer carries a **secret** once: 32 hex characters, stored as its SHA-256 and compared in constant time. Every later call presents `secret` and `token`. The token keeps the throttle and lets the server refuse one that expired, belongs to another workspace, or now names someone else, which ends the request (`identity_changed`).
- An unknown id and a wrong secret get the same answer.
- Every visitor route is a `POST` and reads the token, the write key and the secret from the body only (JSON or a form), never from the query string: a URL ends up in access logs, proxies and error trackers. The upload endpoints read the token and the key the same way.

| Method | Route | Does |
| --- | --- | --- |
| `POST` | `assist/requests` `{token, session?, key?, message?, url?, tab?}` | create; 201 with `secret`, or 200 and `secret: null` for the request that is going (`tab`, the tab's own id, keeps one per tab without a recording); 403 `guests` or `no_recording` for a guest Assist does not take; 429 past `requests_per_hour`, `max_open_requests` or `guest_requests_per_hour` |
| `POST` | `assist/requests/{id}` `{secret, token, after, tab, claim}` | the poll: `visitor_seen_at`, the timeouts, the call created on acknowledgement, and Holler's poll for the guest once a call exists. With `session` and `key` of the tab's new recording, the request moves to it (same person, same workspace). |
| `POST` | `assist/requests/{id}` `{token, session, key}` | the first answer to an agent's offer, with the triple instead of a secret: the secret is issued in it, once (409 after) |
| `POST` | `assist/requests/{id}/accept` `{secret, token, tab}` | yes to an offer (or, with `watch_consent`, to the agent who claimed); creates the call |
| `POST` | `assist/requests/{id}/decline` | "Not now" on an offer |
| `POST` | `assist/requests/{id}/cancel` | stop waiting |
| `POST` | `assist/requests/{id}/hangup` | end a live assist |
| `POST` | `assist/requests/{id}/leave` `{tab}` | the unload beacon: the guest's side of the call is free for the tab's next page |
| `POST` | `assist/requests/{id}/signals` `{type, payload, to?}` | a WebRTC signal as the guest (`offer`, `answer`, `ice`, `reset`, `state`), capped at Holler's `max_signal_kb`; never trimmed |
| `POST` | `assist/requests/{id}/grants` `{kind, granted}` | the visitor's browser reports a grant or its revocation (`watch`, `control`, `audio`, `video`, `screen`, `control_masked`), added to the log with a timestamp |
| `POST` | `assist/heartbeat` `{token, session, key}` | a visible tab's sign of life: the request and the live list see it; answers `{assist: {id, agent} \| null}`, an agent's offer for the recording |

The upload endpoint's answer carries the same `assist` key while Assist is on, for the recording the batch was accepted for.

A poll answers:

```json
{
    "id": "5f0c…",
    "status": "active",
    "opened_by": "visitor",
    "agent": { "id": "12", "name": "Ana", "avatar": null },
    "consent": null,
    "reconnecting": false,
    "end_reason": null,
    "call": { "id": 41, "kind": "assist", "status": "active", "peer": { "id": "12", "name": "Ana", "avatar": null } },
    "signals": [],
    "cursor": 0
}
```

`call`, `signals` and `cursor` are Holler's poll as the guest (`guest:<request id>`, also for a signed-in visitor); a page checks that `call.peer.id` equals `agent.id` before it connects. `consent` is `"watch"` while the visitor's Accept is what moves the request on; `reconnecting` is true while the agent left the live view and the page waits for them. Nothing in it names anyone but the agent.

## The agent's routes

Behind `viewer.middleware` and the `viewSessionReplay` gate; every request-bound route asks `visibleUsing()` and `canAssist` again. JSON for a client of your own; the Requests page posts forms. They stay registered while `viewer.enabled` is off (a stage hosted elsewhere, such as the Filament package's, polls `status` and posts `asks`, `end` and `withdraw`), outside any panel: in an app with several workspaces, register `tenantUsing()` or `canAssistUsing()` so these routes know which workspace an agent works in ([Several workspaces](#several-workspaces)).

| Method | Route | Does |
| --- | --- | --- |
| `GET` | `assist/queue` | `{requests: [...]}`: the open and claimed requests you may see, and your own live ones |
| `GET` | `assist/requests/{id}/status` | one request; also marks you as seen while you hold it |
| `POST` | `assist/requests/{id}/claim` | take a visitor's request; 409 with `holder` when someone was faster |
| `POST` | `assist/sessions/{session}/propose` | offer help to the person making a live recording; 409 with `holder` when the recording has a request going, 422 when it is not live (no upload for two minutes) |
| `POST` | `assist/requests/{id}/withdraw` | take your offer back (it ends, `withdrawn`), or let go of your claim (it goes back to the list) |
| `POST` | `assist/requests/{id}/asks` `{what}` | log that you asked the visitor for `control`, `audio`, `video`, `screen` or `control_masked`, so the grants log shows what was asked next to what was allowed |
| `POST` | `assist/requests/{id}/end` | end it (and the call) |

A request as the agent sees it: `id`, `status`, `opened_by`, `session`, `session_url`, `user` (`id`, `label`), `message`, `page_url`, `agent` (`id`, `name`), `mine`, `call`, `reconnecting`, `visitor_here`, `visitor_seen_ago`, `waiting` (seconds), `grants`, `claimed_at`, `started_at`, `ended_at`, `end_reason`, `created_at`. Refusals are `{message, reason}`, `reason` one of `taken`, `exists`, `not_allowed`, `guard_mismatch`, `connection_mismatch`, `not_live`, `declined_recently`, `no_calls`, `state`.

## Privacy

- Nothing of the live view is stored beyond the recording that exists anyway, plus one full snapshot per live-view start and reconnect. Audio, video and screen share are never stored. The mirror and the media go peer to peer, encrypted by WebRTC; a TURN relay forwards ciphertext. ICE candidates show each side's addresses to the other; `holler.ice_transport_policy` `relay` hides them behind your TURN server.
- The mirror is rebuilt from what the visitor's browser sends, so a visitor could point it at a URL of their choosing (an image, a `url()` in a stylesheet) and learn the agent's address from the agent's browser fetching it. The stage page sends a `Content-Security-Policy` that lets images, styles, fonts, media and frames load only from the app (its own origin, `app.url`, `app.asset_url`) and `assist.mirror_sources`; scripts and connections stay with your app's own policy. If your pages load assets from a CDN or a font service, add those origins to `assist.mirror_sources` (`SESSION_REPLAY_ASSIST_MIRROR_SOURCES`, comma-separated), or the mirror shows them missing; `*` sends no policy. A `<link>` that is not a stylesheet (preconnect, dns-prefetch, preload, prefetch) loses its `rel` in the mirror, since those reach a host past the policy.
- The visitor's routes take no identity but the signed token and the request's secret; the agent sees the page's URL with `privacy.redact_query` applied, and the message as text.
- No credential is read from a URL: the token, the write key and the secret come from the request body on every visitor route (the leave beacon sends a form body), and the rate limiter reads the token from the body too. Nothing in the package logs them.
- The grants log is the compliance trail: what the agent asked for (`{kind, asked: true, by: "agent", at}`) and what the visitor allowed or took back (`{kind, granted, by: "visitor", at}`), and when. `AssistEnded` carries it; the `assist` marker summarises what was allowed on the recording.
- Holler deletes a call's signals when it ends; the package never logs a session description or a candidate.
- A request is deleted with its recording by `session-replay:prune`; one that never had a recording, after `retention.days`.

### GDPR and your privacy notice

This is how the package behaves, not legal advice; your privacy team or DPO has the last word.

- **The lawful basis is yours.** Your app is the controller and decides why live help happens. For most apps it is support the person asked for under their contract (Art. 6(1)(b)) or your legitimate interest in helping them (Art. 6(1)(f)). The visitor's yes to each step (the offer, control, audio, video, screen) is how the package keeps them in charge of what the agent may do; it is not meant as the legal basis on its own.
- **What leaves the browser, and to whom.** To your server: the request (the message, the page URL with `privacy.redact_query` applied, the recording's id) and, for the call, the WebRTC signals (session descriptions and ICE candidates, which include IP addresses) in Holler's tables, deleted when the call ends. To the agent's browser, peer to peer and encrypted: the recorder's events, masked as in the recording, and audio, video or the screen only after the visitor allowed each. Through a TURN server when one is set (`holler.ice_servers`): the same, still encrypted. A STUN server (Holler's default is a public one) sees each side's IP address while the connection is set up; list your own to keep that in house. Nothing goes to Packstub.
- **What is kept.** The recording that exists anyway, one extra full snapshot per live-view start and reconnect, the request row (who, when, the message, the outcome) and its grants log, all deleted with the recording (`retention.days`). The `assist` marker on the recording says what was allowed and for how long, never who the agent was.
- **The grants log** is your record of consent to each step: what the agent asked for, what the visitor allowed or took back, with timestamps. `AssistEnded` hands it to your app if you keep an audit trail elsewhere.
- **Wording for the visitor.** The questions on the page already say what each step does ("Ana would like to control this page: click, scroll and type for you. You can stop it at any time with Escape."). For your privacy notice, something like: "When you ask for help, or accept our offer of help, a support agent can see the page you are on as you use it, with form fields hidden. They can only control the page, talk with you or see your screen after you allow it, and you can stop at any time. We keep a note of what you allowed, with the session recording, for N days."

## Configuration

| Key | Default | Meaning |
| --- | --- | --- |
| `assist.enabled` | `false` (`SESSION_REPLAY_ASSIST`) | The routes, the Requests page and the knock in the upload answer. |
| `assist.calls` | `true` | Use `packstub/holler` when it is installed. `false` keeps the queue alone. |
| `assist.watch_consent` | `false` | The visitor accepts before the agent joins, also for a request they opened. Accepting an offer always counts. |
| `assist.requests_per_hour` | `6` | New requests per person per hour (guests: per rendered page); `null` turns it off. |
| `assist.max_open_requests` | `100` | Requests going at once per workspace (no workspace counts as one); past it, 429. `null` turns it off. |
| `assist.guests` | `true` (`SESSION_REPLAY_ASSIST_GUESTS`) | Guests (recorded with `session-replay.guests`) may ask. `false`: signed-in people only. |
| `assist.guest_requests_per_hour` | `20` | New requests per hour from all guests of a workspace together; while set, a guest asks only from a recording with events. `null` turns both off. |
| `assist.claim_timeout_seconds` | `30` | A claim the page has not acknowledged goes back to the list; so does the claim of an agent who left the live view and has not come back this long after Holler dropped them. |
| `assist.proposal_timeout_seconds` | `60` | An offer nobody answered expires. |
| `assist.decline_cooldown_seconds` | `300` | After "Not now", nobody may offer help on that recording, or another recording of the same signed-in person, for this long (`declined_recently`, 429); `0` turns it off. |
| `assist.visitor_timeout_seconds` | `60` | A request whose page stopped polling expires; a live one ends. |
| `assist.max_duration_minutes` | `120` | An assist ends after this long, counted from its first start. |
| `assist.button` | `false` (`SESSION_REPLAY_ASSIST_BUTTON`) | A floating "Get help" button on every recorded page. |
| `assist.control_masked` | `false` (`SESSION_REPLAY_ASSIST_CONTROL_MASKED`) | Let the agent type into fields they see masked, after a separate question. Password fields never. |
| `assist.control_across_pages` | `true` (`SESSION_REPLAY_ASSIST_CONTROL_ACROSS_PAGES`) | Remote control lasts across the tab's pages of the site, until either side ends it. Off: one Allow per page. |
| `assist.heartbeat_seconds` | `15` | A visible tab's sign of life, which also brings an agent's offer. |
| `assist.poll.waiting_ms` | `3000` | How often a waiting page polls its request. |
| `assist.poll.active_ms` | `2000` | How often it polls during an assist (the call's heartbeat; kept between 500 and 4000, a second under the 5 seconds Holler keeps a window's claim on its side of the call). |
| `assist.calls_routes` | `holler.` | The name prefix of Holler's routes (`Holler::routes(as: …)`), which the agent's live stage polls. |
| `assist.mirror_sources` | `[]` (`SESSION_REPLAY_ASSIST_MIRROR_SOURCES`) | More origins the live mirror may load images, styles, fonts and media from, besides the app's own; `*` sends no policy. |
