@ap3x/browser-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @ap3x/browser-agent
+
+The agent that drives a browser: a step loop, an action registry, run history, and replay — plus an MCP server exposing it to any MCP client.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/browser-agent
+```
+
+## What's inside
+
+- **Step loop** — perceive, decide, act, with a structured output schema and a multi-action executor.
+- **Action registry** — `defineAction` with an explicit context object; actions are filtered per page.
+- **Sensitive data** — a placeholder pipeline that keeps secrets out of model context.
+- **FileSystem workspace** — a contained workspace with PDF and DOCX reads.
+- **Run history + replay** — record a run, then replay it deterministically with element re-matching.
+- **Captcha watchdog** — page-state detection that emits a typed signal; it never attempts to solve.
+
+## MCP server
+
+```bash
+npx ap3x-browser-mcp
+```
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/agent/agent.d.ts

@@ -0,0 +1,160 @@
+import type { Api, Model, ProviderStreamOptions } from "@ap3x/ai";
+import { BrowserDriver, type BrowserSession, type HarLog } from "@ap3x/browser";
+import { type Logger } from "../observability/logger";
+import { type ExtractionLlm, type Registry } from "../tools/registry";
+import type { SensitiveData } from "../tools/sensitive";
+import type { VisionMode } from "./context-builder";
+import { type AgentStreamEvent, type AgentStreamEventOf, type AgentStreamEventType } from "./event-stream";
+import { type GifOptions } from "./gif";
+import { AgentHistoryList } from "./history";
+import { type JudgementResult } from "./judge";
+import { type RunOptions, type StepLoopHooks, type StepLoopLimits } from "./step-loop";
+import { type VideoOptions } from "./video";
+/** Grouped constructor options (E1). Only `llm` and `browser` are required. */
+export interface AgentOptions {
+    llm: {
+        model: Model<Api>;
+        /** Optional extraction LLM for the `extract_content` action. */
+        extraction?: ExtractionLlm;
+        /**
+         * Per-call overrides (apiKey/headers/etc.) merged into every LLM call the
+         * step loop makes. The seam an embedding host (one that authenticates
+         * with per-request credentials rather than a static env key) uses to
+         * inject auth without a parallel config shape — this is exactly
+         * `@ap3x/ai`'s own `StreamOptions` surface, passed straight through to
+         * `generateObject`.
+         */
+        streamOptions?: ProviderStreamOptions;
+    };
+    browser: {
+        /** An existing session to drive. */
+        session: BrowserSession;
+        /** Override the driver built from `session`. */
+        driver?: BrowserDriver;
+    };
+    /** Custom action registry. NEVER mutated — the Agent drives a clone. */
+    tools?: Registry;
+    /** Screenshot policy (E7). Default `everyStep`. */
+    vision?: VisionMode;
+    output?: {
+        /** Include the `thinking` field (default true). */
+        thinking?: boolean;
+        /** Minimal `memory`+`action` schema (overrides `thinking`). */
+        flash?: boolean;
+        /** Build an animated GIF run-summary from history screenshots after `run()` (IMPROVEMENTS GIF). */
+        generateGif?: boolean | GifOptions;
+        /** Capture network traffic into a HAR 1.2 artifact for the run (M11). Off by default. */
+        recordHar?: boolean;
+        /** Capture a CDP screencast and assemble it into a video-as-GIF artifact (M11). Off by default. */
+        recordVideo?: boolean | VideoOptions;
+    };
+    limits?: Partial<StepLoopLimits>;
+    security?: {
+        sensitiveData?: SensitiveData;
+        availableFilePaths?: string[];
+    };
+    hooks?: StepLoopHooks;
+    /** Base dir for the FileSystem workspace (default: an OS-temp dir). */
+    fileSystemDir?: string;
+    /** Replace the default system prompt entirely. */
+    systemPrompt?: string;
+    /** Injectable structured logger (O1). Default: silent (no output). */
+    logger?: Logger;
+    /** Highlight each action's element before it runs (IMPROVEMENTS demo-mode overlay). */
+    demoMode?: boolean;
+    /**
+     * Opt-in post-run judge (design/04b §4.5): after `run()` completes, an
+     * auxiliary LLM scores the finished trajectory and the verdict is exposed on
+     * {@link Agent.judgement}. Informational only — it NEVER overrides the agent's
+     * own reported success, and a judge failure is logged-and-swallowed (it never
+     * fails the run). Off by default (it's an extra LLM call). Pass `true` to judge
+     * with the agent's own model, or an object to override the judge model / supply
+     * ground-truth / tune screenshot attachment. The judge's token spend is folded
+     * into the run's usage totals.
+     */
+    judge?: boolean | {
+        /** Judge with a different model than the agent runs with (default: the agent's own model). */
+        model?: Model<Api>;
+        /** Ground-truth criteria / expected answer; takes precedence over every other signal the judge weighs. */
+        groundTruth?: string;
+        /** Attach up to this many of the run's most recent screenshots (default 10). */
+        maxImages?: number;
+        /** Attach screenshots to the judge at all (default true). */
+        vision?: boolean;
+    };
+}
+export declare class Agent {
+    private readonly task;
+    private readonly options;
+    private readonly model;
+    private readonly session;
+    private readonly driver;
+    private readonly registry;
+    private readonly vision;
+    private readonly variant;
+    private readonly limits;
+    private readonly ledger;
+    private readonly historyList;
+    private readonly messageManager;
+    private readonly fileSystemDir;
+    private readonly stream;
+    private readonly logger;
+    private readonly taskId;
+    private fileSystem?;
+    private stepLoop?;
+    private pendingPaused;
+    private pendingStopped;
+    /** Set once, after `run()` completes, when `output.generateGif` is on. */
+    private lastGif?;
+    /** Set once, after `run()` completes, when `output.recordHar` is on. */
+    private lastHar?;
+    /** Set once, after `run()` completes, when `output.recordVideo` is on. */
+    private lastVideo?;
+    /** Set once, after `run()` completes, when `judge` is on and the judge succeeded. */
+    private lastJudgement?;
+    constructor(task: string, options: AgentOptions);
+    /** The run history (populated as the loop runs). */
+    get history(): AgentHistoryList;
+    /** The effective (cloned, vision-filtered) registry the agent drives. */
+    get effectiveRegistry(): Registry;
+    /** The model this agent reasons with. */
+    get currentModel(): Model<Api>;
+    /** The GIF run-summary built after `run()`, when `output.generateGif` is on. */
+    get gif(): Uint8Array | undefined;
+    /** The HAR 1.2 network-traffic artifact built after `run()`, when `output.recordHar` is on. */
+    get har(): HarLog | undefined;
+    /** The video-as-GIF artifact built after `run()`, when `output.recordVideo` is on. */
+    get video(): Uint8Array | undefined;
+    /**
+     * The post-run judge's verdict, when `judge` is on. Informational — it never
+     * overrides the agent's own reported success. `undefined` if the judge was off
+     * or the evaluation failed.
+     */
+    get judgement(): JudgementResult | undefined;
+    /** The curated O2 event stream as an async iterable (`for await`). */
+    events(): AsyncIterableIterator<AgentStreamEvent>;
+    /** Subscribe to one event type (callback sugar over {@link events}). */
+    on<T extends AgentStreamEventType>(type: T, cb: (event: AgentStreamEventOf<T>) => void): () => void;
+    /** Subscribe to every event. Returns an unsubscribe function. */
+    onEvent(cb: (event: AgentStreamEvent) => void): () => void;
+    run(options?: RunOptions): Promise<AgentHistoryList>;
+    /** Drive one step (respects pause/stop). Returns whether the task is now done. */
+    step(): Promise<boolean>;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    /** Clone the caller's (or default) registry and apply the vision filter (E7). */
+    private buildRegistry;
+    /**
+     * Compose the caller's `onDone` (if any) with the post-run artifact steps:
+     * the caller's hook always runs first, then — for whichever of GIF/HAR/video
+     * is gated on — the run's screenshots/network trace/screencast are turned
+     * into {@link Agent.gif} / {@link Agent.har} / {@link Agent.video}. Each
+     * artifact step is independently logged-and-swallowed on failure — a pure
+     * output artifact must never fail the run.
+     */
+    private buildHooks;
+    /** Create the FileSystem + StepLoop once; apply any buffered pause/stop. */
+    private ensureReady;
+}
+//# sourceMappingURL=agent.d.ts.map

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

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

package/dist/agent/backend.d.ts

@@ -0,0 +1,38 @@
+import type { AgentBackend, AgentEvent, AgentMessage, AgentRunOptions, AgentRunResult, BackendCapability } from "@ap3x/agent-core";
+import type { Model } from "@ap3x/ai";
+import { Agent, type AgentOptions } from "./agent";
+import type { AgentStreamEvent } from "./event-stream";
+/**
+ * Bridge one O2 {@link AgentStreamEvent} to an agent-core {@link AgentEvent}
+ * (undefined = intentionally dropped, no clean analog). Every one of the 11
+ * `AgentStreamEvent` variants is a named case below — 6 bridged, 5 dropped —
+ * so the drop set is explicit rather than a silent `default:` fall-through.
+ * `default` is reached only by a FUTURE variant the union doesn't have yet:
+ * with all 11 cases present, `event` is typed `never` there, so adding a 12th
+ * variant without a case above is a compile error (exhaustiveness guard).
+ * `backend.test.ts` pins the RUNTIME half — that each case still maps to the
+ * value asserted here, which the compiler alone can't guarantee.
+ */
+export declare function bridgeEvent(event: AgentStreamEvent): AgentEvent | undefined;
+/**
+ * Adapt an {@link Agent} (or {@link AgentOptions}) to agent-core's
+ * {@link AgentBackend}. An `Agent` instance is run as-is; `AgentOptions` spins a
+ * fresh ephemeral `Agent` per `run()` (the task arg supplies its task).
+ */
+export declare class BrowserAgentBackend implements AgentBackend {
+    private readonly source;
+    private readonly model;
+    private readonly listeners;
+    private active?;
+    constructor(source: Agent | AgentOptions);
+    private agentFor;
+    run(task: string | AgentMessage[], opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /** Drain the O2 stream, translating each event to a subscribed agent-core listener. */
+    private pumpEvents;
+    private toRunResult;
+    subscribe(listener: (event: AgentEvent) => void | Promise<void>): () => void;
+    abort(): void;
+    supports(capability: BackendCapability): boolean;
+    getCurrentModel(): Model<string>;
+}
+//# sourceMappingURL=backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/agent/backend.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAO,KAAK,EAAwC,MAAM,UAAU,CAAC;AAEjF,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAwEvD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,GAAG,SAAS,CA8C3E;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0D;IACpF,OAAO,CAAC,MAAM,CAAC,CAAQ;gBAEX,MAAM,EAAE,KAAK,GAAG,YAAY;IAKxC,OAAO,CAAC,QAAQ;IAIV,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAezF,uFAAuF;YACzE,UAAU;IAQxB,OAAO,CAAC,WAAW;IAcnB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI;IAO5E,KAAK,IAAI,IAAI;IAIb,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO;IAIhD,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC;CAKjC"}

package/dist/agent/captcha-watchdog.d.ts

@@ -0,0 +1,31 @@
+/** Known captcha/anti-bot vendors this heuristic recognizes; "generic" covers everything else. */
+export type CaptchaVendor = "recaptcha" | "hcaptcha" | "cloudflare" | "perimeterx" | "datadome" | "akamai" | "generic";
+export interface CaptchaSignal {
+    vendor: CaptchaVendor;
+    url: string;
+    title: string;
+    /** The text snippet that triggered detection (for logging/debugging). */
+    matchedText: string;
+}
+/** Page state the detector needs — a subset of `BrowserStateSummary`. */
+export interface CaptchaDetectInput {
+    url: string;
+    title: string;
+    serializedText: string;
+}
+/**
+ * Detect a likely captcha/anti-bot interstitial from perceived page state.
+ * Heuristic, never a solver: returns a signal or `undefined`, nothing more.
+ */
+export declare function detectCaptcha(state: CaptchaDetectInput): CaptchaSignal | undefined;
+/**
+ * Dedupe helper: fires only when the signal differs from the last one seen
+ * (by vendor + url) — keeps a host from being spammed once per step while the
+ * agent is stuck on the same captcha page.
+ */
+export declare class CaptchaWatchdog {
+    private last;
+    /** Check state; returns a signal only the FIRST time it's seen for this vendor+url. */
+    check(state: CaptchaDetectInput): CaptchaSignal | undefined;
+}
+//# sourceMappingURL=captcha-watchdog.d.ts.map

package/dist/agent/captcha-watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha-watchdog.d.ts","sourceRoot":"","sources":["../../src/agent/captcha-watchdog.ts"],"names":[],"mappings":"AAWA,kGAAkG;AAClG,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAmBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,GAAG,SAAS,CAWlF;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAqB;IAEjC,uFAAuF;IACvF,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,GAAG,SAAS;CAW5D"}

package/dist/agent/context-builder.d.ts

@@ -0,0 +1,24 @@
+import type { BrowserDriver, BrowserStateSummary } from "@ap3x/browser";
+import type { AgentOutput } from "./output-schema";
+/** How screenshots are attached across the run (E7). */
+export type VisionMode = "off" | "everyStep" | "onDemand";
+/** Read current browser state; capture a screenshot unless vision is off. */
+export declare function perceive(driver: BrowserDriver, vision: VisionMode): Promise<BrowserStateSummary>;
+/** Nudge when the run has consumed most of its step budget. */
+export declare function budgetNudge(stepNumber: number, maxSteps: number): string | undefined;
+/**
+ * Soft loop / stagnation detector. Never blocks an action — it only produces
+ * advisory nudge text. Tracks a rolling window of action signatures and the last
+ * few page fingerprints.
+ */
+export declare class LoopDetector {
+    private readonly actionHashes;
+    private readonly fingerprints;
+    private stagnation;
+    /** Record a step's executed actions and the page state it was taken against. */
+    record(output: AgentOutput | undefined, state: BrowserStateSummary): void;
+    /** Advisory nudges to inject this step (may be empty). */
+    nudges(): string[];
+    private maxRepetition;
+}
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/agent/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../src/agent/context-builder.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,CAAC;AAU1D,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAEhG;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIpF;AAcD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,UAAU,CAAK;IAEvB,gFAAgF;IAChF,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAazE,0DAA0D;IAC1D,MAAM,IAAI,MAAM,EAAE;IAgBlB,OAAO,CAAC,aAAa;CAUtB"}

package/dist/agent/event-stream.d.ts

@@ -0,0 +1,104 @@
+import { type Action, type ActionResult } from "../tools/types";
+import type { CaptchaSignal } from "./captcha-watchdog";
+import type { AgentOutput } from "./output-schema";
+/** The discriminated union of everything a run emits to consumers. */
+export type AgentStreamEvent = {
+    type: "run-started";
+    task: string;
+    maxSteps: number;
+    startedAt: number;
+} | {
+    type: "step-started";
+    step: number;
+    url: string;
+    title: string;
+} | {
+    type: "model-thought";
+    step: number;
+    thinking?: string;
+    evaluationPreviousGoal?: string;
+    memory?: string;
+    nextGoal?: string;
+} | {
+    type: "action-started";
+    step: number;
+    /** Position of this action within the step's batch. */
+    index: number;
+    name: string;
+    /** The typed action (for live element highlighting etc.). */
+    action: Action;
+    params: Record<string, unknown>;
+} | {
+    type: "action-finished";
+    step: number;
+    index: number;
+    name: string;
+    result: ActionResult;
+} | {
+    type: "step-finished";
+    step: number;
+    /** The voice sentence — built from the model's own fields, no extra LLM cost. */
+    narration: string;
+    output?: AgentOutput;
+    results: ActionResult[];
+} | {
+    type: "paused";
+} | {
+    type: "resumed";
+} | {
+    type: "done";
+    success: boolean;
+    finalText: string;
+    steps: number;
+} | {
+    type: "error";
+    message: string;
+    step?: number;
+} | ({
+    type: "captcha-detected";
+    step: number;
+} & CaptchaSignal);
+/** The `type` discriminant of {@link AgentStreamEvent}. */
+export type AgentStreamEventType = AgentStreamEvent["type"];
+/** The event variant for a given `type`. */
+export type AgentStreamEventOf<T extends AgentStreamEventType> = Extract<AgentStreamEvent, {
+    type: T;
+}>;
+type AnyListener = (event: AgentStreamEvent) => void;
+/**
+ * The producer + fan-out for {@link AgentStreamEvent}. The loop calls `emit`;
+ * consumers use `on` (typed callback), `onEvent` (every event) or `events()`
+ * (async iterable). Multiple consumers of each kind are supported; every one
+ * sees every event from the moment it subscribes.
+ */
+export declare class AgentEventStream {
+    private readonly typed;
+    private readonly any;
+    /** Fan an event out to all listeners. */
+    emit(event: AgentStreamEvent): void;
+    /** Subscribe to one event type. Returns an unsubscribe function. */
+    on<T extends AgentStreamEventType>(type: T, cb: (event: AgentStreamEventOf<T>) => void): () => void;
+    /** Subscribe to every event. Returns an unsubscribe function. */
+    onEvent(cb: AnyListener): () => void;
+    /**
+     * An async iterable of every event, ending after the terminal (done/error).
+     * Subscribe before/while a run produces events; iterating after a run has
+     * already finished (with no further run) parks on the first `next()`.
+     */
+    events(): AsyncIterableIterator<AgentStreamEvent>;
+}
+/**
+ * Reconstruct the typed {@link Action} from a parsed single-key action. The
+ * built-in action schemas use the same field names as the {@link Action} union,
+ * so the discriminant is the action name and the params carry the rest.
+ */
+export declare function toTypedAction(name: string, params: Record<string, unknown>): Action;
+/**
+ * The voice sentence for a step — assembled only from fields the model already
+ * produced (zero extra LLM cost). A terminal `done` speaks its own text; an
+ * ordinary step speaks its evaluation of the last goal plus the next goal,
+ * falling back to an action summary, then to the first error.
+ */
+export declare function assembleNarration(output: AgentOutput | undefined, results: readonly ActionResult[]): string;
+export {};
+//# sourceMappingURL=event-stream.d.ts.map

package/dist/agent/event-stream.d.ts.map

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

package/dist/agent/executor.d.ts

@@ -0,0 +1,37 @@
+import type { BrowserSession } from "@ap3x/browser";
+import type { ActionContext, Registry } from "../tools/registry";
+import type { SecretMap, SensitiveData } from "../tools/sensitive";
+import { type ActionResult } from "../tools/types";
+import { type AgentStreamEvent } from "./event-stream";
+export interface MultiActInput {
+    actions: Array<Record<string, unknown>>;
+    registry: Registry;
+    ctx: ActionContext;
+    session: BrowserSession;
+    secrets?: SecretMap;
+    /** Full cross-domain sensitive-data config, for outbound masking (M8 follow-up — see registry.execute). */
+    allSensitiveData?: SensitiveData;
+    signal?: AbortSignal;
+    /**
+     * Checked BEFORE every action (design/06 §6.7, the stop/pause gate). Returns
+     * false → the batch breaks cleanly with the results so far. Lets a mid-step
+     * stop()/pause() interrupt the queued actions, not just an AbortSignal.
+     */
+    shouldContinue?: () => boolean;
+    /** Cap on actions executed per step (default: no cap). */
+    maxActions?: number;
+    /** Highlight each action's element before it runs, cleared after (demo mode). */
+    demoMode?: boolean;
+    /** Emit the O2 action-started/action-finished events (optional). */
+    emit?: (event: AgentStreamEvent) => void;
+    /** 1-based step number, stamped onto emitted events. */
+    step?: number;
+}
+/**
+ * Execute a step's action batch. Returns the accumulated results (partial when the
+ * batch was aborted by a page change, an error, or a done). Never throws for
+ * action failures — those become `ActionResult.error`; it DOES throw if the run
+ * was aborted (the step loop maps that to a clean stop).
+ */
+export declare function multiAct(input: MultiActInput): Promise<ActionResult[]>;
+//# sourceMappingURL=executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/agent/executor.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,KAAK,YAAY,EAA4B,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,KAAK,gBAAgB,EAAiB,MAAM,gBAAgB,CAAC;AAGtE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxC,QAAQ,EAAE,QAAQ,CAAC;IACnB,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,2GAA2G;IAC3G,gBAAgB,CAAC,EAAE,aAAa,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;IAC/B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzC,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AASD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsE5E"}

package/dist/agent/gif.d.ts

@@ -0,0 +1,23 @@
+import type { AgentHistoryList } from "./history";
+import { type DecodedImage } from "./png-decode";
+export interface GifOptions {
+    /** Milliseconds each frame is shown. Default 3000. */
+    frameDurationMs?: number;
+    /** Max palette colors per frame (default 256, GIF's ceiling). */
+    maxColors?: number;
+    /** GIF loop count: 0 = forever (default), -1 = play once, N = N extra loops. */
+    repeat?: number;
+}
+/**
+ * Encode a list of same-size decoded frames into an animated GIF. Shared core
+ * used by {@link generateRunGif} (per-step screenshots) and the M11 video
+ * pipeline (agent/video.ts, screencast frames) — "assemble via the M10 GIF
+ * pipeline" per the PRP. Returns `undefined` when `frames` is empty.
+ */
+export declare function encodeFramesToGif(frames: readonly DecodedImage[], options?: GifOptions): Uint8Array | undefined;
+/**
+ * Build an animated GIF from a run's history screenshots. Returns `undefined`
+ * when there is nothing to encode (no history, or no decodable screenshots).
+ */
+export declare function generateRunGif(history: AgentHistoryList, options?: GifOptions): Uint8Array | undefined;
+//# sourceMappingURL=gif.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gif.d.ts","sourceRoot":"","sources":["../../src/agent/gif.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,cAAc,CAAC;AAclE,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA0BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,GAAE,UAAe,GACvB,UAAU,GAAG,SAAS,CAqBxB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,UAAe,GACvB,UAAU,GAAG,SAAS,CAExB"}

package/dist/agent/history.d.ts

@@ -0,0 +1,89 @@
+import type { DOMInteractedElement, TabInfo } from "@ap3x/browser";
+import { type ActionResult } from "../tools/types";
+import type { UsageSummary } from "../usage/ledger";
+import type { AgentOutput } from "./output-schema";
+/** The slice of browser state persisted with a step. */
+export interface BrowserStateHistory {
+    url: string;
+    title: string;
+    tabs: TabInfo[];
+    /** Present only when a screenshot was captured this step. */
+    screenshot?: string;
+    /**
+     * Per-action interacted-element snapshot, aligned index-for-index with
+     * `modelOutput.action` (undefined where an action carried no element index).
+     * Captured against the selector map the LLM actually saw (before any action
+     * ran this step) — design/04b §4.1 RECORD phase. This is the ONLY thing a
+     * replay (M9) has to re-locate an element across a fresh page load, since
+     * indices are live backendNodeIds that do not survive a reload.
+     */
+    interactedElements?: Array<DOMInteractedElement | undefined>;
+}
+/** Per-step timing. `stepInterval` is the duration of the PREVIOUS step. */
+export interface StepMetadata {
+    stepStartTime: number;
+    stepEndTime: number;
+    stepNumber: number;
+    stepInterval?: number;
+}
+/** Duration of one step in seconds. */
+export declare function stepDurationSeconds(metadata: StepMetadata): number;
+/** One recorded step. */
+export interface AgentHistory {
+    modelOutput?: AgentOutput;
+    result: ActionResult[];
+    state: BrowserStateHistory;
+    metadata?: StepMetadata;
+    /** The raw state-message text, kept for debugging. */
+    stateMessage?: string;
+}
+/** Why the run loop stopped — a STRUCTURAL signal the loop sets, not a string sniff. */
+export type TerminationReason = "done" | "max_steps" | "max_failures" | "run_timeout" | "aborted" | "stopped";
+/** Append-only list of steps plus the run's usage summary + query helpers. */
+export declare class AgentHistoryList {
+    readonly history: AgentHistory[];
+    usage?: UsageSummary;
+    /** Set once by the loop when it exits; drives StopReason mapping (no regex). */
+    terminationReason?: TerminationReason;
+    /** Append a step. Items are never mutated or reordered afterwards. */
+    add(item: AgentHistory): void;
+    get length(): number;
+    numberOfSteps(): number;
+    private lastResult;
+    /** The `extractedContent` of the last result of the last step. */
+    finalResult(): string | undefined;
+    /** True once a terminal `done` result has been recorded. */
+    isDone(): boolean;
+    /** The agent's self-reported success — only meaningful when done, else undefined. */
+    isSuccessful(): boolean | undefined;
+    /** One error (the first) per step; undefined where a step had none. */
+    errors(): Array<string | undefined>;
+    hasErrors(): boolean;
+    /** Per-step page URLs. */
+    urls(): string[];
+    /** Flattened action names across all steps (one per single-key action object). */
+    actionNames(): string[];
+    /** Sum of per-step durations (seconds). */
+    totalDurationSeconds(): number;
+    /** Plain-data snapshot for persistence (design/04b §4.1 `AgentHistoryList.save_to_file`). */
+    toJSON(): AgentHistoryFile;
+    /**
+     * Rebuild a list from a plain-data snapshot. The CALLER is responsible for
+     * schema-validating untrusted input before calling this (replay.ts's
+     * `loadHistoryFromFile` is the trust boundary — this constructor trusts its
+     * argument, matching every other in-process history mutation in this class).
+     *
+     * `interactedElements` entries round-trip through JSON as `null` (undefined
+     * array elements serialize that way — `Type.Array` has no other way to carry
+     * a "no element" slot); normalize them back to `undefined` here so in-memory
+     * histories built directly (never touching JSON) and loaded ones agree.
+     */
+    static fromJSON(data: AgentHistoryFile): AgentHistoryList;
+}
+/** The serializable shape of an {@link AgentHistoryList} (M9 replay trust boundary). */
+export interface AgentHistoryFile {
+    version: number;
+    history: AgentHistory[];
+    terminationReason?: string;
+}
+//# sourceMappingURL=history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent/history.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;CAC9D;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,uCAAuC;AACvC,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAElE;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,WAAW,GACX,cAAc,GACd,aAAa,GACb,SAAS,GACT,SAAS,CAAC;AAEd,8EAA8E;AAC9E,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAM;IACtC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC,sEAAsE;IACtE,GAAG,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAI7B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,UAAU;IAMlB,kEAAkE;IAClE,WAAW,IAAI,MAAM,GAAG,SAAS;IAIjC,4DAA4D;IAC5D,MAAM,IAAI,OAAO;IAKjB,qFAAqF;IACrF,YAAY,IAAI,OAAO,GAAG,SAAS;IAMnC,uEAAuE;IACvE,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;IAInC,SAAS,IAAI,OAAO;IAIpB,0BAA0B;IAC1B,IAAI,IAAI,MAAM,EAAE;IAIhB,kFAAkF;IAClF,WAAW,IAAI,MAAM,EAAE;IAWvB,2CAA2C;IAC3C,oBAAoB,IAAI,MAAM;IAO9B,6FAA6F;IAC7F,MAAM,IAAI,gBAAgB;IAI1B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB;CAa1D;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}