explorbot 0.2.4 → 0.2.5

package/dist/src/test-plan.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { tag } from "./utils/logger.js";
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from "./utils/test-plan-markdown.js";
 import { uniqSessionName } from "./utils/unique-names.js";
 export const TestResult = {
@@ -260,12 +261,14 @@ export class Test extends Task {
         this.startTime = performance.now();
         this.addNote(`Test started. Session name: ${this.sessionName}`);
         this.plan?.notifyChange();
+        this.reportStatus();
     }
     finish(result = TestResult.FAILED) {
         this.status = TestStatus.DONE;
         this.result = result;
         this.endTime = performance.now();
         this.plan?.notifyChange();
+        this.reportStatus();
     }
     getDurationMs() {
         if (this.startTime != null && this.endTime != null)
@@ -276,6 +279,17 @@ export class Test extends Task {
         const achieved = this.getCheckedExpectations();
         return this.expected.filter((e) => !achieved.includes(e));
     }
+    reportStatus() {
+        tag('data').log('test', {
+            scenario: this.scenario,
+            status: this.status,
+            result: this.result,
+            priority: this.priority,
+            sessionName: this.sessionName,
+            url: this.startUrl,
+            plan: this.plan?.title,
+        });
+    }
     getLog() {
         const merged = {};
         for (const [key, stepData] of Object.entries(this.steps)) {
@@ -338,6 +352,11 @@ export class Plan {
         for (const listener of this.changeListeners) {
             listener(this.tests);
         }
+        tag('data').log('plan', {
+            title: this.title,
+            url: this.url,
+            tests: this.tests.map((test) => ({ scenario: test.scenario, status: test.status, result: test.result, priority: test.priority })),
+        });
     }
     getAllTests() {
         if (!this.parentPlan)

package/dist/src/utils/logger.d.ts

@@ -1,5 +1,5 @@
 import { type Span } from '@opentelemetry/api';
-export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input';
+export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input' | 'data';
 export interface TaggedLogEntry {
     type: LogType;
     content: string;

package/dist/src/utils/logger.js

@@ -406,6 +406,14 @@ class Logger {
             }
             return;
         }
+        if (type === 'data') {
+            const entry = { type, content: String(args[0]), timestamp: new Date(), originalArgs: args };
+            for (const destination of this.extra) {
+                if (destination.isEnabled())
+                    destination.write(entry);
+            }
+            return;
+        }
         const options = this.extractLogOptions(type, args);
         let content = this.processArgs(args);
         if (type === 'step' && args[0]?.toCode) {

package/docs/index.json

@@ -66,7 +66,8 @@
       "pages": [
         { "title": "Commands", "file": "reference/commands.md", "description": "Every CLI and terminal command" },
         { "title": "Configuration", "file": "reference/configuration.md", "description": "The config file, top to bottom" },
-        { "title": "Scripting", "file": "reference/scripting.md", "description": "The programmatic API" }
+        { "title": "Scripting", "file": "reference/scripting.md", "description": "The programmatic API" },
+        { "title": "WebSocket stream", "file": "reference/websocket.md", "description": "Every frame a listener can read from a run" }
       ]
     },
     {

package/docs/reference/commands.md

@@ -51,6 +51,7 @@ Inside the TUI, use the matching slash command: `/explore`, `/research`, `/plan`
 | Manage persistent browser | `npx explorbot browser {start\|stop\|status}` | — | Share browser across runs |
 | Initialize project | `npx explorbot init` | — | Generates `explorbot.config.*`, or `~/.explorbot` with `--global` |
 | List registered sites | `npx explorbot sites` | — | Sites stored in the global installation |
+| Show resolved configuration | `npx explorbot config [url] [--json]` | `/config` | Models, config file, paths and `EXPLORBOT_*` in effect |
 | Clean generated files | `npx explorbot clean [target]` | `/clean [target]` | Same targets both ways |
 
 ## Common CLI Options
@@ -107,6 +108,8 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 | `EXPLORBOT_NO_BANNER` | Suppress the startup banner, for machine-readable output |
 <!-- END env -->
 
+`npx explorbot config` prints the values a run actually uses — models per role, the config file behind them, the output, knowledge and experience directories, and every `EXPLORBOT_*` variable currently set. The boats answer for their own configuration the same way: `npx explorbot api config`, `npx explorbot docs config`, `npx explorbot prima config`. Add `--json` on any of them to get the same values as an object a script can read.
+
 Explorbot resolves its configuration in this order: the path given to `--config`, then `explorbot.config.*` in the working directory, then the `EXPLORBOT_*` variables, and finally `~/.explorbot/config.*` from the global installation. A bare provider name fills every model role from the recommendations in [Providers](../basics/providers.md); a `provider/model-id` spec pins one model and splits on the first slash, so `openrouter/openai/gpt-oss-120b:nitro` selects OpenRouter with model `openai/gpt-oss-120b:nitro`. Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`.
 
 In this mode output goes to `~/.explorbot/sites/<host>/output/` (or `EXPLORBOT_OUTPUT`, or a temp directory with `EXPLORBOT_EPHEMERAL=1`), experience is kept beside it unless the run is ephemeral, and the Historian is off, so no generated test files appear. See [Agentic Usage](../workflow/agentic-usage.md) for the full picture.

package/docs/reference/websocket.md

@@ -0,0 +1,50 @@
+# WebSocket Stream
+
+`--ws <url>` (or `EXPLORBOT_WS_URL`) streams a run to your own UI. Explorbot dials **out** — your side is the server — so the same flag covers a child process you spawned and a CI bot connecting from elsewhere.
+
+```bash
+npx explorbot explore /dashboard --ws ws://127.0.0.1:8787
+```
+
+Every message is JSON with a `type` and a `ts`, plus whatever that type carries. Nothing is validated on either side: render the types you know, ignore the rest, and expect new ones.
+
+## What a run sends
+
+| Type | What it is |
+|---|---|
+| `hello` | the run itself: command, working directory, pid |
+| `state` | the page under test: url, path, title, heading |
+| `test` | a test starting or finishing, with its status, result and plan |
+| `plan` | the current plan and the status of every test in it |
+| `screenshot` | the screenshot file just written |
+| `research` | the researcher's map of a page: markdown and its file |
+| `report` | the analyst's end-of-session report: markdown and its file |
+| `activity` | what the run is doing this second |
+| `log` | a log line and its level |
+| `ask` | a question for a human, carrying an `askId` |
+| `result` | the run exited, with its code |
+
+Each type carries the latest truth, so keep the last frame per type — that is what the terminal itself shows.
+
+## What you can send back
+
+| Type | What it does |
+|---|---|
+| `answer` | answers an `ask`: same `askId`, plus `value` — or `null` to skip the question |
+| `interrupt` | stops the current step; the run then asks what to do instead |
+
+A run with nobody to answer never asks in the first place, so connecting a listener that answers is what makes a headless run interactive.
+
+## Delivery
+
+Frames queue while disconnected — the last 1000 — and the connection retries on its own, so treat it as a live feed rather than a history. On exit the queue is flushed after `result`.
+
+## Adding a frame
+
+Frames are logged, not published:
+
+```ts
+tag('data').log('coverage', { visited: 12, total: 30 });
+```
+
+That reaches listeners as a `coverage` frame. A `data` entry never goes to the console, the log file, or the TUI.

package/docs/superpowers/specs/2026-08-18-prima-false-verdicts.md

@@ -0,0 +1,159 @@
+# Prima False Verdicts — No Reload, Vision-Confirmed Outcomes, Unconfirmed ≠ Failed
+
+**Date:** 2026-08-18
+**Status:** Implemented
+**Follows:** `2026-08-07-prima-fixes-design.md`
+**Evidence:** field feedback from an orchestrator driving prima over eight calls
+
+## Problem
+
+Prima returned verdicts that did not match what happened, in both directions.
+
+- `prima do` reported `error: open: <instruction>` for clicks that had landed. The caller only
+  found out by screenshotting anyway — which is the cost the boat exists to remove.
+- `prima check` returned `ok: false` for an environmental reason and said nothing about it.
+- No command answered a visual question with a verdict. `check` and `verify` never read a
+  screenshot; `ask` read one but returned prose.
+
+The skill tells callers to trust `### Result`. A false red trains them out of that, and then the
+greens stop meaning anything either.
+
+## Mechanisms found
+
+1. **`check` reloaded the page before checking it.** `prima.check()` → `tester.test()` →
+   `runTestSession` → `explorer.visit(task.startUrl!)` (`tester.ts:192`, unconditional) →
+   `I.amOnPage()` (`explorer.ts:431`) → `page.goto()`, which reloads even on the same URL.
+   `task.startUrl` is the page the caller is already on. Any transient state — an open dialog, a
+   selected tab, an unsaved form — was destroyed by the command asked to inspect it. This was
+   guaranteed, not a race with a dev-server reload.
+2. **`check` could not say why it failed.** `reportEnvelope` never sets `failure`, and
+   `envelope.steps` was built only from notes with `status === FAILED`. An abort produced
+   `ok: false` with an empty Steps section and no Failure section.
+3. **`do`'s verdict was the model's bookkeeping, not the page.** An instruction the model never
+   passed to `completed()` was rendered as an error, so an envelope could show every step green
+   and `ok: false` at once. `settleLedger`'s `.catch(() => null)` made a provider error
+   indistinguishable from a model that would not report.
+4. **Vision routing was per command, not per question.** `verify` produced DOM assertions only;
+   `check`'s verdict came from that same tool plus `settleExpectations`, which judged a text log.
+   The `inexpressible` branch told the model to "check it with `see()`" with no model in the loop
+   to act on the suggestion.
+5. **`prima status` printed the page tree.** `saveStatus` stored the full compact ARIA under
+   `changes`, so the command whose job is to cite artifact paths dumped the tree inline instead.
+
+## Changes
+
+### 1. `check` starts where the caller is
+
+`Tester.test(task, opts)` takes `startOnCurrentPage`, which skips the initial visit. Prima passes
+it. Nothing else changes for the explore flow, where reload-to-start-url is intentional.
+
+`reset` needs no guard: it already refuses when the current URL equals the start URL, which is
+the case for a check that starts in place. Once a check has navigated away, resetting back is
+the right behaviour anyway.
+
+### 2. The screenshot is the proof, and a disagreement is a finding
+
+`settleExpectations` is called from exactly one place, `prima.ts`, so it is prima's final judge
+and can change without touching the explore flow. It now takes the final `ActionResult` and, when
+that carries a screenshot and a vision model is configured, settles every outcome in one
+structured call on the vision model with the image attached.
+
+The screenshot is not one of two equal inputs. An outcome is satisfied when the page shows it to
+somebody looking at it; the log only says what the run did. The prompt says so.
+
+**Where the two disagree, the judge does not choose.** It reports `contradiction` and says what each
+side shows. An assertion that matched an element nobody can see is a defect in the application, and
+it is exactly the case both other verdicts destroy: `passed` hides it behind an assertion that
+happens to match, `failed` mislabels a feature that half works. It comes back as its own status
+with both sides quoted, it fails the command, and `### Artifacts` names the html, aria and screenshot
+on disk so the caller can settle it on the page itself rather than on the judge's word.
+
+**Absence in the picture is not a contradiction.** Review of the first pass raised this: a
+screenshot is not proof that a thing is missing, only that the judge could not make it out. A
+contradiction now requires the picture to show something *incompatible* — a list visibly empty, an error
+where a result was expected, the old value still displayed. "I cannot find it" is `unverified`,
+which does not fail the command.
+
+The screenshot is the final page only. An outcome the run established earlier stays established
+even when the page has moved past it, and the prompt says that is not a contradiction — otherwise every
+"record deleted, then navigated away" scenario reports one.
+
+### 3. `check`'s verdict is its outcomes
+
+`ok` no longer comes from `tester.test()`'s success flag, which could contradict the outcomes
+printed beside it. `ok: true` when no outcome failed and none was contradicted; each failure and
+each contradiction names itself in `### Failure`. `unverified` is not a failure — it is a statement about
+the run, matching what the help text already promised.
+
+A run that could not complete is reported separately from an application failure: when the test
+never finished or was skipped, the envelope says the run established nothing and cites the last
+step recorded.
+
+### 4. `do` distinguishes failed from unconfirmed
+
+`ok` is a function of what ran, not of the paperwork. An action error or a `blocked()` fails the
+command. An instruction the model never reported becomes a `??` row in `### Steps` — the actions
+that ran are listed above it — and does not fail the command. An AI error while settling the
+ledger is reported as its own step rather than attributed to the instruction.
+
+The `<proof>` block gains one general line: how much of the page moved is not evidence of whether
+something happened. A change confined to one region proves an instruction as well as one that
+redraws everything.
+
+### 5. `verify` reaches for vision when no assertion can express the claim
+
+The `inexpressible` branch now judges the claim from a screenshot and reports the judgement,
+instead of dead-ending on a suggestion nothing acts on. Because Tester's `verify` tool calls the
+same `navigator.verifyState`, this covers `check` as well.
+
+`Prima.visionEnabled()` also honours `Stats.visionDisabled`, so a session that lost vision
+mid-run stops claiming to have it.
+
+### 6. `status` cites artifacts instead of reprinting the page
+
+The ARIA blob is gone from `status.json`. `status` returns the page block and the artifact paths,
+which is its whole job.
+
+## Decisions Log
+
+- `check` starts on the current page. A command that inspects transient UI must not destroy it.
+- Vision is not a fallback in `check`; it closes every run that has a vision model. The
+  screenshot is the proof — what a user can see — and the run log only says what was done.
+- A disagreement between the picture and the run is reported as `contradiction`, never settled one
+  way. An assertion matching an element nobody can see is a defect, and both `passed` and `failed`
+  would bury it. A contradiction fails the command, and hands the caller the page files to judge on.
+  The word is `contradiction` rather than `conflict` because it names what happened, and rather than
+  `ambiguity` because that is what `unverified` already means.
+- A contradiction needs the picture to show something incompatible. Not finding something is `unverified`;
+  absence of evidence is not evidence of absence, and treating it as one is how a false-verdict fix
+  becomes a false-verdict generator.
+- Nothing probes the page to explain *why* something is invisible. A first attempt walked the DOM
+  comparing colours, sniffing screen-reader patterns and hit-testing every element; it was a pile of
+  heuristics guessing at an answer the contradiction already states. "The run says it is there and
+  the picture does not show it" is the finding, and the caller is better placed to say why.
+- `settleExpectations` judges all outcomes, not only undecided ones, when it has a screenshot —
+  otherwise a DOM assertion the run already made could never be contradicted by the page.
+- `unverified` is not a failure, in `check` outcomes and in `do` instructions alike. A statement
+  about the run is not a statement about the application.
+- Bookkeeping is not evidence. `do`'s `ok` follows actions and blocks; an unreported instruction
+  is surfaced, never rendered as an error.
+- A run that could not complete is reported as such, never as an application failure.
+- `provider.getVisionModel()` is added for symmetry with `getModelForAgent`/`getAgenticModel`;
+  `processImage` returns free text and cannot carry a per-outcome verdict.
+- A failed vision judgement falls back to the text model and flips `Stats.visionDisabled` — the
+  existing global for "vision is not usable this session" — which prima reads through
+  `visionEnabled()`.
+- No line reports which evidence the judge had; that is plumbing. Only the degraded case is
+  stated, as a `### Warning`, because only that case is a fact the caller must act on.
+- The verdict vocabulary lives in `prima <command> --help`. A marker the caller can see in an
+  envelope but cannot look up is not documented.
+
+## Not done
+
+- `explorer.beginTest` still calls `closeOtherTabs()`, so `check` closes other tabs of an
+  attached session. Guarding it means threading an option through `beginTest`, which every flow
+  shares.
+- `do` gets no vision confirmation pass. Its `completed()` proof is the same kind of unverified
+  paperwork, but a per-instruction vision call is a different cost profile.
+- The `prima` skill in `testomatio/skills` documents the old envelope vocabulary. It needs the
+  `??` row, the `CONTRADICTION` status, and the unconfirmed-is-not-failed rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/action.ts

@@ -57,6 +57,7 @@ class Action {
     try {
       await (this.actor as any).saveScreenshot(filename);
       if (currentState) currentState.screenshotFile = filename;
+      tag('data').log('screenshot', { path: outputPath('states', filename) });
       return filename;
     } catch (err) {
       debugLog('Screenshot failed:', err);
@@ -105,7 +106,10 @@ class Action {
         const screenshotPath = join(statesDir, filename);
         screenshotFile = await page
           ?.screenshot({ path: screenshotPath, fullPage: true })
-          .then(() => filename)
+          .then(() => {
+            tag('data').log('screenshot', { path: screenshotPath });
+            return filename;
+          })
           .catch((err: Error) => {
             debugLog('Screenshot failed, continuing without it:', err);
             return undefined;