@itsthelore/proofkeeper 2026.6.0

package/dist/agent/drive.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The autonomous drive — Proofkeeper Initiative 2's drive phase.
+ *
+ * A bring-your-own-model agent loop: it navigates to the start URL, observes
+ * the live page, asks the {@link ModelClient} what to do next, dispatches the
+ * model's tool calls through the {@link Recorder}, observes the result, and
+ * repeats until the model finishes (or a step budget is hit). The Recorder
+ * records each action only after it succeeds, so the produced
+ * {@link RecordedSession} is — by construction — a faithful sequence that held,
+ * ready for the deterministic compiler and the fidelity gate.
+ *
+ * Proofkeeper bundles no model (ADR-035, ADR-002): the caller supplies the
+ * ModelClient. This loop is the autonomous runtime; the model is the brain.
+ */
+import type { Page } from "@playwright/test";
+import type { RecordedSession } from "../compiler/actions.js";
+import type { ModelClient } from "./model.js";
+export interface DriveOptions {
+    /** Capability under verification; threads into the recorded session. */
+    capabilityId?: string;
+    /** Human title for the emitted test. */
+    title: string;
+    /** Product entry point; the driver navigates here first. */
+    startUrl: string;
+    /** What the model should accomplish and assert on the product. */
+    goal: string;
+    /** Maximum model turns before the drive gives up. Defaults to 12. */
+    maxSteps?: number;
+    /** Reasons earlier attempts at this capability failed, to steer away from them. */
+    priorFailures?: string[];
+    /** When set, run a planning turn first and record a Markdown test plan. */
+    plan?: boolean;
+}
+export interface DriveResult {
+    /** The recorded session, ready to compile. */
+    session: RecordedSession;
+    /** True if the model signalled completion (vs hitting the step budget). */
+    finished: boolean;
+    /** Number of model turns taken. */
+    steps: number;
+    /** The Markdown test plan, when a planning turn ran. */
+    plan?: string;
+}
+export declare class AutonomousDriver {
+    private readonly page;
+    private readonly model;
+    private readonly options;
+    constructor(page: Page, model: ModelClient, options: DriveOptions);
+    drive(): Promise<DriveResult>;
+}
+/** Convenience wrapper: construct a driver and run it. */
+export declare function runDrive(page: Page, model: ModelClient, options: DriveOptions): Promise<DriveResult>;
+//# sourceMappingURL=drive.d.ts.map

package/dist/agent/drive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../src/agent/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,KAAK,EAAE,WAAW,EAA0B,MAAM,YAAY,CAAC;AAiBtE,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,OAAO,EAAE,eAAe,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA2GD,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,YAAY;IAGlC,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;CAqFpC;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC,CAEtB"}

package/dist/agent/drive.js

