@data-fair/lib-agents-sim 0.3.0 → 0.4.1

package/README.md

@@ -51,8 +51,8 @@ Agent SDK may hoist zod 4 and break `ai`'s type inference. Add
 npx df-agents-sim-init [--force]
 ```
 
-Copies the `/simulate` skill and the `simulation-judge` sub-agent definition
-into your repo's `.claude/skills/simulate/SKILL.md` and
+Copies the `/agents-sim` skill and the `simulation-judge` sub-agent definition
+into your repo's `.claude/skills/agents-sim/SKILL.md` and
 `.claude/agents/simulation-judge.md`. These cannot be loaded from
 `node_modules` — Claude Code reads them from the repository — so they are
 copied, not referenced, and **can drift** from the version in this package.
@@ -73,11 +73,18 @@ session's locale. Pass the locale your application runs in — `createChatDriver
 { locale: 'fr' })` — or the run dies as a 15-minute "element not found" with
 nothing pointing at the cause. The default is `'en'`.
 
+**Send recovery.** `sendMessage` bounds its fill/click at `SEND_TIMEOUT_MS`
+(15s) rather than waiting indefinitely. If the first attempt fails — typically
+an overlay left open over the composer — it presses Escape (the ordinary way a
+person dismisses something in their way) and retries once before throwing. It
+never passes `{ force: true }`: punching through an overlay a real user could
+not reach would report a success a person could never have had.
+
 ```ts
 import { test } from '@playwright/test'
 import {
-  createChatDriver, captureGateway, nextUserMessage, isDone,
-  writeEvidence, selectCases, type Transcript, type SimulationCase
+  createChatDriver, chatDriverStrings, captureGateway, nextUserMessage, isDone,
+  writeEvidence, selectCases, createPagePerception, type Transcript, type SimulationCase
 } from '@data-fair/lib-agents-sim'
 
 const cases: SimulationCase[] = [
@@ -89,13 +96,25 @@ for (const simCase of selectCases(cases, [])) {
     const gateway = captureGateway(page)
     await page.goto(simCase.route)
 
-    const chat = createChatDriver(page.frameLocator('iframe'))
+    const locale = 'en' as const
+    const strings = chatDriverStrings(locale)
+    const chat = createChatDriver(page.frameLocator('iframe'), { locale })
     const conversation: Array<{ role: string, text: string }> = []
+    // Lets the persona look at, click and type into the real page instead of
+    // guessing at what is on screen — see "Give the persona eyes" below.
+    // offLimits is not optional in practice: without it the persona can (and
+    // will) click into the composer and press Send itself, double-sending its
+    // message on top of the runner's own send below.
+    const perception = createPagePerception(
+      [{ label: 'page', root: page }],
+      { offLimits: [strings.input, strings.send, strings.stop, strings.reset] }
+    )
     let error: string | undefined
 
     try {
       for (let i = 0; i < simCase.maxTurns; i++) {
-        const message = await nextUserMessage(simCase, conversation, simCase.maxTurns - i)
+        perception.setTurn(i + 1)
+        const message = await nextUserMessage(simCase, conversation, simCase.maxTurns - i, { perception })
         if (isDone(message)) break
         await chat.sendMessage(message)
         await chat.waitForTurn()
@@ -110,7 +129,7 @@ for (const simCase of selectCases(cases, [])) {
       error = err instanceof Error ? err.message : String(err)
     }
 
-    const transcript: Transcript = { case: simCase.name, goal: simCase.goal, persona: simCase.persona, route: simCase.route, conversation, gateway, consoleErrors: [] }
+    const transcript: Transcript = { case: simCase.name, goal: simCase.goal, persona: simCase.persona, route: simCase.route, conversation, gateway, consoleErrors: [], observations: perception.observations }
     // `valid` is derived, never hardcoded: the sidecar exists to tell a run that
     // really happened apart from one that fell over, so that `reportCases` says
     // "invalid (…)" instead of re-reporting the previous run's verdict.
@@ -125,11 +144,71 @@ for (const simCase of selectCases(cases, [])) {
 ```
 
 Then judge each written transcript with the `simulation-judge` sub-agent (via
-the copied `/simulate` skill), and turn the evidence directory into a pass/fail
+the copied `/agents-sim` skill), and turn the evidence directory into a pass/fail
 summary with `reportCases(cases, evidenceDir)` — the host repo's own report
 script decides where cases live and what to do with the failure count it
 returns.
 
+### Give the persona eyes
+
+`createPagePerception(roots, opts?)` gives the simulated user a
+`look`/`click`/`type` MCP tool set over the real Playwright page(s), so it can
+check what is actually on screen instead of guessing. Pass one root per
+visible surface — a chat embedded in an iframe has both the host page and the
+frame:
+
+```ts
+const perception = createPagePerception(
+  [
+    { label: 'page', root: page },
+    { label: 'chat panel', root: page.frameLocator('iframe') }
+  ],
+  { offLimits: [strings.input, strings.send, strings.stop, strings.reset] }
+)
+```
+
+**Pass `offLimits`.** It is the second argument's only option, and it is not
+optional in practice: it is the list of accessible names — typically the
+composer's input, send, stop and reset controls, from `chatDriverStrings` — that
+`click`/`type` refuse before even looking the element up. The persona's system
+prompt is told *"the composer will refuse you"* only when this list is
+non-empty (an empty or omitted `offLimits` refuses nothing, silently). Without
+it, the persona can and will type its own message into the composer and press
+Send itself — double-sending on top of the runner's own `chat.sendMessage`
+below, and usually invalidating the run. A `reset` control is worth including
+too: a mid-run click erases the transcript the run exists to produce.
+
+Before each turn, tell it which turn is starting — this stamps every
+observation the persona records during that turn — then pass it through
+`nextUserMessage`'s options so the persona's query gets the tool set:
+
+```ts
+perception.setTurn(i + 1)
+const message = await nextUserMessage(simCase, conversation, simCase.maxTurns - i, { perception })
+```
+
+Every `look`/`click`/`type` call is recorded into `perception.observations` as
+`{ turn, tool, args, result }`; put that array into the transcript's
+`observations` field so the judge can check a visual claim against what was
+actually seen. **Without `perception`, the persona cannot see the page at
+all** — do not write a case or a judge prompt that expects it to notice or
+react to anything visual (a panel opening, a chart rendering, a result
+appearing) unless perception is wired in.
+
+`df-agents-sim-init` copies the `simulation-judge` definition into your repo,
+and the copied version now includes the instruction to check visual claims
+against `observations`. If you already ran `df-agents-sim-init` before this
+was added, re-run `npx df-agents-sim-init --force` to pick it up — otherwise
+your judge keeps trusting unverified visual claims.
+
+**Breaking change in 0.3.0.** `Transcript.observations` is a required field,
+not an optional one — deliberately: an optional field would let a host wire up
+`perception` and forget to add `observations` to its transcript object, and
+ship runs that look valid while the judge sees no evidence at all. Upgrading
+from 0.2.0 means adding `observations: perception?.observations ?? []` (or
+`[]` where perception is not used) to the transcript you build; a TypeScript
+compile error will name the field for you.
+
 ### Where the evidence goes
 
 `writeEvidence(name, transcript, sidecar, dir?)` writes `sim-<name>.json` (the
@@ -141,7 +220,7 @@ from the repository root. Pass `dir` explicitly to put evidence anywhere else,
 and hand the same directory to `reportCases(cases, dir)` so the reader and the
 writer agree.
 
-## Scripts the copied `/simulate` skill expects
+## Scripts the copied `/agents-sim` skill expects
 
 `df-agents-sim-init` copies the skill **verbatim**, and the skill refers to npm
 scripts by the names the origin repository uses. It cannot know yours, so define
@@ -166,5 +245,5 @@ these three in your `package.json` (adjust the paths to your layout):
   on the failure count it returns.
 
 If you prefer different names, edit the copied
-`.claude/skills/simulate/SKILL.md` to match — but remember that a later
+`.claude/skills/agents-sim/SKILL.md` to match — but remember that a later
 `df-agents-sim-init --force` overwrites it.

package/bin/init.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Copies the judge definition and the /simulate skill into the consuming repo's
+ * Copies the judge definition and the /agents-sim skill into the consuming repo's
  * .claude/ directory. They cannot be loaded from node_modules — Claude Code reads
  * them from the repository — so they are copied and can drift. The version is
  * printed so drift is at least detectable.
@@ -14,7 +14,7 @@ const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'u
 const cwd = process.cwd();
 const targets = [
     { from: 'simulation-judge.md', to: path.join(cwd, '.claude', 'agents', 'simulation-judge.md') },
-    { from: 'simulate-skill.md', to: path.join(cwd, '.claude', 'skills', 'simulate', 'SKILL.md') }
+    { from: 'agents-sim-skill.md', to: path.join(cwd, '.claude', 'skills', 'agents-sim', 'SKILL.md') }
 ];
 for (const { from, to } of targets) {
     fs.mkdirSync(path.dirname(to), { recursive: true });

package/chat-driver.d.ts

@@ -20,8 +20,10 @@ export declare function chatDriverStrings(locale: ChatDriverLocale): {
     input: string;
     send: string;
     stop: string;
+    reset: string;
 };
 export declare const TURN_TIMEOUT_MS: number;
+export declare const SEND_TIMEOUT_MS = 15000;
 export declare function createChatDriver(root: ChatRoot, opts?: {
     locale?: ChatDriverLocale;
 }): {

package/chat-driver.js

@@ -16,12 +16,16 @@
 import { expect } from '@playwright/test';
 /**
  * The chat takes its locale from the session (`i18n_lang`), so a host
- * application running in French renders a French composer. These are the only
- * locale-dependent selectors: `readConversation` matches on classes.
+ * application running in French renders a French composer. `reset` is the
+ * header's "Reset conversation" icon button (AgentChatHeader.vue) — its
+ * accessible name comes from the same `t()`-into-`title` pattern as the
+ * composer's own strings, so it is sourced here rather than as a literal at
+ * the call site. These are the only locale-dependent selectors:
+ * `readConversation` matches on classes.
  */
 const STRINGS = {
-    en: { input: 'Type your message...', send: 'Send', stop: 'Stop' },
-    fr: { input: 'Tapez votre message...', send: 'Envoyer', stop: 'Arrêter' }
+    en: { input: 'Type your message...', send: 'Send', stop: 'Stop', reset: 'Reset conversation' },
+    fr: { input: 'Tapez votre message...', send: 'Envoyer', stop: 'Arrêter', reset: 'Réinitialiser la conversation' }
 };
 export function chatDriverStrings(locale) {
     const strings = STRINGS[locale];
@@ -35,12 +39,41 @@ export function chatDriverStrings(locale) {
 // legitimate multi-step turn has no fixed ceiling on total time. This bounds the
 // harness generously rather than recording a slow-but-working turn as a failure.
 export const TURN_TIMEOUT_MS = 10 * 60 * 1000;
+// Bounds a wedged page — e.g. the persona's own click/look/type tools
+// (page-perception.ts) left an overlay open over the composer — so a stuck
+// send fails in seconds rather than retrying against a stable-but-unreachable
+// element until the test runner's own timeout kills the whole case 15 minutes
+// later with no diagnosis. Unrelated to TURN_TIMEOUT_MS, which bounds a
+// legitimately long model turn once the message has actually been sent.
+export const SEND_TIMEOUT_MS = 15000;
 export function createChatDriver(root, opts = {}) {
     const strings = chatDriverStrings(opts.locale ?? 'en');
     return {
         async sendMessage(text) {
-            await root.getByPlaceholder(strings.input).fill(text);
-            await root.getByRole('button', { name: strings.send }).click();
+            const fillAndSend = async () => {
+                await root.getByPlaceholder(strings.input).fill(text, { timeout: SEND_TIMEOUT_MS });
+                await root.getByRole('button', { name: strings.send }).click({ timeout: SEND_TIMEOUT_MS });
+            };
+            try {
+                await fillAndSend();
+            }
+            catch {
+                // Not { force: true }: punching through an overlay a real user could
+                // not reach would make the harness report successes a person could
+                // never have had. Escape is the ordinary way a person dismisses a
+                // dialog that is in their way, so try that and retry once — on a
+                // locator, not `root.keyboard`, since root is a FrameLocator (no
+                // keyboard) when the chat is embedded.
+                await root.locator('body').press('Escape', { timeout: SEND_TIMEOUT_MS }).catch(() => { });
+                try {
+                    await fillAndSend();
+                }
+                catch (secondErr) {
+                    const detail = secondErr instanceof Error ? secondErr.message : String(secondErr);
+                    throw new Error('could not operate the chat composer (fill/send) even after pressing Escape — ' +
+                        `the page may have been left in a modal or scrolled state by the simulated user. Underlying error: ${detail}`);
+                }
+            }
         },
         async waitForTurn(timeoutMs = TURN_TIMEOUT_MS) {
             const stop = root.getByRole('button', { name: strings.stop });

package/index.d.ts

@@ -1,8 +1,10 @@
 export type { SimulationCase, Transcript, RunSidecar } from './types.ts';
 export { createNeutralCwd, scrubEnv, isolationOptions, type Env } from './isolation.ts';
 export { captureGateway, summariseRequest, type GatewayExchange } from './gateway-capture.ts';
-export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE } from './persona.ts';
+export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE, PERSONA_MAX_TURNS, PERCEPTION_INSTRUCTIONS } from './persona.ts';
 export { writeEvidence, evidenceDir } from './transcript.ts';
 export { selectCases } from './cases.ts';
 export { reportCases } from './report.ts';
-export { createChatDriver, type ChatRoot, TURN_TIMEOUT_MS } from './chat-driver.ts';
+export { createChatDriver, chatDriverStrings, type ChatRoot, type ChatDriverLocale, TURN_TIMEOUT_MS, SEND_TIMEOUT_MS } from './chat-driver.ts';
+export { createPagePerception, truncate, SNAPSHOT_CAP, ACTION_TIMEOUT_MS, MCP_SERVER_NAME as PAGE_MCP_SERVER_NAME } from './page-perception.ts';
+export type { PerceptionRoot, Observation, PagePerception } from './page-perception.ts';

package/index.js

@@ -1,7 +1,8 @@
 export { createNeutralCwd, scrubEnv, isolationOptions } from "./isolation.js";
 export { captureGateway, summariseRequest } from "./gateway-capture.js";
-export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE } from "./persona.js";
+export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE, PERSONA_MAX_TURNS, PERCEPTION_INSTRUCTIONS } from "./persona.js";
 export { writeEvidence, evidenceDir } from "./transcript.js";
 export { selectCases } from "./cases.js";
 export { reportCases } from "./report.js";
-export { createChatDriver, TURN_TIMEOUT_MS } from "./chat-driver.js";
+export { createChatDriver, chatDriverStrings, TURN_TIMEOUT_MS, SEND_TIMEOUT_MS } from "./chat-driver.js";
+export { createPagePerception, truncate, SNAPSHOT_CAP, ACTION_TIMEOUT_MS, MCP_SERVER_NAME as PAGE_MCP_SERVER_NAME } from "./page-perception.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-fair/lib-agents-sim",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Primitives for judged browser simulations of the data-fair agents chat, plus a Claude Code bridge exposing the Agent SDK as an OpenAI-compatible provider.",
   "main": "index.js",
   "type": "module",

package/page-perception.d.ts

@@ -0,0 +1,37 @@
+import type { ChatRoot } from './chat-driver.ts';
+export declare const MCP_SERVER_NAME = "page";
+export declare const SNAPSHOT_CAP = 4000;
+export declare const ACTION_TIMEOUT_MS = 15000;
+export type PerceptionRoot = {
+    label: string;
+    root: ChatRoot;
+};
+export type Observation = {
+    turn: number;
+    tool: string;
+    args: unknown;
+    result: string;
+};
+export type PagePerception = {
+    server: {
+        type: 'sdk';
+        name: string;
+        instance: unknown;
+        alwaysLoad: true;
+    };
+    observations: Observation[];
+    setTurn: (turn: number) => void;
+    toolNames: string[];
+    call: (tool: string, args: Record<string, unknown>) => Promise<string>;
+    /**
+     * The names passed as `opts.offLimits`, verbatim (empty when none were).
+     * `persona.ts` reads this to decide whether the composer-refusal sentence in
+     * its system prompt is a true statement — with no offLimits, nothing refuses
+     * anything, so the prompt must not claim otherwise.
+     */
+    offLimits: string[];
+};
+export declare function truncate(text: string): string;
+export declare function createPagePerception(roots: PerceptionRoot[], opts?: {
+    offLimits?: string[];
+}): PagePerception;

package/page-perception.js

@@ -0,0 +1,163 @@
+/**
+ * What the simulated user can perceive and do.
+ *
+ * Three tools, shaped like a person rather than like a test framework: look at
+ * the screen, click something by its visible name, type into a named field.
+ * There is deliberately no evaluate, no raw selector and no DOM access — a
+ * persona that can run JavaScript verifies outcomes no human could, which would
+ * make verdicts wrongly optimistic in exactly the way a blind persona makes them
+ * wrongly pessimistic.
+ *
+ * The handlers run in-process against the runner's live Playwright roots, so
+ * there is one browser and one page. Every call is recorded as an observation,
+ * because a judge cannot otherwise tell a real complaint from an invented one —
+ * including a failed one: `look`/`click`/`type` are all bounded by
+ * `ACTION_TIMEOUT_MS`, so a stuck element is caught and recorded rather than
+ * hanging the case with no evidence ever written.
+ *
+ * `click` and `type` also accept an `offLimits` list of names (e.g. the chat
+ * composer's own input/send/stop): a request naming one is refused, structurally,
+ * before the element is even looked up, instead of relying on an instruction the
+ * persona is free to ignore. This is what keeps "look and act freely, but talk by
+ * replying" (spec §3) an invariant rather than a suggestion.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export const MCP_SERVER_NAME = 'page';
+export const SNAPSHOT_CAP = 4000;
+// Bounds every Playwright call the persona itself makes (look/click/type).
+// Without this, an element Playwright calls visible/enabled/stable but stuck
+// outside the viewport — the exact case a live run hit — waits with no ceiling
+// of its own, wedging the case until the test runner's 15-minute timeout kills
+// it with no diagnosis. 15s mirrors chat-driver.ts's SEND_TIMEOUT_MS: a person
+// does not wait minutes for something to become clickable, and a timeout here
+// must surface through the existing try/catch as a recorded observation
+// instead of an unrecorded hang.
+export const ACTION_TIMEOUT_MS = 15000;
+export function truncate(text) {
+    return text.length <= SNAPSHOT_CAP ? text : text.slice(0, SNAPSHOT_CAP) + '…[truncated]';
+}
+const TOOLS = [
+    {
+        name: 'look',
+        description: 'Look at the screen. Returns what is currently visible, as an accessibility outline of the page. Use this before saying anything about what you can or cannot see.',
+        inputSchema: { type: 'object', properties: {} }
+    },
+    {
+        name: 'click',
+        description: 'Click something by the visible text or label on it, exactly as a person would point at it.',
+        inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'The visible text or accessible name of what to click' } }, required: ['name'] }
+    },
+    {
+        name: 'type',
+        description: 'Type into a field identified by its visible label.',
+        inputSchema: { type: 'object', properties: { name: { type: 'string' }, text: { type: 'string' } }, required: ['name', 'text'] }
+    }
+];
+export function createPagePerception(roots, opts = {}) {
+    const observations = [];
+    let turn = 0;
+    // Equality, not substring: the persona copies names verbatim out of the aria
+    // snapshot it just looked at, so an exact (trimmed, case-insensitive) match is
+    // enough to catch it — while substring matching on a short off-limits word
+    // like "Send" would also block an unrelated "Send report" button.
+    const offLimits = new Set((opts.offLimits ?? []).map(n => n.trim().toLowerCase()));
+    const isOffLimits = (name) => offLimits.has(name.trim().toLowerCase());
+    const OFF_LIMITS_RESULT = 'the composer is not yours to operate — reply with your message and the runner will send it for you';
+    const look = async () => {
+        const parts = [];
+        for (const { label, root } of roots) {
+            let snap = '';
+            try {
+                snap = await root.locator('body').ariaSnapshot({ timeout: ACTION_TIMEOUT_MS });
+            }
+            catch (err) {
+                snap = `(could not read: ${err instanceof Error ? err.message : String(err)})`;
+            }
+            // Capped per root, not on the joined result: otherwise a large first
+            // root can consume the whole budget and a second root (e.g. an embedded
+            // `## chat panel`) disappears from the log entirely, with no marker
+            // hinting it was ever there.
+            parts.push(truncate(`## ${label}\n${snap}`));
+        }
+        return parts.join('\n\n');
+    };
+    const firstMatch = async (finders) => {
+        for (const find of finders) {
+            try {
+                const loc = find();
+                if (await loc.count() > 0)
+                    return loc;
+            }
+            catch { /* a finder that throws simply does not match */ }
+        }
+        return null;
+    };
+    const click = async (name) => {
+        if (isOffLimits(name))
+            return OFF_LIMITS_RESULT;
+        for (const { root } of roots) {
+            const loc = await firstMatch([
+                () => root.getByRole('button', { name }).first(),
+                () => root.getByRole('link', { name }).first(),
+                () => root.getByText(name).first()
+            ]);
+            if (loc) {
+                try {
+                    await loc.click({ timeout: ACTION_TIMEOUT_MS });
+                    return `clicked "${name}"`;
+                }
+                catch (err) {
+                    return `could not click "${name}": ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
+        }
+        return `could not find anything called "${name}" to click`;
+    };
+    const type = async (name, text) => {
+        if (isOffLimits(name))
+            return OFF_LIMITS_RESULT;
+        for (const { root } of roots) {
+            const loc = await firstMatch([
+                () => root.getByRole('textbox', { name }).first(),
+                () => root.getByLabel(name).first()
+            ]);
+            if (loc) {
+                try {
+                    await loc.fill(text, { timeout: ACTION_TIMEOUT_MS });
+                    return `typed into "${name}"`;
+                }
+                catch (err) {
+                    return `could not type into "${name}": ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
+        }
+        return `could not find a field called "${name}"`;
+    };
+    const call = async (tool, args) => {
+        let result;
+        if (tool === 'look')
+            result = await look();
+        else if (tool === 'click')
+            result = await click(String(args.name ?? ''));
+        else if (tool === 'type')
+            result = await type(String(args.name ?? ''), String(args.text ?? ''));
+        else
+            result = `unknown tool: ${tool}`;
+        observations.push({ turn, tool, args, result });
+        return result;
+    };
+    const instance = new Server({ name: MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
+    instance.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    instance.setRequestHandler(CallToolRequestSchema, async (req) => ({
+        content: [{ type: 'text', text: await call(req.params.name, (req.params.arguments ?? {})) }]
+    }));
+    return {
+        server: { type: 'sdk', name: MCP_SERVER_NAME, instance, alwaysLoad: true },
+        observations,
+        setTurn: (n) => { turn = n; },
+        toolNames: TOOLS.map(t => t.name),
+        call,
+        offLimits: opts.offLimits ?? []
+    };
+}

package/persona.d.ts

@@ -1,7 +1,17 @@
 import type { SimulationCase } from './types.ts';
+import type { PagePerception } from './page-perception.ts';
 export declare const DONE = "DONE";
+export declare const PERSONA_MAX_TURNS = 25;
+export declare const PERCEPTION_INSTRUCTIONS = "You can look at the screen yourself with the look tool, and you can click and type\non the page. Before you say anything about what is or is not on the screen, look.\nNever claim you cannot see something you have not looked for.";
 export declare function isDone(message: string): boolean;
-export declare function personaSystemPrompt(c: SimulationCase): string;
+export declare function personaSystemPrompt(c: SimulationCase, perceptionEnabled?: boolean, offLimitsActive?: boolean): string;
+/**
+ * The SDK's `query`, narrowed to what the persona uses. Injectable (mirrors
+ * `BridgeQuery` in bridge/server.ts) so a test can observe the options actually
+ * handed over — including the perception wiring — without a network call or a
+ * live model.
+ */
+export type PersonaQuery = (typeof import('@anthropic-ai/claude-agent-sdk'))['query'];
 export declare function personaPrompt(conversation: Array<{
     role: string;
     text: string;
@@ -9,4 +19,7 @@ export declare function personaPrompt(conversation: Array<{
 export declare function nextUserMessage(c: SimulationCase, conversation: Array<{
     role: string;
     text: string;
-}>, turnsLeft: number): Promise<string>;
+}>, turnsLeft: number, opts?: {
+    perception?: PagePerception;
+    query?: PersonaQuery;
+}): Promise<string>;

package/persona.js

@@ -9,8 +9,41 @@
  */
 import { createNeutralCwd, isolationOptions } from "./isolation.js";
 import { MISSING_SDK_MESSAGE, isMissingSdkError } from "./missing-sdk.js";
+import { MCP_SERVER_NAME } from "./page-perception.js";
 export const DONE = 'DONE';
 let neutralCwd;
+// The persona looks and acts before replying, so one turn is not enough:
+// look → act → look → reply, with room to spare.
+//
+// Tuned from real runs, three times, and the number follows the shape of the
+// work rather than a guess. It is the budget for ONE message: how many tool
+// calls the person may make before answering.
+//
+// 6 was the cost of look/click/look/click/look — the most ordinary thing a
+// person does on a multi-step page — leaving nothing for the reply.
+//
+// 12 was exactly the length of a guided workflow. In a run of the dataset
+// creation case the assistant handed over the whole procedure in one message
+// and the person executed it in one turn: click Create, choose the type, skip
+// the init step, type a title, tick an option, continue — with a look between
+// each, twelve calls of purposeful work and nothing wasted. The reply then had
+// no budget left and the run was discarded.
+//
+// So a guided scenario costs roughly (steps × 2) + 1, and the assistant decides
+// how many steps it hands over at once. 25 covers a full wizard driven in a
+// single message, with the verification looks and the reply, and still stops a
+// genuinely lost persona long before it could wander for minutes.
+export const PERSONA_MAX_TURNS = 25;
+export const PERCEPTION_INSTRUCTIONS = `You can look at the screen yourself with the look tool, and you can click and type
+on the page. Before you say anything about what is or is not on the screen, look.
+Never claim you cannot see something you have not looked for.`;
+// Appended only when the caller actually configured createPagePerception's
+// offLimits — otherwise nothing refuses the composer and this sentence would be
+// a promise the harness does not keep (the persona types its message in itself,
+// double-sending). See lib-sim/README.md, "Give the persona eyes".
+const COMPOSER_OFF_LIMITS_INSTRUCTIONS = `The message box and its Send button will refuse you if you try to click or type into
+them — that part of the page is not yours to operate. To talk to the assistant, just
+reply with your message; the runner types and sends it for you.`;
 export function isDone(message) {
     if (!message)
         return false;
@@ -29,8 +62,8 @@ export function isDone(message) {
     // Only true if it is exactly DONE, not a sentence containing the word
     return normalized === DONE;
 }
-export function personaSystemPrompt(c) {
-    return [
+export function personaSystemPrompt(c, perceptionEnabled = false, offLimitsActive = false) {
+    const lines = [
         c.persona,
         '',
         `What you want: ${c.goal}`,
@@ -43,7 +76,13 @@ export function personaSystemPrompt(c) {
         '',
         'Reply with ONLY the message you would type next — no quotes, no narration, no stage directions.',
         `When you have what you wanted, or you are convinced you will not get it, reply with exactly ${DONE} and nothing else.`
-    ].join('\n');
+    ];
+    if (perceptionEnabled) {
+        lines.push('', PERCEPTION_INSTRUCTIONS);
+        if (offLimitsActive)
+            lines.push('', COMPOSER_OFF_LIMITS_INSTRUCTIONS);
+    }
+    return lines.join('\n');
 }
 export function personaPrompt(conversation, turnsLeft) {
     if (conversation.length === 0)
@@ -60,29 +99,51 @@ export function personaPrompt(conversation, turnsLeft) {
         `Write your next message, or ${DONE} if you are finished.${warning}`
     ].join('\n');
 }
-export async function nextUserMessage(c, conversation, turnsLeft) {
-    // Loaded here, not at module top level, so importing the package barrel
-    // never requires the Agent SDK — it is an optional peer, and a consumer who
-    // only wants the harness primitives must not pay for it. This is the only
-    // place in the exported surface that reaches for it at runtime.
-    let query;
-    try {
-        ({ query } = await import('@anthropic-ai/claude-agent-sdk'));
+export async function nextUserMessage(c, conversation, turnsLeft, opts) {
+    let runQuery;
+    if (opts?.query) {
+        runQuery = opts.query;
     }
-    catch (err) {
-        if (isMissingSdkError(err))
-            throw new Error(MISSING_SDK_MESSAGE);
-        throw err;
+    else {
+        // Loaded here, not at module top level, so importing the package barrel
+        // never requires the Agent SDK — it is an optional peer, and a consumer who
+        // only wants the harness primitives must not pay for it. This is the only
+        // place in the exported surface that reaches for it at runtime.
+        try {
+            ({ query: runQuery } = await import('@anthropic-ai/claude-agent-sdk'));
+        }
+        catch (err) {
+            if (isMissingSdkError(err))
+                throw new Error(MISSING_SDK_MESSAGE);
+            throw err;
+        }
     }
     neutralCwd ??= createNeutralCwd();
     let text = '';
-    for await (const msg of query({
+    for await (const msg of runQuery({
         prompt: personaPrompt(conversation, turnsLeft),
         options: {
             ...isolationOptions(neutralCwd),
             model: process.env.SIM_USER_MODEL ?? 'haiku',
-            systemPrompt: personaSystemPrompt(c),
-            maxTurns: 1
+            systemPrompt: personaSystemPrompt(c, !!opts?.perception, !!opts?.perception?.offLimits.length),
+            // Unconditional: a caller with no perception registers no mcpServers, so
+            // the persona has no tool to call and the loop still ends after the one
+            // assistant turn a blind persona always took — the higher cap only ever
+            // matters once look/click/type are actually wired in below.
+            maxTurns: PERSONA_MAX_TURNS,
+            ...(opts?.perception
+                ? {
+                    // page-perception.ts deliberately builds the LOW-LEVEL MCP `Server`
+                    // (server/index.js), not the high-level `McpServer` helper the SDK's
+                    // `McpServerConfig` type expects — the low-level API accepts raw JSON
+                    // Schema for tool inputs, while `McpServer` demands Zod (the same
+                    // choice bridge/tool-server.ts makes, cast at the same boundary in
+                    // bridge/server.ts). The two classes are structurally unrelated, so
+                    // no tighter typing of `instance` would remove this cast.
+                    mcpServers: { [MCP_SERVER_NAME]: opts.perception.server },
+                    allowedTools: opts.perception.toolNames.map(n => `mcp__${MCP_SERVER_NAME}__${n}`)
+                }
+                : {})
         }
     })) {
         if (msg.type === 'assistant') {

package/templates/{simulate-skill.md → agents-sim-skill.md}

@@ -1,5 +1,5 @@
 ---
-name: simulate
+name: agents-sim
 description: Run the scenario simulations - drive real browser conversations with a simulated user, then dispatch a judge per transcript. Use when asked to run the simulations, or after changing a system prompt, a tool description, or the chat orchestration.
 ---
 
@@ -11,12 +11,16 @@ transcript.
 
 ## Before you start
 
-Three things must be true, and each fails confusingly if it is not:
+Four things must be true, and each fails confusingly if it is not:
 
 1. The dev stack is up — `bash dev/status.sh`.
 2. The workspace packages are built — `ls lib-vue/*.js lib-vuetify/*.js`. If they
    are missing, e2e-style runs fail with "element not found".
-3. The bridge is running — `npm run dev-bridge`. The runner checks this and says so.
+3. `lib-sim` is built — `npm -w @data-fair/lib-agents-sim run build`.
+   `simulations/` imports it by package name, not by relative path, so a stale
+   build silently runs the OLD code and still reports the run valid — the exact
+   failure mode this subsystem exists to catch.
+4. The bridge is running — `npm run dev-bridge`. The runner checks this and says so.
 
 Ask the user to start anything that is down. Never start or stop dev processes yourself.
 

package/templates/simulation-judge.md

@@ -1,6 +1,6 @@
 ---
 name: simulation-judge
-description: Judge one scenario simulation transcript and return a JSON verdict. Use when asked to verdict a simulation run produced by the /simulate skill.
+description: Judge one scenario simulation transcript and return a JSON verdict. Use when asked to verdict a simulation run produced by the /agents-sim skill.
 tools: Read
 ---
 
@@ -15,6 +15,15 @@ The transcript holds:
 - `gateway` — every request the page made, carrying the tools it offered and the
   tool calls the assistant actually made
 - `consoleErrors` — browser errors during the run
+- `observations` — what the person actually looked at and did, recorded per turn:
+  `{ turn, tool, args, result }`. `look` returns the accessibility outline of the
+  screen at that moment.
+
+A claim about what is on screen must be supported by a preceding `look` in
+`observations`. A persona asserting a visual fact it never observed is a HARNESS
+fault, not product friction — say so plainly in `notes` and do not count it as a
+friction point. This has happened: a run once had the person insist a panel was
+closed having never looked, and the judge reported it as a product failure.
 
 `gateway` records what the browser SENT to the server, and each request carries
 the whole conversation so far — so the assistant's FINAL reply of a conversation

package/types.d.ts

@@ -2,6 +2,7 @@
  * The shapes a host repo needs to write cases and read evidence.
  */
 import type { GatewayExchange } from './gateway-capture.ts';
+import type { Observation } from './page-perception.ts';
 export type SimulationCase = {
     /** Evidence files are named after this; keep it filesystem-safe. */
     name: string;
@@ -24,6 +25,7 @@ export type Transcript = {
     }>;
     gateway: GatewayExchange[];
     consoleErrors: string[];
+    observations: Observation[];
 };
 export type RunSidecar = {
     case: string;