@ap3x/browser-agent 0.1.0

package/dist/agent/judge.d.ts

@@ -0,0 +1,36 @@
+import { type Api, type Model, type ProviderStreamOptions, type Usage } from "@ap3x/ai";
+import { type Static } from "@sinclair/typebox";
+import type { AgentHistoryList } from "./history";
+export declare const JudgementResultSchema: import("@sinclair/typebox").TObject<{
+    reasoning: import("@sinclair/typebox").TString;
+    verdict: import("@sinclair/typebox").TBoolean;
+    failureReason: import("@sinclair/typebox").TString;
+    impossibleTask: import("@sinclair/typebox").TBoolean;
+    reachedCaptcha: import("@sinclair/typebox").TBoolean;
+}>;
+/** The judge's structured verdict on a finished run. */
+export type JudgementResult = Static<typeof JudgementResultSchema>;
+export interface JudgeOptions {
+    /**
+     * Ground-truth criteria or expected answer, when known. 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 at all (default true). */
+    vision?: boolean;
+    signal?: AbortSignal;
+    /**
+     * Per-call overrides (apiKey/headers/etc.) merged into the judge's
+     * `generateObject` call — same seam as `AgentOptions.llm.streamOptions`.
+     */
+    streamOptions?: ProviderStreamOptions;
+}
+export interface JudgeResult {
+    judgement: JudgementResult;
+    usage: Usage;
+}
+/** Evaluate a completed run. Never throws for a "the task failed" outcome — only for LLM/transport errors. */
+export declare function judgeRun(model: Model<Api>, task: string, history: AgentHistoryList, options?: JudgeOptions): Promise<JudgeResult>;
+//# sourceMappingURL=judge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/agent/judge.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,GAAG,EAER,KAAK,KAAK,EACV,KAAK,qBAAqB,EAE1B,KAAK,KAAK,EAEX,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,eAAO,MAAM,qBAAqB;;;;;;EAMhC,CAAC;AAEH,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;CACd;AAmED,8GAA8G;AAC9G,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA4BtB"}

package/dist/agent/message-manager.d.ts

@@ -0,0 +1,94 @@
+import type { Message } from "@ap3x/ai";
+import type { BrowserStateSummary } from "@ap3x/browser";
+import { type SensitiveData } from "../tools/sensitive";
+import { type ActionResult } from "../tools/types";
+import type { AgentOutput } from "./output-schema";
+/** Compaction gates (design/04b §4.2): BOTH must hold to compact. */
+export declare const COMPACT_EVERY_N_STEPS = 25;
+export declare const COMPACT_TRIGGER_CHARS = 40000;
+/**
+ * One rendered history entry. `error` and `systemMessage` are mutually exclusive
+ * (a step is either a normal turn or a synthetic system note).
+ */
+export interface HistoryItem {
+    stepNumber?: number;
+    evaluationPreviousGoal?: string;
+    memory?: string;
+    nextGoal?: string;
+    /** Persistent per-result lines (longTermMemory / extractedContent / error text). */
+    actionResults?: string[];
+    error?: string;
+    systemMessage?: string;
+}
+export interface MessageManagerOptions {
+    systemPrompt: string;
+    task: string;
+    sensitiveData?: SensitiveData;
+    fileSystemDescribe?: () => string;
+    todoContents?: () => string;
+    availableFilePaths?: readonly string[];
+}
+export interface BuildMessagesOptions {
+    stepNumber: number;
+    maxSteps: number;
+    /** Transient nudges appended as context messages this step. */
+    nudges?: string[];
+    /** Attach the screenshot as an image part (vision on). */
+    attachScreenshot?: boolean;
+}
+export declare class MessageManager {
+    private readonly systemPrompt;
+    private readonly task;
+    private readonly sensitiveData?;
+    private readonly fileSystemDescribe?;
+    private readonly todoContents?;
+    private readonly availableFilePaths;
+    private readonly items;
+    private readState;
+    private compactedMemory?;
+    private compactionCountValue;
+    private lastCompactionStep;
+    /**
+     * One-shot: set when a step's result asked for the screenshot to be shown
+     * next (the on-demand `screenshot` action's `metadata.includeScreenshot`,
+     * design/04b §4.3 — "the message manager attaches the *next* state
+     * screenshot even in use_vision='auto'"). Consumed by the following
+     * `buildMessages` call regardless of the caller's own `attachScreenshot`.
+     */
+    private pendingScreenshotRequest;
+    /** The raw state text built for the most recent step (kept for history debugging). */
+    private lastStateText;
+    constructor(options: MessageManagerOptions);
+    get compactionCount(): number;
+    get stateMessageText(): string;
+    /**
+     * Fold a completed step's output + results into the running history (the RECORD
+     * half of the loop as the LLM sees it). Once-only content becomes the next
+     * prompt's one-shot <read_state>; everything else becomes a persistent line.
+     */
+    recordStep(stepNumber: number, output: AgentOutput | undefined, results: ActionResult[]): void;
+    /** Record a synthetic system note (e.g. "Failed to complete task in max steps"). */
+    recordSystemNote(stepNumber: number, message: string): void;
+    /** Full rendered history text (used for both the prompt and the compaction gate). */
+    private renderHistory;
+    /**
+     * Compaction (design/04b §4.2). Fires only when BOTH gates hold:
+     * `stepNumber - lastCompactionStep >= 25` AND rendered history `>= 40000` chars.
+     * Summarizes the dropped items into `compactedMemory`, keeps the first item and
+     * the last 6, and bumps the compaction count. Returns whether it fired.
+     *
+     * ponytail: deterministic join-summary rather than a summarizer LLM call — the
+     * gate + keep-window is the load-bearing behavior; upgrade path is to pass a
+     * compaction model and summarize `dropped` instead of joining their memories.
+     */
+    maybeCompact(stepNumber: number): boolean;
+    /** Assemble `[system, state, ...context]` for one step. */
+    buildMessages(state: BrowserStateSummary, options: BuildMessagesOptions): Message[];
+    private buildStateMessage;
+    private buildStateText;
+    private buildAgentState;
+    private buildBrowserState;
+}
+/** True when a result set completed the task (a terminal `done`). */
+export declare function resultsAreDone(results: ActionResult[]): boolean;
+//# sourceMappingURL=message-manager.d.ts.map