@@ -0,0 +1,194 @@
+/**
+ * The autonomous drive — Proofkeeper Initiative 2's drive phase.
+ *
+ * A bring-your-own-model agent loop: it navigates to the start URL, observes
+ * the live page, asks the {@link ModelClient} what to do next, dispatches the
+ * model's tool calls through the {@link Recorder}, observes the result, and
+ * repeats until the model finishes (or a step budget is hit). The Recorder
+ * records each action only after it succeeds, so the produced
+ * {@link RecordedSession} is — by construction — a faithful sequence that held,
+ * ready for the deterministic compiler and the fidelity gate.
+ *
+ * Proofkeeper bundles no model (ADR-035, ADR-002): the caller supplies the
+ * ModelClient. This loop is the autonomous runtime; the model is the brain.
+ */
+import { Recorder } from "../compiler/recorder.js";
+import { observePage, renderObservation, createPageMonitor } from "./observe.js";
+import { DRIVE_TOOLS, LOCATOR_GUIDANCE, TERMINAL_GUIDANCE, HTTP_GUIDANCE, parseLocator, parseRunCommand, parseExpectOutput, parseExpectExit, parseRequest, parseExpectStatus, parseExpectJson, } from "./tools.js";
+const DEFAULT_MAX_STEPS = 12;
+/** Instruction for the optional planning turn (a no-tools text response). */
+const PLAN_INSTRUCTION = "Before acting, write a short Markdown test plan: the steps you will take to verify " +
+    "this capability and the observable outcomes you will assert. Respond with the plan only — " +
+    "no tool calls.";
+function systemPrompt(goal, priorFailures = []) {
+    const lines = [
+        "You are Proofkeeper's autonomous QA agent. You drive a product like a",
+        "developer to verify a capability, using only the provided tools — a browser",
+        "and a terminal. Work in small steps: observe, take an action, observe again.",
+        "Assert every observable outcome (expect_text / expect_visible for the page,",
+        "expect_output / expect_exit for the terminal) — those become the committed",
+        "test. When the capability is driven and asserted, call finish.",
+        "",
+        `Goal: ${goal}`,
+    ];
+    if (priorFailures.length > 0) {
+        lines.push("", "Earlier attempts at this capability failed for these reasons — do not", "repeat them; choose a more robust path or more stable assertions:", ...priorFailures.map((r) => `- ${r}`));
+    }
+    lines.push("", LOCATOR_GUIDANCE, "", TERMINAL_GUIDANCE, "", HTTP_GUIDANCE);
+    return lines.join("\n");
+}
+/** Dispatch one tool call to the recorder. Records only on success. */
+async function dispatch(recorder, call) {
+    try {
+        switch (call.name) {
+            case "navigate":
+                await recorder.goto(String(call.arguments["url"]));
+                return { ok: true };
+            case "click":
+                await recorder.click(parseLocator(call.arguments));
+                return { ok: true };
+            case "fill":
+                await recorder.fill(parseLocator(call.arguments), String(call.arguments["value"]));
+                return { ok: true };
+            case "check":
+                await recorder.check(parseLocator(call.arguments));
+                return { ok: true };
+            case "press":
+                await recorder.press(parseLocator(call.arguments), String(call.arguments["key"]));
+                return { ok: true };
+            case "expect_text":
+                await recorder.expectText(parseLocator(call.arguments), String(call.arguments["text"]));
+                return { ok: true };
+            case "expect_visible":
+                await recorder.expectVisible(parseLocator(call.arguments));
+                return { ok: true };
+            case "run_command": {
+                const { command, cwd } = parseRunCommand(call.arguments);
+                const r = await recorder.run(command, cwd !== undefined ? { cwd } : {});
+                const parts = [
+                    r.stdout.trim() && `stdout: ${r.stdout.trim()}`,
+                    r.stderr.trim() && `stderr: ${r.stderr.trim()}`,
+                    `exit: ${r.code}`,
+                ].filter(Boolean);
+                return { ok: true, detail: `$ ${command}\n${parts.join("\n")}` };
+            }
+            case "expect_output":
+                await recorder.expectOutput(parseExpectOutput(call.arguments));
+                return { ok: true };
+            case "expect_exit":
+                await recorder.expectExit(parseExpectExit(call.arguments));
+                return { ok: true };
+            case "request": {
+                const input = parseRequest(call.arguments);
+                const res = await recorder.request(input);
+                const snippet = res.body.length > 500 ? `${res.body.slice(0, 500)}…` : res.body;
+                return { ok: true, detail: `${input.method} ${input.url}\nstatus: ${res.status}\nbody: ${snippet}` };
+            }
+            case "expect_status":
+                await recorder.expectStatus(parseExpectStatus(call.arguments));
+                return { ok: true };
+            case "expect_json": {
+                const { path, equals } = parseExpectJson(call.arguments);
+                await recorder.expectJson(path, equals);
+                return { ok: true };
+            }
+            case "finish":
+                return { ok: true, finished: true };
+            default:
+                return { ok: false, error: `unknown tool '${call.name}'` };
+        }
+    }
+    catch (err) {
+        // The action failed against the real page, so the recorder did NOT record
+        // it. Report the failure back to the model so it can adapt.
+        return { ok: false, error: err.message };
+    }
+}
+export class AutonomousDriver {
+    page;
+    model;
+    options;
+    constructor(page, model, options) {
+        this.page = page;
+        this.model = model;
+        this.options = options;
+    }
+    async drive() {
+        const recorder = new Recorder(this.page, {
+            capabilityId: this.options.capabilityId,
+            title: this.options.title,
+            startUrl: this.options.startUrl,
+        });
+        // Seed the session at the known entry point, then let the model take over.
+        await recorder.goto(this.options.startUrl);
+        // Subscribe to console and network events; merge the recent window into each
+        // observation so the model sees execution feedback, not just the DOM.
+        const monitor = createPageMonitor(this.page);
+        const observe = async () => renderObservation({
+            ...(await observePage(this.page)),
+            console: [...monitor.console],
+            network: [...monitor.network],
+        });
+        const transcript = [
+            { role: "system", content: systemPrompt(this.options.goal, this.options.priorFailures) },
+            {
+                role: "user",
+                content: `You are on the start page.\n\n${await observe()}`,
+            },
+        ];
+        // Optional planning turn: ask for a Markdown test plan (no tools → text),
+        // record it, and feed it back as context so the drive follows its own plan.
+        let plan;
+        if (this.options.plan) {
+            const response = await this.model.complete({
+                transcript: [...transcript, { role: "user", content: PLAN_INSTRUCTION }],
+                tools: [],
+            });
+            const text = response.done?.trim();
+            if (text) {
+                plan = text;
+                transcript.push({ role: "assistant", content: `Test plan:\n${text}` });
+            }
+        }
+        const maxSteps = this.options.maxSteps ?? DEFAULT_MAX_STEPS;
+        let finished = false;
+        let steps = 0;
+        while (steps < maxSteps) {
+            steps++;
+            const response = await this.model.complete({ transcript, tools: [...DRIVE_TOOLS] });
+            const calls = response.toolCalls ?? [];
+            if (calls.length === 0) {
+                // The model stopped acting; treat a `done` message as completion.
+                finished = response.done !== undefined;
+                break;
+            }
+            transcript.push({ role: "assistant", content: JSON.stringify(calls) });
+            const outcomes = [];
+            let stop = false;
+            for (const call of calls) {
+                const result = await dispatch(recorder, call);
+                if (result.finished) {
+                    finished = true;
+                    stop = true;
+                    break;
+                }
+                outcomes.push(result.ok
+                    ? `ok: ${call.name}${result.detail ? `\n${result.detail}` : ""}`
+                    : `ERROR ${call.name}: ${result.error}`);
+            }
+            if (stop)
+                break;
+            transcript.push({ role: "user", content: `Results:\n${outcomes.join("\n")}\n\n${await observe()}` });
+        }
+        monitor.dispose();
+        const session = recorder.recording();
+        if (plan !== undefined)
+            session.plan = plan;
+        return { session, finished, steps, ...(plan !== undefined ? { plan } : {}) };
+    }
+}
+/** Convenience wrapper: construct a driver and run it. */
+export function runDrive(page, model, options) {
+    return new AutonomousDriver(page, model, options).drive();
+}
+//# sourceMappingURL=drive.js.map

