Skip to content

docs(skills): catch a browser session that dies mid-flow - #12951

Merged
bolichen97 merged 1 commit into
mainfrom
docs/browser-skill-session-expiry
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/browser-skill-session-expiry

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

What changed

Two builtin skill bodies now name the failure that costs the most time in attach
mode, a login that expires while the agent is still working:
src/kiro_crew/builtin_skills/browser-auth/SKILL.md and
src/kiro_crew/builtin_skills/web-browse/SKILL.md.

browser-auth gains a session can die mid-flow section. It says a page still on
screen is not proof the session is alive, because a loaded single-page app keeps
rendering after its cookie expires and only the next request redirects. It gives a
one-request probe instead: open a known gated page in a NEW tab and read the printed
Page URL — the target means live, an identity-provider host means dead. The probe
uses a new tab on purpose, because in attach mode a same-tab navigation would discard
whatever the user had half-entered in the tab being driven. It adds the
symptom that does not look like auth at all, a click timing out on
waiting for element to be visible, enabled and stable with the locator already
resolved, and says to probe and read the console before touching selectors. It closes
with a checkpoint rule for long forms.

The same skill's attach section now carries the token-mismatch error text with both
fixes, and says the extension link is the wrong answer to it. The token workaround is
scoped to the attach command alone, because carrying the env-stripped form forward
in a shell variable is refused by the shell policy floor as credential access.

Both skills now state that attach exposes one tab, the one the extension was
activated on, so tab-list is not a view of the browser and a page the user already
has open needs their click on the extension icon before it can be driven.

Why

Driving a real internal form through attach mode lost about 28 minutes across five
cycles. Two of those cycles chased the wrong cause — a suspected Chrome profile or
headless problem — because nothing told the agent that a visible page proves nothing
and that a stability timeout can be an auth failure.

Backwards compatibility

No behaviour change. Documentation only, in two builtin skill bodies.

Testing

Ran the gates that cover this diff: check_builtin_skill_scope.py,
scripts/docs-lint.sh, check_brand_name.py, check_focus_cue.py,
check_feature_map.py, check_changelog_history.py. All six pass. The rest of the
floor is unrelated to a markdown-only change and is left to CI.

no linked issue: this documents an incident hit while driving attach mode, not a tracked defect report.

@bolichen97
bolichen97 requested review from a team and CrysisDeu September 23, 2026 00:05
@bolichen97

Copy link
Copy Markdown
Contributor Author

Intent: Make an agent recognise, in one probe rather than several wasted cycles, that an authenticated browser session died while it was working, and stop reading a page still on screen as proof the session is alive.
Not a goal: Changing any browser code, adding an automatic session-liveness check, or documenting any single company's SSO system inside a shipped skill.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 20d61a1805eabdb31a315356f6f703be76fc19f1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 20d61a1

Verdict parsed from the review's SHA-scoped output markers for commit 20d61a1805eabdb31a315356f6f703be76fc19f1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 20d61a1805eabdb31a315356f6f703be76fc19f1: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 20d61a1805eabdb31a315356f6f703be76fc19f1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the documented env -u PLAYWRIGHT_MCP_EXTENSION_TOKEN … attach command actually clears the shell policy floor, since the skill asserts nearby spellings are refused.

[DESIGN-REVIEWED] 20d61a1

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 20d61a1805eabdb31a315356f6f703be76fc19f1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify on a real attach session that re-attach actually drops tab-new tabs and exposes only the activated tab — that claim now ships as fact in two skills.

What this change ships

Inventory (6 items) — 6 justified

Intent: stop the agent misdiagnosing a browser login that expires mid-flow in attach mode — an ADDITION of guidance, grounded in a reproduced incident written in the description. FIX-vs-ADDITION gap: none; description and diff describe the same job.

  1. browser-auth gains a mid-flow session-death section with a new-tab probe recipe — justified
  2. browser-auth names the stability-timeout symptom and says probe before re-picking selectors — justified
  3. browser-auth adds a checkpoint rule for long forms — justified
  4. browser-auth's attach section carries the token-mismatch error text and the env -u fix scoped to attach — justified
  5. browser-auth states attach exposes only the tab the extension was activated on — justified
  6. web-browse repeats the one-tab note (skills load independently; both files already share the never-close paragraph, counted: 2 files) — justified

[FIRST-PRINCIPLES-REVIEWED] 20d61a1

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 20d61a1805eabdb31a315356f6f703be76fc19f1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 20d61a1

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 20d61a1805eabdb31a315356f6f703be76fc19f1: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@bolichen97
bolichen97 force-pushed the docs/browser-skill-session-expiry branch from 7d8168d to 9465d70 Compare September 23, 2026 00:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: probe example now opens a new tab and switches back, instead of navigating the driven tab

  • F1 src/kiro_crew/builtin_skills/browser-auth/SKILL.md:164 — the auth probe discards an in-progress form (residual/crash-data-loss-corruption): fixed

Legitimate, and self-added by this PR: the probe I introduced told the agent to goto while attached, and in attach mode that navigates the tab being driven. The finding's trigger is the one the same section names two paragraphs earlier ("again on the first ambiguous failure"), so it is the ordinary path, not an edge.
Fixed in 9465d70: the example is now tab-new <gated-url> followed by tab-select <original index>, with one sentence saying why (a same-tab navigation would discard whatever the user had half-entered), and a same-tab goto is admitted only when that tab holds nothing losable.
The PR body's description of the probe was rewritten in the same push so it does not describe the discarded form either.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Verify the shell gate actually admits env -u PLAYWRIGHT_MCP_EXTENSION_TOKEN playwright-cli attach — the skill asserts that boundary but nothing pins it: rebutted