package/dist/agent/message-manager.d.ts.map

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

package/dist/agent/output-schema.d.ts

@@ -0,0 +1,26 @@
+import { type TSchema } from "@sinclair/typebox";
+/** Which brain fields the output schema carries. */
+export type OutputVariant = "thinking" | "noThinking" | "flash";
+/**
+ * Build the AgentOutput schema for a step. `actionUnion` is the registry's
+ * per-page union of single-key `{ actionName: params }` objects; it becomes the
+ * item type of the required, non-empty `action` array.
+ */
+export declare function buildAgentOutputSchema(actionUnion: TSchema, variant: OutputVariant): TSchema;
+/** One single-key action element as parsed out of {@link AgentOutput.action}. */
+export interface ParsedAction {
+    name: string;
+    params: Record<string, unknown>;
+}
+/** The parsed LLM output the step loop consumes (variant-agnostic superset). */
+export interface AgentOutput {
+    thinking?: string;
+    evaluation_previous_goal?: string;
+    memory?: string;
+    next_goal?: string;
+    /** Non-empty list of single-key `{ name: params }` objects. */
+    action: Array<Record<string, unknown>>;
+}
+/** Split a single-key action object into `{ name, params }`. */
+export declare function parseAction(entry: Record<string, unknown>): ParsedAction | undefined;
+//# sourceMappingURL=output-schema.d.ts.map

package/dist/agent/output-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-schema.d.ts","sourceRoot":"","sources":["../../src/agent/output-schema.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,mBAAmB,CAAC;AAEvD,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAwB5F;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,GAAG,SAAS,CAMpF"}

package/dist/agent/png-decode.d.ts

@@ -0,0 +1,9 @@
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** width*height*4 bytes, RGBA, row-major. */
+    rgba: Uint8Array;
+}
+/** Decode a base64 PNG data string. Returns `undefined` for anything unsupported. */
+export declare function decodePngBase64(base64: string): DecodedImage | undefined;
+//# sourceMappingURL=png-decode.d.ts.map

package/dist/agent/png-decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png-decode.d.ts","sourceRoot":"","sources":["../../src/agent/png-decode.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,UAAU,CAAC;CAClB;AAYD,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAMxE"}

package/dist/agent/rematch.d.ts