package/dist/agent/drive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive.js","sourceRoot":"","sources":["../../src/agent/drive.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The compile→fidelity→run pipeline — Proofkeeper Initiatives 2–4 wired.
+ *
+ * The DRIVE phase (a BYO-model agent calling the {@link Recorder} to produce a
+ * {@link RecordedSession}) is upstream and supplied by the caller; this keeps
+ * the loop honest about what is autonomous today and what is not. Given a
+ * recorded session, the loop compiles it ({@link Compiler}), gates the
+ * candidate on fidelity ({@link assessFidelity}), and runs the accepted test
+ * across targets ({@link Runner}).
+ */
+import type { RecordedSession } from "../compiler/actions.js";
+import type { CandidateTest, Compiler } from "../compiler/types.js";
+import { type FidelityVerdict } from "../fidelity/gate.js";
+import type { Runner, RunResult, RunTarget } from "../runner/types.js";
+export interface AgentLoopDeps {
+    compiler: Compiler;
+    runner: Runner;
+}
+export interface AgentLoopOptions {
+    /** The recorded drive session to compile (produced upstream by a Recorder). */
+    session: RecordedSession;
+    /** Stability target and N for the fidelity gate. */
+    fidelity: {
+        n: number;
+        target: RunTarget;
+    };
+    /** Targets the accepted suite runs against. */
+    runTargets: RunTarget[];
+}
+export interface AgentLoopResult {
+    candidate: CandidateTest;
+    verdict: FidelityVerdict;
+    /** Only populated when the candidate passed the fidelity gate. */
+    runResults: RunResult[];
+}
+/**
+ * Compile a recorded session, gate it on fidelity, and run the accepted test.
+ */
+export declare function runAgentLoop(deps: AgentLoopDeps, options: AgentLoopOptions): Promise<AgentLoopResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/agent/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,OAAO,EAAE,eAAe,CAAC;IACzB,oDAAoD;IACpD,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC;IAC3C,+CAA+C;IAC/C,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,eAAe,CAAC;IACzB,kEAAkE;IAClE,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/dist/agent/loop.js

