Repository navigation
2026 11 13 explorer agent design
History. Shipped in #129. What it asked for now lives in the living spec: plugin (PLG-44 to PLG-53). The tools (Ruling 3) are PLG-46; the no-overwrite and no-argument
open_sessionrules (Ruling 4) are PLG-47 and PLG-49; bare tool names (Ruling 5) are PLG-46; the stop-and-report default (Ruling 7) is PLG-50; the limits, the stop list and the report (Ruling 8) are PLG-45, PLG-51 and PLG-52. Ruling 6, sharing the caller's browser, holds until a session of its own exists and is in PLG-45.
**Status: SETTLED 2026-11-13, issue #121 (parent #115), pull request #129.
Rulings 1–8 are Dr K's, from #115 and #121. He approved the draft on #129 on
11-13. The draft was finished this round, not replaced. Checking it against the
code added Checked against the code and three (call)s, listed under Calls
that stand. A (call) is the agent's and stands unless Dr K says otherwise.
The build waits for the code of #119 and #114 (PR #122) to be on this branch's
base: the file is served by #119's mcp/agents.py, and its habit reads #114's
flows_here. Built by docs/superpowers/plans/2026-11-13-explorer-agent.md.
#115, by Claude for Dr K: a main agent that wants a website explored either drives the browser itself, filling its context with every page, or writes a subagent by hand that knows nothing of flows. The first agent this server ships explores a website for a main agent and reports back briefly. Its one habit: as it navigates, it always tries to use a flow, and when it does by hand something that will be done again, it saves one. It reads the embedded skill by its URI before its first browser call.
#121 is the second half of #115's split. #119 builds plugin/ and the agents
extension that serves this file. #114 builds the hints this agent reads.
#119 (2026-11-12-plugin-agents-design.md, and its plan). mcp/agents.py
loads every plugin/agents/*.md, top level only, and serves each one through
agents/list and agents/get. The extension is declared from #119 on, with an
empty list (#119 Ruling 7). This issue is what puts something in it.
What #119 requires of the file:
- The frontmatter is a non-empty mapping that survives conversion to JSON.
-
namehas no whitespace,/or@. -
descriptionis non-empty.
What #119 makes of it:
-
modelbecomesmodelRoutingHint:opusislarge,sonnetismedium,haikuissmall, andinheritgives no hint. -
skillsbecomes_meta["io.kubed/agent"].skills, beside the frontmatter exactly as written. -
agents/getreturnstools: []always. The frontmatter'stoolsreaches a host only through_meta.
A file that does not load is skipped and logged, which is why this issue adds a strict test.
#114 (2026-11-12-flow-sites-paths-design.md). flows_here is an optional
result field listing the flows whose sites and paths match the page.
-
On
open_session: always. -
On a result whose page changed host, port or path: yes. A query or fragment
change does not count, and
url=Nonecarries none. - On a run's final report: if the run's last page changed. Steps inside a run carry none.
-
On
workspace://current: on every read.
The field is an array, absent when nothing applies, of at most 10 entries, the
workspace's own flows before global's. Each entry is:
{
"name": "…",
"uri": "flow://flows/<name>",
"description": "…",
"parameters": ["…"],
"required": ["…"],
"shared": true // only for a global flow
}
#114's rule for agents, which this agent follows rather than restates:
- Run a hinted flow with
run_flowwhen its description matches the task and every required parameter can be filled. - Read
flow://flows/{name}first when:- the description is unclear;
- a parameter cannot be filled;
- the flow writes something the agent was not asked to write.
- Never run a flow only because it is hinted.
Read on 11-13, on issue-121 (base issue-115):
-
Neither #119's code nor #114's is on the branch yet. There is no
plugin/, nomcp/agents.pyand noflows_hereinkubed/. The interfaces this spec and its plan use are taken from #119's plan (2026-11-12-plugin-agents.md):-
agents.load(base=None, skills=()) -> list[Agent], whereAgenthasname,cardanddetail; -
agents.agents_path(); - a skipped file logs
agent file %s is skipped: ….
If #119 lands with different names, the plan follows the code.
-
-
The tool names are the registered ones. Every name in Ruling 3 is a tool today: the browser actions in
tests/test_surfaces.py'sEXPECTED, withopen_sessionandend_browser, the three flow tools,keep_file, andshow.showis listed only to a client that renders apps, andlist_resources/read_resourceonly to one that cannot read resources. -
A save replaces without asking.
flows/api.save_onecreates or replaces, and nothing on the server knows which run saved a flow. So Ruling 4's overwrite rule is the body's to keep, and there is no check to build. -
flow://flowslists the workspace's flows and the shared library's, each withshared(flows/api.catalogue). A flow saved in the workspace under a shared flow's name shadows it:read_oneandrun_flowthen find the workspace's. That is why a nameflow://flowslists at all counts as taken (Calls that stand). -
The resources the body names are served:
workspace://current,flow://flows,flow://flows/{name}, and the skill's files (tests/test_show_inventory.py'sFORMS).
- A sub-issue of its own, built after #114 (Dr K, 2026-11-12, #115).
-
The family's rulings hold (Dr K, #115 and #119):
-
_metais the sharedio.kubed/agent; - the name is unprefixed, so
explorer; - agents are served only with
mcp.skill; - in-cluster clients reach
agents/*on the Service directly.
-
-
The tools (Dr K, 2026-11-13, #121).
-
In:
open_session,navigate,extract,outline,screenshot,interact,write,press_key,frame,dialog,await_control,run_flow,save_flow,execute_script.execute_scriptis in because the server's instructions say to scroll with it. -
Out:
end_browser, which would end the caller's browser, anddelete_flow, because it saves flows and never removes them.resizeandsave_site_dataare out because they change the caller's window and saved site data.upload_file,drag,print,keep_file,show,assertandnetwork_bodyare out because exploring needs none of them.
-
In:
-
Two rules with the tools (Dr K, 2026-11-13, #121):
-
open_sessionis called with no arguments, and only when no browser is open, so it opens with the caller's settings rather than its own; -
save_flownever overwrites a flow it did not save in the same run.
-
-
Bare tool names in the file (Dr K, 2026-11-13, #121).
toolslistsnavigate, notmcp__<server>__navigate, because the server name is the client's to choose. Thekb-agentsmod prefixes them with the server it reached the agent through. It also grants the host's own resource reader, because the explorer readsskill://andflow://URIs, and Claude Code serves those through its built-in resource tools, not ours. Both are listed under Outside this repo. -
It shares the caller's browser until #94 (Dr K, 2026-11-13, #121). Until
then, the caller must not drive while the explorer runs. #94 (multiplayer) is
expected to let a known subagent pin its own session, with an
Sf-Session: explorerheader on its own MCP entry. Once it does, the explorer stops sharing and the rule goes. That is the follow-up. Nothing is built for it here. - Stop and report by default (Dr K, 2026-11-13, #121). The explorer never takes a step that changes something on the site unless the main agent's hand-off names that exact step, such as "you may submit the search form" or "you may sign in as X". It takes only that step, and only once. Anything else that would change the site goes under Couldn't in the report, with the step it would have taken.
-
The limits, the stop list, the report and the tests are accepted (Dr K,
2026-11-13, #121), as drafted below:
model: sonnet,maxTurns: 40, When it stops, the five headings of The report in about 200 words, and the five tests.
A main agent hands the explorer a question about a website. The explorer answers it in the caller's workspace, using the flows that fit each page and leaving new ones behind for what it did by hand. What comes back is a short report, not the pages.
- Any change to
mcp/agents.py, the extension or the folder (#119). - Any change to
flows_here,sitesorpaths(#114). - A session of its own. That is #94 (Ruling 6).
- A server-side check on the overwrite rule or on sharing. The server cannot tell the explorer's calls from the caller's (Checked against the code).
- Doing the task it explored for. It explores and reports. A step that changes something on the site is taken only when the hand-off names it (Ruling 7).
- An integration test. AGENTS.md's "less is more" applies, and an agent is not a browser action.
---
name: explorer
description: >-
Explores a website in your selenium-flow workspace and reports back briefly:
what it found, the flows it used, the flows it saved for next time. It drives
your workspace's browser, so do not call selenium-flow tools until it reports.
Hand it the question, the starting URL, and the values any flow will need.
It changes nothing on the site unless you name the exact step it may take,
e.g. "you may submit the search form" or "you may sign in as X".
model: sonnet
maxTurns: 40
skills: [selenium-flow]
tools:
- open_session
- navigate
- extract
- outline
- screenshot
- interact
- write
- press_key
- frame
- dialog
- await_control
- run_flow
- save_flow
- execute_script
----
descriptionis written for the main agent, which reads it when deciding whether to delegate. It says four things:- what comes back;
- the browser rule (Ruling 6);
- what to hand over;
- that a step which changes the site has to be named (Ruling 7).
It names no tool by its host-qualified name.
-
model: sonnet(Ruling 8): exploring is many cheap steps. It routes asmedium. -
maxTurns: 40(Ruling 8). This is a Claude Code agent field. #119 passes it through in_metaand does not read it.
The body is prompt for the subagent, the way mcp/tools.py's docstrings are
prompt. It defers to the skill and #114's rule, and does not restate them. It
names every resource by its URI, a template in its template form
(flow://flows/{name}), and names no tool it does not have (call): a
subagent told to call a tool its host withheld fails mid-run.
-
Read
skill://selenium-flow/SKILL.mdfirst, before any browser call. Readskill://selenium-flow/references/FLOWS.mdbefore the firstsave_flow. A URI it cannot read goes under Couldn't, and it carries on with what the tool results say (call). -
Find the browser. Read
workspace://current. If a session is open, start there. If not, callopen_sessionwith no arguments (Ruling 4). -
Try a flow first. Whenever a result or
workspace://currentcarriesflows_here, apply #114's rule to the step in hand before driving by hand. Run a flow only with values the caller handed over or the page shows; never invent one. A flow that would change something on the site counts as that change, and runs only if the hand-off names it (Ruling 7). -
Drive by hand only where no flow fits, reading with
extractandoutlinebefore reaching forscreenshot, as the skill says. -
Save what will be done again. Some sequences done by hand will plainly
recur: a login, a search, reaching a page deep in the site. Save each with
save_flowin the caller's workspace, withsitesandpathsset so thatflows_hereoffers it on that page next time. Give each a name and description that say what it does. Never overwrite a flow it did not save in this run (Ruling 4): before a save, readflow://flows, and a name listed there at all, the workspace's or the shared library's, is taken unless this run saved it (call). If the name is taken, pick another. -
Wait, don't fight, when a person holds the browser. A refusal naming
await_controlmeans a person is in Control. Call it once. If Control is still held after that, stop and report. - Leave the browser open, on the last page it reached. It has no tool that ends the browser (Ruling 3), and the caller decides.
- Stop and report (When it stops, The report).
Placing an order, sending a message, deleting, or submitting any form: each changes something on the site. By default the explorer takes none of them.
- The hand-off names a step, for example "you may submit the search form" or "you may sign in as X". The explorer takes that step, once.
- A second time, or a step the hand-off does not name, is reported under Couldn't, with the step it would have taken.
- A search or a login is not exempt. It is taken only when it is named.
- When in doubt whether a step changes the site, the explorer treats it as if it does.
- The question is answered.
- Something it was not given blocks it: a login, a CAPTCHA, a value no flow or page supplies.
- The next step would change something on the site and the hand-off does not name it (Ruling 7). It reports the step instead of taking it.
-
A person still holds Control after one
await_control. -
It is near
maxTurns. It keeps the last few turns for the report, so a cut-off run still says what it found.
Plain Markdown, at most about 200 words, under five headings in this order:
- Found: the answer to the question, or what it learned instead.
- Flows used: the name of each, and whether it worked.
- Flows saved: for each, the name, what it does, and its required parameters.
- Couldn't: each blocker and why. For a step that would have changed the site, it names the step it would have taken (Ruling 7), so the main agent can name it in the next hand-off.
- Browser: the page it left the browser on, as an origin and path. No query string, because a query can carry a token.
No page text beyond what answers the question, and no screenshots inline.
Until #94, sharing is made explicit in two places:
- The description tells the main agent not to call selenium-flow tools until the report arrives. A Claude Code main agent reads that when it delegates.
- The report's Browser line tells the main agent where its browser now is, because the explorer moved it.
No server-side lock or check is added. One browser-driving call at a time per
session (workspace/locks.py) already keeps two calls from interleaving. What it
cannot stop is two agents taking turns on one page, and that is #94's.
A new tests/test_explorer.py, unit-marked, beside #119's
tests/test_agents_extension.py. The five accepted tests (Ruling 8):
-
It loads strictly.
agents.loadover the shippedplugin/agents/returnsexplorer, and no file is skipped. This followstests/test_prompts.py, which loads every shipped prompt strictly. Without it a broken frontmatter is skipped, logged, and invisible until somebody lists. -
Every listed tool exists. Each name in
toolsis a tool this server registers, so a rename fails here and not in a host. -
None of the excluded tools is listed (Ruling 3),
end_browseranddelete_flowabove all. The test pins the ruling:toolsis Ruling 3's In set exactly. -
It names the skill by URI. The body contains
skill://selenium-flow/SKILL.md, and_meta["io.kubed/agent"].skillsmapsselenium-flowto it. -
It routes.
agents/get explorerreturnsmodelRoutingHintforsonnet.
And four more, from the plan's Review Focus, each holding one thing a person would see break that the five do not:
-
No host-qualified name. No
mcp__anywhere in the file (Ruling 5). -
The body and description name no tool outside
tools(The body's call). - Every URI the body names is served: a skill file that exists, or a resource or template this server lists.
- The prompt keeps its two promises: the body has the report's five headings in order, and the description carries the browser rule (Ruling 6), since until #94 it is one of the only two places it is said.
-
README.md: one sentence. Agent-aware clients find the explorer throughagents/list, and it explores a site using and saving flows. -
AGENTS.md: one line under #119's agents paragraph. It covers:- the explorer is the first agent;
- its tools are pinned by a test;
- it shares the caller's browser until #94.
-
CHANGELOG.md[Unreleased]: one line, "An explorer agent, served throughagents/list, explores a site for a main agent, using and saving flows." The extension's own line is #119's (#119 Ruling 7). - The skill: no change. The explorer reads it, and it does not describe the explorer.
-
claude-control
kb-agents:- read
io.kubed/agent; - learn selenium-flow's in-cluster
url; - prefix the bare
toolswith the server it reached the agent through; - grant the host's resource reader (Ruling 5).
- read
-
#94: a known subagent pins its own session (
Sf-Session: explorer), which ends the browser-sharing rule (Ruling 6).
In-cluster, from the pod:
- a legacy
initializecarriesio.modelcontextprotocol/agents; -
agents/listnamesexplorer; -
agents/get explorercarriesmodelRoutingHintandio.kubed/agent; -
skill://selenium-flow/SKILL.mdreads back.
Once the mod change lands, delegate one exploration from Claude Code against the admin page. Check two things:
- the report has the shape above;
- a flow it saved appears in
flows_hereon the next visit.
- The hand-off (call): until #94, the description and the report's Browser line are the only places sharing is made explicit. No server-side check is added.
-
A taken name (call): any name
flow://flowslists, the workspace's or the shared library's, is taken unless this run saved it, because saving over a shared flow's name shadows it for the caller. - The body names no tool it does not have (call), so item 7 says "no tool that ends the browser" rather than naming it; test 7 holds it.
-
A URI it cannot read (call) goes under Couldn't, and the explorer
carries on with what the tool results say, which still carry
flows_here.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network