@@ -0,0 +1,26 @@
+import { type BackendNodeId, type DOMInteractedElement, type DomSelectorMap, type EnhancedDOMTreeNode, MatchLevel } from "@ap3x/browser";
+export interface RematchSuccess {
+    level: MatchLevel;
+    backendNodeId: BackendNodeId;
+    node: EnhancedDOMTreeNode;
+}
+export interface RematchFailure {
+    level: undefined;
+    diagnostic: string;
+}
+export type RematchResult = RematchSuccess | RematchFailure;
+/**
+ * Re-locate a recorded element in the current (live) selector map. Returns the
+ * live backendNodeId + match level on success, or a diagnostic on total miss.
+ */
+export declare function rematchElement(recorded: DOMInteractedElement, selectorMap: DomSelectorMap): RematchResult;
+/**
+ * Heuristic: does this recorded element look like it OPENS a menu/dropdown
+ * (aria-haspopup / aria-expanded / a menu-ish class)? Used by the replay
+ * engine's menu-reopen fallback (design/04b §4.1) — when a menu-item element
+ * can't be found, re-clicking the opener before retrying often fixes it.
+ */
+export declare function looksLikeMenuOpener(el: DOMInteractedElement): boolean;
+/** Heuristic: does this recorded element look like a menu ITEM (as opposed to the opener)? */
+export declare function looksLikeMenuItem(el: DOMInteractedElement): boolean;
+//# sourceMappingURL=rematch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rematch.d.ts","sourceRoot":"","sources":["../../src/agent/rematch.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,UAAU,EAKX,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AA8C5D;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,cAAc,GAC1B,aAAa,CA0Df;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAKrE;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAKnE"}

package/dist/agent/replay.d.ts