@@ -0,0 +1,29 @@
+/**
+ * The compile→fidelity→run pipeline — Proofkeeper Initiatives 2–4 wired.
+ *
+ * The DRIVE phase (a BYO-model agent calling the {@link Recorder} to produce a
+ * {@link RecordedSession}) is upstream and supplied by the caller; this keeps
+ * the loop honest about what is autonomous today and what is not. Given a
+ * recorded session, the loop compiles it ({@link Compiler}), gates the
+ * candidate on fidelity ({@link assessFidelity}), and runs the accepted test
+ * across targets ({@link Runner}).
+ */
+import { assessFidelity } from "../fidelity/gate.js";
+/**
+ * Compile a recorded session, gate it on fidelity, and run the accepted test.
+ */
+export async function runAgentLoop(deps, options) {
+    // 1. COMPILE — reduce the recorded session to a candidate test (the moat).
+    const candidate = await deps.compiler.compile(options.session);
+    // 2. FIDELITY — accept only if it re-runs green and stable N times.
+    const verdict = await assessFidelity(deps.runner, candidate, {
+        n: options.fidelity.n,
+        target: options.fidelity.target,
+    });
+    // 3. RUN — fan the accepted test across targets; quarantine if unstable.
+    const runResults = verdict.stable
+        ? await deps.runner.run([candidate], { targets: options.runTargets })
+        : [];
+    return { candidate, verdict, runResults };
+}
+//# sourceMappingURL=loop.js.map

package/dist/agent/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAwB3E;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAmB,EACnB,OAAyB;IAEzB,2EAA2E;IAC3E,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/D,oEAAoE;IACpE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE;QAC3D,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM;KAChC,CAAC,CAAC;IAEH,yEAAyE;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM;QAC/B,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QACrE,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC"}

