Taking over a job

Taking over a job opens a fresh browser at the point a parked job stopped and streams it to you, so you can finish by hand what the program could not. What you do is recorded and offered back as proposals, so the next run can do it alone.

#When to use it

Some pages need a person: a dialog with no label anyone could recognise, a check that only makes sense to a human, a login that changed overnight. When a job parks on one of those (needs_attention) or is waiting for a value (awaiting_input), take it over.

Try the cheaper answers first: a proposal on the attention card often fixes the job in one click, and a job waiting for a one-time code only needs the code. Take over when neither is enough.

#1. Start a takeover

From the panel, press Take over on the job's card in Attention, or on the job's page. From code:

curl -X POST https://api.kaab.ist/v1/jobs/job_…/takeover \
  -H "Authorization: Bearer sk_live_…"

{ "live_url": "https://app.kaab.ist/live/lv_…?t=…", "token": "…", "expires_in": 900 }

Open live_url in a browser, or hand it to the person who should finish the job. Behind it, Kaabist has already:

1. placed a browser on one of its pods (if none is free within ten seconds you get 503 live_unavailable; try again shortly),
2. restored the job's checkpoint into it: cookies, local storage, the page it was on,
3. checked that the page is where the job stopped. If it is not (a session that aged out, say), the browser goes back to where the session was established and the live view tells you so.

The token is good for 15 minutes; the panel refreshes it for you. A session never outlives an hour, and one nobody is watching ends after about five minutes.

#2. Drive it

The live view is headed Take over, with Open the job beside the title. The page fills the left side, under a toolbar with a Use the page / Inspect switch, back, reload, the address bar and a connection badge. A rail on the right shows, from the top:

• a reminder that what you do here is recorded and becomes a proposal;
• the program, the job and why it parked;
• the step it stopped at, with "Continue once the page shows what the step expects.";
• notices from the obstacle probe, such as "Something covers the page. Close it, then continue.";
• the three buttons of step 3.

The page is the real page: click, type, scroll, open links. Inspect switches to pick mode to look at an element without clicking it. A dialog the page shows is dismissed and reported, and downloads are not available here. Only one viewer at a time: opening the same session elsewhere moves it there, and the first view says "Opened elsewhere". A dropped connection reconnects by itself; Reconnect tries again by hand.

Everything you do is recorded: the elements you clicked, what you typed, where you navigated. Passwords are never recorded: a value typed into a password field is written down as a reference to the program's secret input ({{inputs.password}}), never as the value.

#3. Finish

POST /v1/jobs/{id}/resume with { "continue": true } does the same as Continue the job from here from code.

After Continue, the rail says "The job continues" with a link to follow it, and lists the proposals your takeover produced, each with a Review link.

#4. What it teaches

On Continue your actions become proposals on the program version, never applied by themselves:

• an insert_steps proposal at the step that parked, with the steps you took, each element described by several locators so the next run finds it even if the page shifts a little;
• a dismiss proposal for each dialog you closed by hand, so the obstacle layer can close it next time (approve it with remember: "site").

Review them in the panel's Review queue or through the proposals API.

#Hosted takeovers

A hosted resolve page can offer a takeover to your own end user. Their live view is restricted to the page the job is on: no address bar, no tabs, no session export, and the link lapses with the resolve page.

#Worked example

A shop at https://shop.example.com starts showing a dialog over its product pages that only an unlabelled corner glyph closes, which no heuristic recognises:

1. A program that reads https://shop.example.com/p/1 runs. The job parks needs_attention with the reason obstacle; Attention shows it under "Blocked by something on the page".
2. Press Take over. The live view shows the product page under the dialog, and the rail's notice says something covers the page.
3. Click the corner glyph. The dialog closes, and the price is visible.
4. Press Continue the job from here. The job succeeds, and the rail lists a dismiss proposal for the dialog and an insert_steps proposal with your click.
5. Approve the dismiss proposal in Review with Remember for this site: the next job on that site closes the dialog without parking.

#Pitfalls

• Pressing Continue too early. The job resumes from the page as you left it; if the step's expectation does not hold there, it parks again. Wait until the page shows what the step expects.
• Sharing a live link widely. Anyone with live_url can drive the browser until it expires. Send it to one person.
• Leaving the view open and walking away. A session nobody watches ends after about five minutes, and the job stays parked.
• Expecting the fix to apply by itself. Takeover steps are proposals; approve them, or the next run parks in the same place.

#Reference

• Take over a job, resume a job
• List proposals, approve a proposal
• Attention reasons
• Human-in-the-loop