Browser task lifecycle and controls

Start through a confirmed conversation

Describe the task through the account chat route. The workflow can collect criteria, resolve a destination and request a readback before dispatch.

Confirm the actual task and restrictions. An informational answer, action offer or criteria prompt does not establish that browser work started.

Account browser tasks are broader than embedded viewer research. Supported site actions still depend on policy, current page evidence and the user’s confirmed request.

Browser dispatch endpoints used by workers are internal. A custom client starts through the owned conversation, not an operator browser-run command.

Chat request and confirmation events

Track durable state separately from frames

flowchart TD
  A[Confirmed task] --> B[Durable start command]
  B --> C[Leased browser execution]
  C --> D{User decision required?}
  D -->|Yes| E[Persist checkpoint and current question]
  E --> F["Pause; lease retention depends on runtime"]
  F --> G[Authenticated raw reply with current point ID]
  G --> H[Durable control acknowledgment]
  H --> I[Resume from retained session or checkpoint]
  I --> C
  D -->|No| J[Record terminal outcome]
  J --> K[Project completed, failed or cancelled state]
  K --> L[Release browser handle]

Screenshots, cursor images and live frames are presentation signals. They are not durable checkpoints or proof that a proposed action succeeded.

A terminal browser outcome and its workflow projection are distinct steps. Projection retries do not require rerunning the browser task.

Connect and replay the account stream

The account client connects to /ws/agent-stream on the backend host. This socket path does not include the /v1/ HTTP prefix.

function connectAccountTask({ accessToken, sessionId, lastCursor = 0 }) {
  const url = new URL('wss://api.rapideye.ai/ws/agent-stream');
  url.searchParams.set('token', accessToken);
  url.searchParams.set('session_id', sessionId);
  if (lastCursor > 0) url.searchParams.set('last_sequence', String(lastCursor));
  return new WebSocket(url.toString());
}

The browser WebSocket API does not add an arbitrary Authorization header. This example follows the current account query-token protocol.

Never log or share the constructed URL. Treat it as credential-bearing. Resolve fresh credentials before reconnecting.

Embedded viewer sockets use the separate rapideye.viewer.v1 subprotocol and viewer token. Do not send an account token through an embed viewer channel.

Replay uses the global cursor within the conversation. Per-workflow sequence starts again for another workflow and cannot identify session-wide replay progress.

Deduplicate durable events across HTTP and socket delivery. Apply the current conversation’s events only; do not merge frames from another session.

Apply the current raw user reply

Read the active critical_point_id from the browser decision. Send the user’s exact reply with that point and the same owned session.

function replyToDecision(socket, { sessionId, criticalPointId, response }) {
  if (socket.readyState !== WebSocket.OPEN) return false;
  if (!criticalPointId) return false;
  socket.send('critical_point_response:' + JSON.stringify({
    session_id: sessionId,
    critical_point_id: criticalPointId,
    response
  }));
  return true; // Sent locally; acknowledgment and completion are still pending.
}

Do not trim away restrictions, paraphrase a reply or substitute an old prompt ID. A stale point cannot authorize a new decision.

Email consent has its own email_consent_response message with consent, session_id and critical_point_id. Follow the actual consent prompt instead of guessing authorization.

Private sign-in replies require the application’s Continue after sign-in control. Do not send credentials or arbitrary text as that acknowledgment.

Resume from checkpoints and retained sessions

The durable lifecycle can release a worker lease while a user decision waits. A bounded remote browser session can remain available for continuation.

A fresh worker can reconnect and apply the committed control. If the remote session is lost, recovery uses the latest semantic checkpoint.

A semantic checkpoint restores task state and decisions. It does not recreate every DOM detail or permit an irreversible action without fresh confirmation.

Corrections belong to the ordinary chat route. The workflow must preserve the original task restrictions while resolving changed criteria or replacement requests.

A recheck of a completed task can compare current options with previous results. Previous availability, prices and selections do not guarantee current availability.

Cross-worker recovery is part of the durable design. The earlier bounded embed acceptance used one worker for start and reply; it does not prove every production topology.

Handle sensitive actions and conditional sign-in

The sign-in handoff can require reopening the current login window if the remote session changed. Continue only through the current task’s provided control.

Locked-page ask-and-wait behavior is a constrained task mode. It is not a universal public ask_viewer tool or permission to request private information.

A link, prefilled search or handoff is not proof of a completed purchase or reservation. Inspect the final task outcome and finish any required external action yourself.

Embedded viewers have no saved account browser profile or private sign-in handoff. Their published browser capability remains separately scoped to read-only research.

Embedded viewer scope

Cancel explicitly

Use Stop to cancel the current task. The account client sends cancel_agent on the active socket and has an authenticated HTTP fallback.

The account fallback uses DELETE /api/agent on the application origin with the owned session_id and authenticated application cookies.

async function cancelAccountTask({ sessionId }) {
  const response = await fetch('/api/agent', {
    method: 'DELETE',
    credentials: 'same-origin',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ session_id: sessionId })
  });
  return { status: response.status, payload: await response.json() };
}

The application route derives the downstream bearer token from the validated cookie session. Direct backend DELETE /v1/agent/cancel/ requires a fresh user bearer token and verifies session authorization.

A 404 can mean no unfinished workflow remains. A timeout or connection failure does not establish cancellation; inspect the current task state.

Hiding a panel, leaving the page, destroying an embed controller or disconnecting a socket does not cancel browser work.

Completion, failure and cancellation request browser cleanup. Provider timeout bounds can still apply if release fails.

Browser capacity and admission charges