@@ -0,0 +1,155 @@
+import { type Api, type Model, type ProviderStreamOptions } from "@ap3x/ai";
+import type { BrowserDriver, BrowserSession, MatchLevel } from "@ap3x/browser";
+import type { FileSystem } from "../filesystem/file-system";
+import { type Logger } from "../observability/logger";
+import type { ExtractionLlm, Registry } from "../tools/registry";
+import { type ActionResult } from "../tools/types";
+import { AgentHistoryList } from "./history";
+import { type DetectedVariable } from "./variable-detector";
+/** The on-disk shape of a saved run (design/04b §4.1 `AgentHistory.json`). */
+export declare const HistoryFileSchema: import("@sinclair/typebox").TObject<{
+    version: import("@sinclair/typebox").TLiteral<1>;
+    history: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        modelOutput: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            thinking: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            evaluation_previous_goal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            memory: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            next_goal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            action: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+        }>>;
+        result: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            isDone: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+            success: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+            error: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            extractedContent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            includeExtractedContentOnlyOnce: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+            longTermMemory: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            attachments: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+            images: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                name: import("@sinclair/typebox").TString;
+                data: import("@sinclair/typebox").TString;
+            }>>>;
+            metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+            includeInMemory: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        }>>;
+        state: import("@sinclair/typebox").TObject<{
+            url: import("@sinclair/typebox").TString;
+            title: import("@sinclair/typebox").TString;
+            tabs: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                id: import("@sinclair/typebox").TString;
+                url: import("@sinclair/typebox").TString;
+                title: import("@sinclair/typebox").TString;
+                parentId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            screenshot: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            interactedElements: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+                nodeId: import("@sinclair/typebox").TNumber;
+                backendNodeId: import("@sinclair/typebox").TNumber;
+                frameId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nodeType: import("@sinclair/typebox").TNumber;
+                nodeValue: import("@sinclair/typebox").TString;
+                nodeName: import("@sinclair/typebox").TString;
+                attributes: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>;
+                bounds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                    x: import("@sinclair/typebox").TNumber;
+                    y: import("@sinclair/typebox").TNumber;
+                    width: import("@sinclair/typebox").TNumber;
+                    height: import("@sinclair/typebox").TNumber;
+                }>>;
+                xpath: import("@sinclair/typebox").TString;
+                elementHash: import("@sinclair/typebox").TString;
+                stableHash: import("@sinclair/typebox").TString;
+                axName: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                parentBranchHash: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>, import("@sinclair/typebox").TNull]>>>;
+        }>;
+        metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            stepStartTime: import("@sinclair/typebox").TNumber;
+            stepEndTime: import("@sinclair/typebox").TNumber;
+            stepNumber: import("@sinclair/typebox").TNumber;
+            stepInterval: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        }>>;
+        stateMessage: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    terminationReason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Save a run's history to disk (design/04b §4.1 `save_to_file`). */
+export declare function saveHistoryToFile(history: AgentHistoryList, filePath: string): Promise<void>;
+/**
+ * Load and validate a history file (the trust boundary). Throws a descriptive
+ * `Error` — never a bare JSON.parse crash — when the file is malformed.
+ */
+export declare function loadHistoryFromFile(filePath: string): Promise<AgentHistoryList>;
+export type CompletionStatus = "full" | "partial" | "failed";
+export type SummarySource = "llm" | "plain-text" | "fallback";
+export interface RerunDeps {
+    session: BrowserSession;
+    driver: BrowserDriver;
+    registry: Registry;
+    fileSystem: FileSystem;
+    extractionLlm?: ExtractionLlm;
+    availableFilePaths?: readonly string[];
+    /** Rerun-summary LLM. Omit to always use the non-LLM fallback. */
+    model?: Model<Api>;
+    /**
+     * Per-call overrides (apiKey/headers/etc.) merged into the rerun-summary
+     * LLM call (and its plain-text fallback) — same seam as
+     * `AgentOptions.llm.streamOptions`.
+     */
+    streamOptions?: ProviderStreamOptions;
+    /** Echoed into the rerun summary prompt. Defaults to "". */
+    task?: string;
+    logger?: Logger;
+}
+export interface RerunOptions {
+    maxRetries?: number;
+    retryBaseMs?: number;
+    retryCapMs?: number;
+    defaultStepDelayMs?: number;
+    maxStepIntervalMs?: number;
+    /**
+     * Skip steps that already had an error in the ORIGINAL run, AND continue the
+     * rerun past a step that fails during replay itself instead of aborting.
+     * Default false — a failed replay step stops the rerun (design/04b §4.1;
+     * a strict rerun aborts instead).
+     */
+    skipFailures?: boolean;
+    /** Injectable sleep (tests pass a no-op / spy — fake-timer friendly). */
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    /** Per-attempt action cap, composed with `signal` (design/04b §4.8). Default 180s. */
+    stepTimeoutMs?: number;
+}
+export type StepReplayOutcome = "replayed" | "skipped-redundant" | "skipped-original-error" | "skipped-no-actions" | "failed";
+export interface StepReplayResult {
+    stepNumber: number;
+    outcome: StepReplayOutcome;
+    matchLevels: Array<MatchLevel | undefined>;
+    results?: ActionResult[];
+    error?: string;
+    attempts: number;
+}
+export interface RerunReport {
+    steps: StepReplayResult[];
+    succeededSteps: number;
+    totalSteps: number;
+    summary: string;
+    success: boolean;
+    completionStatus: CompletionStatus;
+    summarySource: SummarySource;
+}
+/**
+ * Replay a recorded `AgentHistoryList` step by step against the LIVE browser,
+ * with no LLM driving decisions (design/04b §4.1, history rerun).
+ */
+export declare function rerunHistory(history: AgentHistoryList, deps: RerunDeps, options?: RerunOptions): Promise<RerunReport>;
+/**
+ * Load a history file, optionally substitute detected variables, then replay
+ * it (design/04b §4.1, load-and-rerun).
+ */
+export declare function loadAndRerun(filePath: string, deps: RerunDeps, options?: RerunOptions & {
+    variables?: Readonly<Record<string, string>>;
+}): Promise<RerunReport & {
+    detectedVariables: DetectedVariable[];
+}>;
+//# sourceMappingURL=replay.d.ts.map

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

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

package/dist/agent/step-loop.d.ts

