Skip to content

2026 11 13 explorer agent design

Dr K edited this page Nov 14, 2026 · 2 revisions

The explorer: an agent that tries a flow first

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_session rules (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.

Brief

#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.

What it builds on

#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.
  • name has no whitespace, / or @.
  • description is non-empty.

What #119 makes of it:

  • model becomes modelRoutingHint: opus is large, sonnet is medium, haiku is small, and inherit gives no hint.
  • skills becomes _meta["io.kubed/agent"].skills, beside the frontmatter exactly as written.
  • agents/get returns tools: [] always. The frontmatter's tools reaches 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=None carries 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_flow when 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.

Checked against the code

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/, no mcp/agents.py and no flows_here in kubed/. 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], where Agent has name, card and detail;
    • 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's EXPECTED, with open_session and end_browser, the three flow tools, keep_file, and show. show is listed only to a client that renders apps, and list_resources / read_resource only to one that cannot read resources.

  • A save replaces without asking. flows/api.save_one creates 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://flows lists the workspace's flows and the shared library's, each with shared (flows/api.catalogue). A flow saved in the workspace under a shared flow's name shadows it: read_one and run_flow then find the workspace's. That is why a name flow://flows lists 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's FORMS).

Rulings

  1. A sub-issue of its own, built after #114 (Dr K, 2026-11-12, #115).
  2. The family's rulings hold (Dr K, #115 and #119):
    • _meta is the shared io.kubed/agent;
    • the name is unprefixed, so explorer;
    • agents are served only with mcp.skill;
    • in-cluster clients reach agents/* on the Service directly.
  3. 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_script is in because the server's instructions say to scroll with it.
    • Out: end_browser, which would end the caller's browser, and delete_flow, because it saves flows and never removes them. resize and save_site_data are out because they change the caller's window and saved site data. upload_file, drag, print, keep_file, show, assert and network_body are out because exploring needs none of them.
  4. Two rules with the tools (Dr K, 2026-11-13, #121):
    • open_session is called with no arguments, and only when no browser is open, so it opens with the caller's settings rather than its own;
    • save_flow never overwrites a flow it did not save in the same run.
  5. Bare tool names in the file (Dr K, 2026-11-13, #121). tools lists navigate, not mcp__<server>__navigate, because the server name is the client's to choose. The kb-agents mod prefixes them with the server it reached the agent through. It also grants the host's own resource reader, because the explorer reads skill:// and flow:// URIs, and Claude Code serves those through its built-in resource tools, not ours. Both are listed under Outside this repo.
  6. 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: explorer header 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.
  7. 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.
  8. 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.

Goal

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.

Non-goals

  • Any change to mcp/agents.py, the extension or the folder (#119).
  • Any change to flows_here, sites or paths (#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.

The design

The file: plugin/agents/explorer.md

---
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
---
  • description is 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 as medium.

  • maxTurns: 40 (Ruling 8). This is a Claude Code agent field. #119 passes it through in _meta and does not read it.

The body: what it is told

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.

  1. Read skill://selenium-flow/SKILL.md first, before any browser call. Read skill://selenium-flow/references/FLOWS.md before the first save_flow. A URI it cannot read goes under Couldn't, and it carries on with what the tool results say (call).
  2. Find the browser. Read workspace://current. If a session is open, start there. If not, call open_session with no arguments (Ruling 4).
  3. Try a flow first. Whenever a result or workspace://current carries flows_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).
  4. Drive by hand only where no flow fits, reading with extract and outline before reaching for screenshot, as the skill says.
  5. 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_flow in the caller's workspace, with sites and paths set so that flows_here offers 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, read flow://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.
  6. Wait, don't fight, when a person holds the browser. A refusal naming await_control means a person is in Control. Call it once. If Control is still held after that, stop and report.
  7. Leave the browser open, on the last page it reached. It has no tool that ends the browser (Ruling 3), and the caller decides.
  8. Stop and report (When it stops, The report).

Steps that change the site (Ruling 7)

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.

When it stops (Ruling 8)

  • 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.

The report (Ruling 8)

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.

The hand-off (Ruling 6)

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.

Testing

A new tests/test_explorer.py, unit-marked, beside #119's tests/test_agents_extension.py. The five accepted tests (Ruling 8):

  1. It loads strictly. agents.load over the shipped plugin/agents/ returns explorer, and no file is skipped. This follows tests/test_prompts.py, which loads every shipped prompt strictly. Without it a broken frontmatter is skipped, logged, and invisible until somebody lists.
  2. Every listed tool exists. Each name in tools is a tool this server registers, so a rename fails here and not in a host.
  3. None of the excluded tools is listed (Ruling 3), end_browser and delete_flow above all. The test pins the ruling: tools is Ruling 3's In set exactly.
  4. It names the skill by URI. The body contains skill://selenium-flow/SKILL.md, and _meta["io.kubed/agent"].skills maps selenium-flow to it.
  5. It routes. agents/get explorer returns modelRoutingHint for sonnet.

And four more, from the plan's Review Focus, each holding one thing a person would see break that the five do not:

  1. No host-qualified name. No mcp__ anywhere in the file (Ruling 5).
  2. The body and description name no tool outside tools (The body's call).
  3. Every URI the body names is served: a skill file that exists, or a resource or template this server lists.
  4. 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.

Documentation

  • README.md: one sentence. Agent-aware clients find the explorer through agents/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 through agents/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.

Outside this repo

  • claude-control kb-agents:
    • read io.kubed/agent;
    • learn selenium-flow's in-cluster url;
    • prefix the bare tools with the server it reached the agent through;
    • grant the host's resource reader (Ruling 5).
  • #94: a known subagent pins its own session (Sf-Session: explorer), which ends the browser-sharing rule (Ruling 6).

Live check after deploy

In-cluster, from the pod:

  • a legacy initialize carries io.modelcontextprotocol/agents;
  • agents/list names explorer;
  • agents/get explorer carries modelRoutingHint and io.kubed/agent;
  • skill://selenium-flow/SKILL.md reads 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_here on the next visit.

Calls that stand

  • 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://flows lists, 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.

Clone this wiki locally