package/dist/agent/model.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The bring-your-own-model boundary — Proofkeeper Initiative 2.
+ *
+ * No model or inference ships with Proofkeeper (ADR-035, ADR-002): the agent
+ * runtime lives here, but the *model* is supplied by the caller. This is the
+ * minimal interface the drive loop needs. Adapters for specific providers live
+ * outside core and are the caller's choice.
+ */
+/** A tool the agent may call while driving a product (browser/terminal action). */
+export interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A single turn's request to the model: the running transcript plus tools. */
+export interface ModelRequest {
+    /** Prior transcript, oldest first. Free-form, provider-shaped by the adapter. */
+    transcript: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+    /**
+     * Tools the model may invoke this turn. `inputSchema` is a JSON Schema for
+     * the tool's arguments; adapters forward it to providers that require one
+     * (e.g. the Anthropic Messages API's `input_schema`).
+     */
+    tools: {
+        name: string;
+        description: string;
+        inputSchema?: Record<string, unknown>;
+    }[];
+}
+/** The model's decision for a turn: either act (tool calls) or stop (text). */
+export interface ModelResponse {
+    /** Tool calls to execute, if any. */
+    toolCalls?: ToolCall[];
+    /** Terminal assistant message when the model decides the session is done. */
+    done?: string;
+}
+/** A caller-supplied model. Proofkeeper bundles none. */
+export interface ModelClient {
+    complete(request: ModelRequest): Promise<ModelResponse>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/agent/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,UAAU,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzE;;;;OAIG;IACH,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;CACvF;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzD"}

package/dist/agent/model.js

@@ -0,0 +1,10 @@
+/**
+ * The bring-your-own-model boundary — Proofkeeper Initiative 2.
+ *
+ * No model or inference ships with Proofkeeper (ADR-035, ADR-002): the agent
+ * runtime lives here, but the *model* is supplied by the caller. This is the
+ * minimal interface the drive loop needs. Adapters for specific providers live
+ * outside core and are the caller's choice.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/agent/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/agent/observe.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Page observation — how the autonomous drive lets the model perceive state.
+ *
+ * Each turn the driver hands the model a compact snapshot of the live page: its
+ * URL and title, the visible text, and Playwright's accessibility (ARIA) tree —
+ * the same structure that makes role/name locators resilient. The model decides
+ * its next action from this; the driver never decides for it.
+ *
+ * Console messages and network responses are *events*, not snapshot state, so a
+ * {@link PageMonitor} subscribes to them during the drive and the driver merges
+ * the most recent of each into the observation (the Playwright-MCP execution-
+ * feedback context). This feedback is observation only — it is never recorded as
+ * a test action.
+ */
+import type { Page } from "@playwright/test";
+export interface PageObservation {
+    url: string;
+    title: string;
+    /** Body innerText — the visible text content. */
+    text: string;
+    /** Playwright ARIA snapshot of the body — roles and accessible names. */
+    aria: string;
+    /** Recent console messages (`[type] text`), most recent last. */
+    console?: string[];
+    /** Recent network responses (`status method url`), most recent last. */
+    network?: string[];
+}
+export declare function observePage(page: Page): Promise<PageObservation>;
+/** Render an observation as the text block fed to the model. */
+export declare function renderObservation(o: PageObservation): string;
+/** A live subscription to a page's console and network events, bounded to a recent window. */
+export interface PageMonitor {
+    /** Recent console messages (`[type] text`), most recent last. */
+    readonly console: string[];
+    /** Recent network responses (`status method url`), most recent last. */
+    readonly network: string[];
+    /** Remove the event listeners. */
+    dispose(): void;
+}
+/**
+ * Subscribe to a page's console and network events, keeping the most recent
+ * `limit` (default 20) of each. The driver creates one after navigating and
+ * disposes it when the drive ends.
+ */
+export declare function createPageMonitor(page: Page, options?: {
+    limit?: number;
+}): PageMonitor;
+//# sourceMappingURL=observe.d.ts.map

package/dist/agent/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/agent/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAkB,IAAI,EAAY,MAAM,kBAAkB,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAQtE;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAU5D;AAED,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,WAAW,CAoB3F"}

package/dist/agent/observe.js

@@ -0,0 +1,65 @@
+/**
+ * Page observation — how the autonomous drive lets the model perceive state.
+ *
+ * Each turn the driver hands the model a compact snapshot of the live page: its
+ * URL and title, the visible text, and Playwright's accessibility (ARIA) tree —
+ * the same structure that makes role/name locators resilient. The model decides
+ * its next action from this; the driver never decides for it.
+ *
+ * Console messages and network responses are *events*, not snapshot state, so a
+ * {@link PageMonitor} subscribes to them during the drive and the driver merges
+ * the most recent of each into the observation (the Playwright-MCP execution-
+ * feedback context). This feedback is observation only — it is never recorded as
+ * a test action.
+ */
+export async function observePage(page) {
+    const body = page.locator("body");
+    const [title, text, aria] = await Promise.all([
+        page.title().catch(() => ""),
+        body.innerText().catch(() => ""),
+        body.ariaSnapshot().catch(() => ""),
+    ]);
+    return { url: page.url(), title, text: text.trim(), aria: aria.trim() };
+}
+/** Render an observation as the text block fed to the model. */
+export function renderObservation(o) {
+    const blocks = [
+        `URL: ${o.url}`,
+        `Title: ${o.title}`,
+        `Visible text:\n${o.text}`,
+        `Accessibility tree:\n${o.aria}`,
+    ];
+    if (o.console && o.console.length > 0)
+        blocks.push(`Console:\n${o.console.join("\n")}`);
+    if (o.network && o.network.length > 0)
+        blocks.push(`Network:\n${o.network.join("\n")}`);
+    return blocks.join("\n\n");
+}
+/**
+ * Subscribe to a page's console and network events, keeping the most recent
+ * `limit` (default 20) of each. The driver creates one after navigating and
+ * disposes it when the drive ends.
+ */
+export function createPageMonitor(page, options = {}) {
+    const limit = options.limit ?? 20;
+    const consoleBuf = [];
+    const networkBuf = [];
+    const push = (buf, line) => {
+        buf.push(line);
+        if (buf.length > limit)
+            buf.shift();
+    };
+    const onConsole = (msg) => push(consoleBuf, `[${msg.type()}] ${msg.text()}`);
+    const onResponse = (res) => push(networkBuf, `${res.status()} ${res.request().method()} ${res.url()}`);
+    page.on("console", onConsole);
+    page.on("response", onResponse);
+    return {
+        console: consoleBuf,
+        network: networkBuf,
+        dispose() {
+            page.off("console", onConsole);
+            page.off("response", onResponse);
+        },
+    };
+}
+//# sourceMappingURL=observe.js.map

package/dist/agent/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/agent/observe.ts"],"names":[],"mappings":"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"}

package/dist/agent/tools.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The tool surface the autonomous drive exposes to the BYO model, and the
+ * parsing of a model's tool-call arguments back into the typed IR.
+ *
+ * Each tool maps one-to-one onto a {@link Recorder} action, so the model drives
+ * the product through exactly the vocabulary the compiler can emit — nothing
+ * the recorder cannot capture, and nothing the emitter cannot render.
+ */
+import type { Locator } from "../compiler/actions.js";
+/** A tool definition advertised to the model, carrying a JSON Schema for args. */
+export interface DriveTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/** The tools advertised to the model each turn. Names map to Recorder methods. */
+export declare const DRIVE_TOOLS: readonly DriveTool[];
+/**
+ * A locator is `{ strategy, ... }`. Prefer resilient strategies (role with a
+ * name, testId, or text) over css. This text is folded into the system prompt.
+ */
+export declare const LOCATOR_GUIDANCE: string;
+/** Guidance for the terminal tools, folded into the system prompt. */
+export declare const TERMINAL_GUIDANCE: string;
+/** Guidance for the HTTP tools, folded into the system prompt. */
+export declare const HTTP_GUIDANCE: string;
+/** Raised when a model's locator arguments are not a recognizable strategy. */
+export declare class ToolArgumentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a model tool-call's arguments into a {@link Locator}.
+ *
+ * Accepts the locator nested under `locator` or inline on the arguments object.
+ *
+ * @throws {ToolArgumentError} on a missing or unrecognized strategy.
+ */
+export declare function parseLocator(args: Record<string, unknown>): Locator;
+/** Arguments for the `run_command` tool. */
+export interface RunCommandArgs {
+    command: string;
+    cwd?: string;
+}
+/** Parse a `run_command` tool call's arguments. */
+export declare function parseRunCommand(args: Record<string, unknown>): RunCommandArgs;
+/** Arguments for the `expect_output` tool. */
+export interface OutputAssertionArgs {
+    match: "exact" | "contains" | "regex";
+    stream: "stdout" | "stderr";
+    value: string;
+}
+/** Parse an `expect_output` tool call's arguments. */
+export declare function parseExpectOutput(args: Record<string, unknown>): OutputAssertionArgs;
+/** Parse an `expect_exit` tool call's arguments. */
+export declare function parseExpectExit(args: Record<string, unknown>): number;
+/** Arguments for the `request` tool. */
+export interface RequestArgs {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** Parse a `request` tool call's arguments. */
+export declare function parseRequest(args: Record<string, unknown>): RequestArgs;
+/** Parse an `expect_status` tool call's arguments. */
+export declare function parseExpectStatus(args: Record<string, unknown>): number;
+/** Arguments for the `expect_json` tool. */
+export interface ExpectJsonArgs {
+    path: string;
+    equals: string | number | boolean;
+}
+/** Parse an `expect_json` tool call's arguments. */
+export declare function parseExpectJson(args: Record<string, unknown>): ExpectJsonArgs;
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AA0BD,kFAAkF;AAClF,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAsG3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAIiD,CAAC;AAE/E,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,QAIwC,CAAC;AAEvE,kEAAkE;AAClE,eAAO,MAAM,aAAa,QAIiE,CAAC;AAE5F,+EAA+E;AAC/E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AASD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAqBnE;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAI7E;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;IACtC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAUpF;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMrE;AAED,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAgBvE;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMvE;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAO7E"}