@@ -0,0 +1,124 @@
+import { type Api, type Model, type ProviderStreamOptions } from "@ap3x/ai";
+import { type BrowserDriver, type BrowserSession } from "@ap3x/browser";
+import type { FileSystem } from "../filesystem/file-system";
+import { type Logger } from "../observability/logger";
+import type { ExtractionLlm, Registry } from "../tools/registry";
+import { type SensitiveData } from "../tools/sensitive";
+import type { UsageLedger } from "../usage/ledger";
+import { type VisionMode } from "./context-builder";
+import { type AgentStreamEvent } from "./event-stream";
+import type { AgentHistoryList, BrowserStateHistory } from "./history";
+import { type MessageManager } from "./message-manager";
+import { type AgentOutput, type OutputVariant } from "./output-schema";
+/** Numeric limits governing the loop. */
+export interface StepLoopLimits {
+    maxSteps: number;
+    maxFailures: number;
+    maxActionsPerStep: number;
+    finalResponseAfterFailure: boolean;
+    stepTimeoutMs: number;
+    llmTimeoutMs: number;
+    /**
+     * Optional overall wall-clock ceiling for the whole run, in ms. OFF by default.
+     * Without it a run is bounded only by `maxSteps × stepTimeoutMs`, so a slow or
+     * heavy page (a live chart, an infinite feed) can grind for minutes with no
+     * total budget — the "stuck forever" failure. When set, the deadline both
+     * prevents a new step from starting AND aborts the in-flight step's LLM/CDP
+     * calls, so a run cannot overshoot it by a whole step. Latency-sensitive
+     * embedders (an interactive chat agent) should set it.
+     */
+    runTimeoutMs?: number;
+}
+export interface StepLoopHooks {
+    onStep?: (state: BrowserStateHistory, output: AgentOutput, step: number) => void | Promise<void>;
+    onDone?: (history: AgentHistoryList) => void | Promise<void>;
+}
+export interface StepLoopDeps {
+    model: Model<Api>;
+    driver: BrowserDriver;
+    session: BrowserSession;
+    /** The EFFECTIVE registry (already cloned + vision-filtered by the Agent). */
+    registry: Registry;
+    fileSystem: FileSystem;
+    messageManager: MessageManager;
+    history: AgentHistoryList;
+    ledger: UsageLedger;
+    vision: VisionMode;
+    variant: OutputVariant;
+    limits: StepLoopLimits;
+    sensitiveData?: SensitiveData;
+    availableFilePaths?: readonly string[];
+    extractionLlm?: ExtractionLlm;
+    /**
+     * Per-call overrides (apiKey/headers/etc.) merged into every `generateObject`
+     * call this loop makes — the seam an embedding host uses to authenticate with
+     * per-request credentials (e.g. OAuth headers) instead of a static env key.
+     * Call-specific fields (like the per-step abort signal) always win.
+     */
+    llmStreamOptions?: ProviderStreamOptions;
+    /** Demo-mode: highlight each action's element before it runs (IMPROVEMENTS overlay). */
+    demoMode?: boolean;
+    hooks?: StepLoopHooks;
+    /** The task text, echoed on the `run-started` event. */
+    task?: string;
+    /** Sink for the O2 typed step-event stream (optional). */
+    emit?: (event: AgentStreamEvent) => void;
+    /** Structured logger (already carrying run identity as fields). */
+    logger?: Logger;
+}
+export interface RunOptions {
+    maxSteps?: number;
+    signal?: AbortSignal;
+}
+/** Combine the defined signals into one, or return undefined when none. */
+export declare function anySignal(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined;
+export declare class StepLoop {
+    private readonly deps;
+    private readonly log;
+    private readonly loopDetector;
+    private readonly captchaWatchdog;
+    private nSteps;
+    private consecutiveFailures;
+    private lastStepDurationSeconds?;
+    private pendingNudges;
+    private done;
+    private stopped;
+    private paused;
+    private pauseGate?;
+    private pauseRelease?;
+    private maxSteps;
+    private runSignal?;
+    private runDeadline?;
+    constructor(deps: StepLoopDeps);
+    /** Fan an event out to the O2 stream (no-op when no sink is wired). */
+    private emit;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    get isDone(): boolean;
+    /** Current consecutive-failure count (observability / tests). */
+    get failures(): number;
+    /** The 1-based number of the step about to run (observability / tests). */
+    get currentStep(): number;
+    run(options?: RunOptions): Promise<AgentHistoryList>;
+    /**
+     * One perceive→decide→act→record cycle. Returns whether the task is now done.
+     * A no-op (returns false) when paused/stopped/already-done.
+     */
+    step(): Promise<boolean>;
+    private waitWhilePaused;
+    /** Consecutive-failure accounting (design/07 §7.2.3). */
+    private accountFailures;
+    private handleLlmError;
+    /** A whole-step failure: increment the counter and record an error result. */
+    private recordWholeStepFailure;
+    /** Append a synthetic terminal failure entry (max steps / consecutive failures). */
+    private recordSyntheticFailure;
+    /** Fold a step into both the message-manager history and the AgentHistoryList. */
+    private recordStep;
+    private metadata;
+    private buildContext;
+    /** A single-key union carrying only `done` (forced-termination schema). */
+    private doneOnlyUnion;
+}
+//# sourceMappingURL=step-loop.d.ts.map

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

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

package/dist/agent/variable-detector.d.ts

@@ -0,0 +1,19 @@
+import { AgentHistoryList } from "./history";
+export interface DetectedVariable {
+    name: string;
+    value: string;
+    stepIndex: number;
+    actionIndex: number;
+    /** Which param carried the value ('text' on input_text, 'query' on extract_content). */
+    param: "text" | "query";
+}
+/** Scan a history for reusable variables. Deterministic — same history → same names. */
+export declare function detectVariables(history: AgentHistoryList): DetectedVariable[];
+/**
+ * Deep-copy `history` and exact-string-replace each detected variable's
+ * recorded value with the caller-supplied replacement (variables not present
+ * in `values` are left untouched). `structuredClone` is enough — every field
+ * on `AgentHistory` is JSON-safe (design/05 invariant).
+ */
+export declare function substituteVariables(history: AgentHistoryList, detected: readonly DetectedVariable[], values: Readonly<Record<string, string>>): AgentHistoryList;
+//# sourceMappingURL=variable-detector.d.ts.map

package/dist/agent/variable-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-detector.d.ts","sourceRoot":"","sources":["../../src/agent/variable-detector.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG7C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AA8ED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CA2C7E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,gBAAgB,CAkBlB"}

package/dist/agent/video.d.ts

@@ -0,0 +1,12 @@
+import type { ScreencastFrame } from "@ap3x/browser";
+import { type GifOptions } from "./gif";
+export type VideoOptions = GifOptions;
+/**
+ * Build a video-as-GIF artifact from screencast frames. Frame duration
+ * defaults to a much shorter interval than the per-step run GIF (screencast
+ * frames are dense in time, not one per agent step) — override via
+ * `frameDurationMs` if the recorder's `everyNthFrame`/framerate warrants it.
+ * Returns `undefined` when there is nothing decodable to encode.
+ */
+export declare function generateRunVideoGif(frames: readonly ScreencastFrame[], options?: VideoOptions): Uint8Array | undefined;
+//# sourceMappingURL=video.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../../src/agent/video.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,OAAO,CAAC;AAG3D,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAkBtC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,GAAE,YAAiB,GACzB,UAAU,GAAG,SAAS,CAMxB"}

package/dist/chunk-32HNRAQS.js

@@ -0,0 +1,82 @@
+// src/testing.ts
+import {
+  fauxAssistantMessage,
+  fauxToolCall,
+  registerFauxProvider
+} from "@ap3x/ai";
+var RESPOND_TOOL = "respond";
+function isAssistantMessage(step) {
+  return "role" in step && step.role === "assistant";
+}
+function toFaux(step) {
+  if (isAssistantMessage(step)) return step;
+  return fauxAssistantMessage(
+    fauxToolCall(RESPOND_TOOL, step),
+    {
+      stopReason: "stop"
+    }
+  );
+}
+function scriptedLlm(steps = []) {
+  const registration = registerFauxProvider();
+  registration.setResponses(steps.map(toFaux));
+  return {
+    model: registration.getModel(),
+    registration,
+    push(more) {
+      registration.appendResponses(more.map(toFaux));
+    },
+    unregister() {
+      registration.unregister();
+    }
+  };
+}
+function agentStep(actions, fields = {}) {
+  return {
+    evaluation_previous_goal: "",
+    memory: "",
+    next_goal: "",
+    ...fields,
+    action: actions
+  };
+}
+function emptyLlmResponse() {
+  return fauxAssistantMessage([], { stopReason: "stop" });
+}
+function truncatedLlmResponse() {
+  return fauxAssistantMessage(fauxToolCall(RESPOND_TOOL, {}), { stopReason: "length" });
+}
+function invalidLlmResponse() {
+  return fauxAssistantMessage(fauxToolCall(RESPOND_TOOL, { memory: "no action here" }), {
+    stopReason: "stop"
+  });
+}
+function transportErrorResponse(message = "provider error") {
+  return fauxAssistantMessage([], { stopReason: "error", errorMessage: message });
+}
+function collectingLogger(base = {}) {
+  const lines = [];
+  const make = (fields) => {
+    const record = (level, message, extra) => {
+      lines.push({ level, message, fields: { ...fields, ...extra } });
+    };
+    return {
+      debug: (message, extra) => record("debug", message, extra),
+      info: (message, extra) => record("info", message, extra),
+      warn: (message, extra) => record("warn", message, extra),
+      error: (message, extra) => record("error", message, extra),
+      child: (extra) => make({ ...fields, ...extra })
+    };
+  };
+  return { logger: make(base), lines };
+}
+
+export {
+  scriptedLlm,
+  agentStep,
+  emptyLlmResponse,
+  truncatedLlmResponse,
+  invalidLlmResponse,
+  transportErrorResponse,
+  collectingLogger
+};