Verified by running it, which is how the boundary was found. On this host, env -u PLAYWRIGHT_MCP_EXTENSION_TOKEN playwright-cli attach --extension=chrome was admitted and attached (playwright-cli 0.1.20). The form that was REFUSED was a later command assigning that same text to a shell variable and reusing it, which the floor classified as reading AWS credentials from the environment. That asymmetry is exactly what the added sentence states: use it on attach, do not carry it forward.
Pinning it in a test is declined as out of scope and not durable: the shell policy floor is the operator's own configurable deny surface (Settings → Security), so a test asserting one phrasing is admitted would encode a user-editable setting as a product invariant and red on a host whose owner tightened it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Verify the pinned tool behavior — the exact error strings, one-tab exposure, and "re-attach drops tab-new tabs" — against the shipped playwright-cli version, since the docs quote them verbatim: rebutted

All three were observed first-hand on playwright-cli 0.1.20, the version this product installs, during the session that motivated the change. The quoted attach failure is the tool's own text, reproduced after the extension token was changed mid-session. The one-tab exposure and the re-attach drop were observed together: tab-list returned three tabs while the original attach held, then one after a detach and re-attach, and the tab the user was looking at was unreachable until they activated the extension on it.
A version-pinned assertion is declined: the quoted string belongs to a third-party CLI the user upgrades independently, so a test over its wording would red on an upgrade that changed nothing about the advice. The surrounding prose already tells the reader to act on what the message MEANS (a mismatch, not a missing extension) rather than to match it literally.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
Driving a real internal form through attach mode lost ~28 minutes to three
failure modes none of the browser skills named, and two of those minutes-long
detours were spent on a hypothesis the skills would have ruled out.

Root causes, in the order they were hit:

1. The SSO session expired between two commands. The page already on screen
   kept rendering, so both the agent and the user read a working screenshot as
   proof the session was alive. Only the next request redirected.
2. The first symptom was not a login page but a click that timed out on
   "waiting for element to be visible, enabled and stable". The locator had
   resolved, so the ref was right; the app's background sync was failing auth
   and re-rendering. Reads as a selector bug, is not one.
3. attach exposes only the tab the extension was activated on, so tab-list is
   not a view of the browser and the tab the user was looking at could not be
   driven at all.
4. A token edited in the extension after the agent process started breaks
   attach with a message that names the token, which is easy to misread as a
   missing extension.

browser-auth gains a "session can die mid-flow" section: a rendered page is not
proof, a one-request probe whose printed Page URL is the whole verdict, the
stability-timeout symptom, and a checkpoint rule for long forms. Its attach
section gains the token-mismatch error with both fixes, plus the one-tab limit.
web-browse gains the one-tab limit where it already explains attach binding.

The token workaround is documented for the attach command only: carrying the
env-stripped form forward in a shell variable trips the shell policy floor as
credential access, and attach has already bound the session by then.
@bolichen97
bolichen97 force-pushed the docs/browser-skill-session-expiry branch from 9465d70 to 20d61a1 Compare September 23, 2026 00:53
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/apps/builtins/issue_radar/backend/crew_store.py since this head's CI ran (f47c56d -> 80532c1); CI re-running.

The red was not this diff. test/test_crew_log_exc_info_sites.py::test_no_exc_info_site_anywhere_in_kiro_crew_holds_a_crew_log_handle failed on shard 7 on both Linux and Windows, naming two exc_info sites in crew_store.py (_landed_since, _all_landed). This branch touches two markdown skill bodies and no Python at all. Those sites came in on main with #12303 and were fixed on main by #12943, which landed after this branch was cut, so the merge ref CI built still carried the offending code. Coverage Gate was downstream of the same failure (backend-test=failure -- failing closed).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 23, 2026 03:56
@bolichen97
bolichen97 merged commit ec99705 into main Sep 23, 2026
145 of 147 checks passed
@bolichen97
bolichen97 deleted the docs/browser-skill-session-expiry branch September 23, 2026 03:56
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
Driving a real internal form through attach mode lost ~28 minutes to three
failure modes none of the browser skills named, and two of those minutes-long
detours were spent on a hypothesis the skills would have ruled out.

Root causes, in the order they were hit:

1. The SSO session expired between two commands. The page already on screen
   kept rendering, so both the agent and the user read a working screenshot as
   proof the session was alive. Only the next request redirected.
2. The first symptom was not a login page but a click that timed out on
   "waiting for element to be visible, enabled and stable". The locator had
   resolved, so the ref was right; the app's background sync was failing auth
   and re-rendering. Reads as a selector bug, is not one.
3. attach exposes only the tab the extension was activated on, so tab-list is
   not a view of the browser and the tab the user was looking at could not be
   driven at all.
4. A token edited in the extension after the agent process started breaks
   attach with a message that names the token, which is easy to misread as a
   missing extension.

browser-auth gains a "session can die mid-flow" section: a rendered page is not
proof, a one-request probe whose printed Page URL is the whole verdict, the
stability-timeout symptom, and a checkpoint rule for long forms. Its attach
section gains the token-mismatch error with both fixes, plus the one-tab limit.
web-browse gains the one-tab limit where it already explains attach binding.

The token workaround is documented for the attach command only: carrying the
env-stripped form forward in a shell variable trips the shell policy floor as
credential access, and attach has already bound the session by then.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants