@ap3x/browser-agent 0.1.0

package/dist/mcp/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/mcp/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/mcp/bin.ts"],"names":[],"mappings":""}

package/dist/mcp/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  logStderr,
+  runBrowserMcpServer
+} from "../chunk-UZALZUEE.js";
+
+// src/mcp/bin.ts
+import { BrowserSession } from "@ap3x/browser";
+async function main() {
+  const cdpUrl = process.env.AP3X_BROWSER_CDP_URL;
+  const session = cdpUrl ? await BrowserSession.connect(cdpUrl) : await BrowserSession.launch();
+  await runBrowserMcpServer({ session });
+}
+main().catch((error) => {
+  logStderr(
+    `browser MCP server failed to start: ${error instanceof Error ? error.stack ?? error.message : String(error)}`
+  );
+  process.exitCode = 1;
+});

package/dist/mcp/client.d.ts

@@ -0,0 +1,45 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type TSchema } from "@sinclair/typebox";
+import { type ActionDefinition } from "../tools/registry";
+/**
+ * Synthesize a TypeBox param schema from a remote MCP tool's JSON-Schema
+ * `inputSchema`. SHALLOW by design — top-level property types only; nested shapes
+ * stay permissive because the remote server is the deep validator. Returns
+ * `undefined` (⇒ the tool is SKIPPED, never fatal) when the schema isn't a plain
+ * object schema or carries composition keywords the action union can't represent.
+ * Every leaf is a real, registered TypeBox kind, so the registry's `Value.Check`
+ * validates without throwing — the wrapper can never explode inside the executor.
+ */
+export declare function synthesizeParamSchema(inputSchema: unknown): TSchema | undefined;
+export interface ImportMcpToolsOptions {
+    /** Prefix each generated action name (avoids collisions with built-ins). */
+    prefix?: string;
+    /** Keep only tools whose (unprefixed) name passes this predicate. */
+    toolFilter?: (name: string) => boolean;
+}
+/**
+ * List an already-connected MCP client's tools and turn each into a browser-agent
+ * action. A tool with an unconvertible schema is skipped (logged), not fatal —
+ * the returned list is every tool that DID convert. Register them on a `Registry`
+ * to expose them to the agent's LLM as ordinary actions.
+ */
+export declare function importMcpTools(client: Client, options?: ImportMcpToolsOptions): Promise<Array<ActionDefinition<TSchema>>>;
+export interface McpStdioConnection {
+    /** The server executable (e.g. `npx`). */
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    clientInfo?: {
+        name?: string;
+        version?: string;
+    };
+}
+/**
+ * Convenience: spawn a stdio MCP server and return a connected `Client`, ready to
+ * hand to {@link importMcpTools}. A connection failure throws
+ * `AgentMCPConnectionError` (reused from @ap3x/agent-core). For tests, construct a
+ * `Client` over an in-memory transport and pass it to `importMcpTools` directly —
+ * this helper is only the real-process path.
+ */
+export declare function connectMcpClient(connection: McpStdioConnection): Promise<Client>;
+//# sourceMappingURL=client.d.ts.map

package/dist/mcp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/mcp/client.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,mBAAmB,CAAC;AA8BxE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAkB/E;AA0DD,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAsB3C;AAED,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBtF"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./server";
+export * from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAGA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/mcp/log.d.ts

@@ -0,0 +1,6 @@
+import { type Logger } from "../observability/logger";
+/** The package logger, hard-wired to stderr for MCP stdio safety. */
+export declare const mcpLogger: Logger;
+/** Convenience shim for one-line stderr diagnostics (delegates to {@link mcpLogger}). */
+export declare function logStderr(message: string): void;
+//# sourceMappingURL=log.d.ts.map

package/dist/mcp/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/mcp/log.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,yBAAyB,CAAC;AAEpE,qEAAqE;AACrE,eAAO,MAAM,SAAS,EAAE,MAItB,CAAC;AAEH,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,36 @@
+import type { Api, Model, ProviderStreamOptions } from "@ap3x/ai";
+import { BrowserDriver, type BrowserSession } from "@ap3x/browser";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ExtractionLlm, Registry } from "../tools/registry";
+export interface BrowserMcpServerOptions {
+    /** The session to drive. */
+    session: BrowserSession;
+    /** Override the driver built from `session`. */
+    driver?: BrowserDriver;
+    /** Action registry (default: the built-in set). Only the mapped tools are exposed. */
+    registry?: Registry;
+    /** Enables `browser_run_agent`. Omit to expose only the direct browser controls. */
+    llm?: {
+        model: Model<Api>;
+        extraction?: ExtractionLlm;
+        /** Per-call overrides (apiKey/headers/etc.) forwarded to the spun-up Agent. */
+        streamOptions?: ProviderStreamOptions;
+    };
+    /** Read/upload-only paths the actions may reference. */
+    availableFilePaths?: string[];
+    /** Base dir for the ActionContext FileSystem (default: an OS-temp dir). */
+    fileSystemDir?: string;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+}
+/**
+ * Build (but do not start) the low-level MCP {@link Server}. Connect it to a
+ * transport — {@link runBrowserMcpServer} uses stdio; tests use the SDK's
+ * in-memory transport pair.
+ */
+export declare function createBrowserMcpServer(options: BrowserMcpServerOptions): Server;
+/** Create the server and serve it over stdio (the real-process entry point). */
+export declare function runBrowserMcpServer(options: BrowserMcpServerOptions): Promise<Server>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE,OAAO,KAAK,EAAiB,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA0BhF,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,gDAAgD;IAChD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,oFAAoF;IACpF,GAAG,CAAC,EAAE;QACJ,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAClB,UAAU,CAAC,EAAE,aAAa,CAAC;QAC3B,+EAA+E;QAC/E,aAAa,CAAC,EAAE,qBAAqB,CAAC;KACvC,CAAC;IACF,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAmDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CA2I/E;AAED,gFAAgF;AAChF,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAK3F"}

package/dist/observability/logger.d.ts

@@ -0,0 +1,25 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Arbitrary structured fields attached to a log line. */
+export type LogFields = Record<string, unknown>;
+/** The surface the agent logs through. Inject your own or use {@link createLogger}. */
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    /** A logger that carries `fields` on every line (merged over this one's). */
+    child(fields: LogFields): Logger;
+}
+export interface LoggerOptions {
+    /** Lowest level that is emitted. Default `info`. */
+    level?: LogLevel;
+    /** Fields carried on every line (the logger's identity). */
+    fields?: LogFields;
+    /** Where a formatted line goes. Default: the matching `console` method. */
+    sink?: (level: LogLevel, line: string) => void;
+}
+/** A structured console logger with a level gate and child loggers. */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/** A logger that discards everything. The library default (no output unless asked). */
+export declare const silentLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,uFAAuF;AACvF,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjD,6EAA6E;IAC7E,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;CAClC;AAID,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AA4BD,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAkBhE;AAED,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,MAQ1B,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,37 @@
+import { type Api, type AssistantMessage, type FauxProviderRegistration, type Model } from "@ap3x/ai";
+import type { AgentOutput } from "./agent/output-schema";
+import type { LogFields, LogLevel, Logger } from "./observability/logger";
+/** A scripted turn: an AgentOutput (wrapped as a tool call) or a raw faux message. */
+export type ScriptedStep = AgentOutput | AssistantMessage;
+export interface ScriptedLlmHandle {
+    /** The model to hand to `new Agent({ llm: { model } })`. */
+    model: Model<Api>;
+    registration: FauxProviderRegistration;
+    /** Append more scripted turns. */
+    push(steps: ScriptedStep[]): void;
+    unregister(): void;
+}
+/** Register a faux provider that replays `steps` as structured-output responses. */
+export declare function scriptedLlm(steps?: ScriptedStep[]): ScriptedLlmHandle;
+/** Build a valid AgentOutput from an action list (brain fields default to empty). */
+export declare function agentStep(actions: Array<Record<string, unknown>>, fields?: Partial<AgentOutput>): AgentOutput;
+/** A response with no tool call and no text → generateObject reports `empty`. */
+export declare function emptyLlmResponse(): AssistantMessage;
+/** A response truncated at the token limit → generateObject reports `truncated`. */
+export declare function truncatedLlmResponse(): AssistantMessage;
+/** A schema-violating response (no `action`) → generateObject reports `invalid`. */
+export declare function invalidLlmResponse(): AssistantMessage;
+/** A provider transport error → generateObject reports `transport`. */
+export declare function transportErrorResponse(message?: string): AssistantMessage;
+/** One captured log line. */
+export interface CapturedLog {
+    level: LogLevel;
+    message: string;
+    fields: LogFields;
+}
+/** A {@link Logger} that records every line (with merged child fields) into `lines`. */
+export declare function collectingLogger(base?: LogFields): {
+    logger: Logger;
+    lines: CapturedLog[];
+};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,GAAG,EACR,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAE7B,KAAK,KAAK,EAIX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAK1E,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,YAAY,EAAE,wBAAwB,CAAC;IACvC,kCAAkC;IAClC,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAClC,UAAU,IAAI,IAAI,CAAC;CACpB;AAgBD,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,GAAE,YAAY,EAAO,GAAG,iBAAiB,CAazE;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CACvB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAChC,WAAW,CAQb;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,gBAAgB,CAEnD;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,IAAI,gBAAgB,CAEvD;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,gBAAgB,CAIrD;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,OAAO,SAAmB,GAAG,gBAAgB,CAEnF;AAED,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,SAAc,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,CAe/F"}

package/dist/testing.js

@@ -0,0 +1,18 @@
+import {
+  agentStep,
+  collectingLogger,
+  emptyLlmResponse,
+  invalidLlmResponse,
+  scriptedLlm,
+  transportErrorResponse,
+  truncatedLlmResponse
+} from "./chunk-32HNRAQS.js";
+export {
+  agentStep,
+  collectingLogger,
+  emptyLlmResponse,
+  invalidLlmResponse,
+  scriptedLlm,
+  transportErrorResponse,
+  truncatedLlmResponse
+};

package/dist/tools/actions.d.ts

@@ -0,0 +1,9 @@
+import { type TSchema } from "@sinclair/typebox";
+import { type ActionDefinition, Registry } from "./registry";
+/** Every built-in action, in a stable order. */
+export declare const BUILTIN_ACTIONS: ReadonlyArray<ActionDefinition<TSchema>>;
+/** Register the built-in action set on a registry. */
+export declare function registerBuiltins(registry: Registry): void;
+/** A fresh registry preloaded with the built-in action set. */
+export declare function createDefaultRegistry(): Registry;
+//# sourceMappingURL=actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/tools/actions.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,QAAQ,EAAgB,MAAM,YAAY,CAAC;AAkX/F,gDAAgD;AAChD,eAAO,MAAM,eAAe,EAqBZ,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;AAEzD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAEzD;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,IAAI,QAAQ,CAIhD"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,125 @@
+import type { BrowserDriver, BrowserSession, CdpTransport } from "@ap3x/browser";
+import { type Static, type TSchema } from "@sinclair/typebox";
+import type { FileSystem } from "../filesystem/file-system";
+import type { SecretMap, SensitiveData } from "./sensitive";
+import { type ActionResult } from "./types";
+/**
+ * The extraction-LLM seam. M4 leaves this undefined and `extract_content` returns
+ * the page's serialized text; M5 wires it to `@ap3x/ai` for real summarization.
+ */
+export interface ExtractionLlm {
+    extract(prompt: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+/**
+ * The ONE typed injection object handed to every action's `execute` (E5). It
+ * carries every capability an action needs, instead of injecting them by
+ * parameter name.
+ */
+export interface ActionContext {
+    /** The live session — for primitives the driver doesn't surface (dropdowns, go-back, upload). */
+    session: BrowserSession;
+    /** The typed facade — navigate / click / type / scroll / tabs / screenshot / extract. */
+    driver: BrowserDriver;
+    /** The current page URL (domain scoping, extraction provenance). */
+    pageUrl: string;
+    /**
+     * Raw CDP transport, for custom actions that reach the protocol directly.
+     * Optional: no built-in action needs it, and a {@link BrowserSession} does not
+     * expose its transport publicly, so the step loop leaves it undefined. A custom
+     * action that requires raw CDP must be handed a transport by its author.
+     */
+    cdpClient?: CdpTransport;
+    /** The agent's workspace filesystem. */
+    fileSystem: FileSystem;
+    /** Optional extraction LLM (M5). */
+    extractionLlm?: ExtractionLlm;
+    /** Read/upload-only paths the agent may reference. */
+    availableFilePaths: readonly string[];
+    /** Whether sensitive data is in play for this step (drives masked logging). */
+    hasSensitiveData: boolean;
+    /**
+     * The composed per-step abort (run abort ∪ step timeout — design/06 §6.7–6.8).
+     * Actions forward it into driver/session/extraction calls so a run-abort or
+     * step-timeout cancels IN-FLIGHT work, not only the gap between actions.
+     */
+    signal?: AbortSignal;
+}
+/** The shape passed to {@link defineAction}. */
+export interface ActionDefinition<S extends TSchema> {
+    /** Unique action name — the single key in the wire JSON `{ name: params }`. */
+    name: string;
+    /** One-line description shown to the model. */
+    description: string;
+    /** TypeBox param schema (the trust boundary). */
+    schema: S;
+    /** Glob URL filters. When set, the action only exists on matching pages. */
+    domains?: string[];
+    /** Abort remaining queued actions after this one (page-changing actions). */
+    terminatesSequence?: boolean;
+    /** The handler. Typed against the schema — a mismatch is a compile error. */
+    execute(params: Static<S>, ctx: ActionContext): Promise<ActionResult> | ActionResult;
+}
+/** A registered action, type-erased for storage. */
+export interface RegisteredAction {
+    name: string;
+    description: string;
+    schema: TSchema;
+    domains?: string[];
+    terminatesSequence: boolean;
+    execute(params: unknown, ctx: ActionContext): Promise<ActionResult> | ActionResult;
+}
+/**
+ * Define a custom (or built-in) action. Identity function — it exists purely so
+ * the generic `S` is inferred and `execute`'s params are typed. This is the
+ * public extension API: `registry.register(defineAction({ ... }))`.
+ */
+export declare function defineAction<S extends TSchema>(def: ActionDefinition<S>): ActionDefinition<S>;
+export declare class Registry {
+    private readonly actions;
+    private readonly excluded;
+    private readonly unionCache;
+    /** Register an action. Later registration of an excluded name is a no-op. */
+    register<S extends TSchema>(def: ActionDefinition<S>): void;
+    /**
+     * A shallow copy sharing the same action definitions. The step loop clones a
+     * caller's registry before applying a vision filter so the caller's object is
+     * never mutated (E7). Excluded names carry over.
+     */
+    clone(): Registry;
+    /** Remove an action and block it from being re-registered. */
+    exclude(name: string): void;
+    get(name: string): RegisteredAction | undefined;
+    /** Actions available on `pageUrl` (unfiltered + domain-matching), name-sorted. */
+    available(pageUrl?: string): RegisteredAction[];
+    /**
+     * The per-page union of single-key action objects for structured output (A8).
+     * Cached by the set of admitted action names (so equivalent URLs share one).
+     */
+    actionUnion(pageUrl?: string): TSchema;
+    /** `name: description (param=type, ...)` lines for the prompt. */
+    promptDescriptions(pageUrl?: string): string;
+    /**
+     * Execute one action. `<secret>key</secret>` tags are substituted (enforcement
+     * point 3) and — ALWAYS, even with no secrets configured — scanned for
+     * survivors: any unresolved `<secret>…</secret>` short-circuits to an
+     * `ActionResult.error` and the action never runs, so a literal tag can never be
+     * typed (C5). Params are then validated against the action's schema before
+     * `execute`; afterwards every result string is masked against the resolved
+     * secrets so a real substituted value can never land in history.
+     *
+     * `allSensitiveData` (M8 follow-up), when provided, masks results against
+     * EVERY domain's secret values (mirroring `maskOutbound`'s all-domains
+     * approach), not just `secrets` (the current-URL-scoped subset used for
+     * substitution). Page content is not domain-sandboxed the way secret
+     * substitution is — a domain-B secret echoed while acting on domain A must
+     * still be masked on this method's outbound text (narration / event stream /
+     * ToolResultMessage), the same way the LLM-prompt path already masks via
+     * `maskOutbound` in the message manager. Without it, masking falls back to
+     * `secrets` alone (the pre-M11 behavior — still correct for the single-domain
+     * case, just narrower).
+     */
+    execute(name: string, rawParams: unknown, ctx: ActionContext, secrets?: SecretMap, allSensitiveData?: SensitiveData): Promise<ActionResult>;
+}
+//# sourceMappingURL=registry.d.ts.map

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

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

package/dist/tools/sensitive.d.ts

@@ -0,0 +1,59 @@
+/** A secret value: a literal string, or a TOTP seed that mints codes on demand. */
+export type SecretValue = string | {
+    totpSeed: string;
+};
+/** `{ [domainPattern]: { [key]: value } }`. `'*'` = applies to any URL. */
+export type SensitiveData = Record<string, Record<string, SecretValue>>;
+/** Resolved secrets for a single URL: key → value. */
+export type SecretMap = Record<string, SecretValue>;
+/**
+ * The secrets that apply to `url` — every domain pattern that matches, flattened.
+ * Empty-string values are dropped (they count as missing). New-tab pages match
+ * nothing (the domain matcher already returns false for them).
+ */
+export declare function resolveSecretsForUrl(data: SensitiveData, url: string): SecretMap;
+/** The placeholder key names applicable to `url` (for the prompt block). */
+export declare function applicablePlaceholders(data: SensitiveData, url: string): string[];
+/**
+ * Point 1 — the `<sensitive_data>` prompt block for `url`, or `undefined` when no
+ * secrets apply. Lists names only; never values.
+ */
+export declare function sensitiveDataDescription(data: SensitiveData, url: string): string | undefined;
+/**
+ * Point 2 — mask every real value found in `text` back to `<secret>key</secret>`,
+ * longest value first. Domain-AGNOSTIC: all domains' values are masked (injection
+ * is domain-scoped, but a value could have been echoed anywhere). TOTP seeds have
+ * no static value and are not masked.
+ */
+export declare function maskOutbound(text: string, data: SensitiveData): string;
+/**
+ * Point 2, applied to a resolved {@link SecretMap} (key→value for one URL) rather
+ * than the whole {@link SensitiveData}: mask every real string value back to
+ * `<secret>key</secret>`, LONGEST value first. Used to scrub any secret that a
+ * post-substitution action wrote into its result text, so a real value can never
+ * land in history — regardless of the caller's `hasSensitiveData` flag. TOTP
+ * seeds have no static value and are not masked.
+ */
+export declare function maskSecretMap(text: string, secrets: SecretMap): string;
+/**
+ * Point 3 — substitute `<secret>key</secret>` tags (and bare strings that exactly
+ * equal a key name) throughout `params` with real values. Returns the substituted
+ * value plus the list of UNRESOLVED placeholder keys (referenced by a tag but not
+ * in `secrets`). The caller MUST error out when `unresolved` is non-empty rather
+ * than let a literal `<secret>` tag reach the page (C5).
+ */
+export declare function substituteSecrets(params: unknown, secrets: SecretMap): {
+    value: unknown;
+    unresolved: string[];
+};
+export interface TotpOptions {
+    /** Unix time in seconds (default: now). */
+    time?: number;
+    /** Time step in seconds (default 30). */
+    step?: number;
+    /** Number of digits (default 6). */
+    digits?: number;
+}
+/** Generate a TOTP code from a base32 seed (RFC 6238). */
+export declare function totp(seed: string, options?: TotpOptions): string;
+//# sourceMappingURL=sensitive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive.d.ts","sourceRoot":"","sources":["../../src/tools/sensitive.ts"],"names":[],"mappings":"AAsBA,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAExE,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAcpD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAShF;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAatE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,MAAM,CAWtE;AASD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,SAAS,GACjB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CA0B1C;AAyBD,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAkBpE"}

package/dist/tools/types.d.ts

@@ -0,0 +1,117 @@
+import type { ElementIndex } from "@ap3x/browser";
+/** One action the agent can take. Discriminated on `kind`. */
+export type Action = {
+    kind: "navigate";
+    url: string;
+    newTab?: boolean;
+} | {
+    kind: "go_back";
+} | {
+    kind: "click";
+    index: ElementIndex;
+} | {
+    kind: "input_text";
+    index: ElementIndex;
+    text: string;
+    clear?: boolean;
+} | {
+    kind: "scroll";
+    down?: boolean;
+    pages?: number;
+    index?: ElementIndex;
+} | {
+    kind: "scroll_to_text";
+    text: string;
+} | {
+    kind: "send_keys";
+    keys: string;
+} | {
+    kind: "select_dropdown";
+    index: ElementIndex;
+    text: string;
+} | {
+    kind: "get_dropdown_options";
+    index: ElementIndex;
+} | {
+    kind: "switch_tab";
+    tabId: string;
+} | {
+    kind: "open_tab";
+    url: string;
+} | {
+    kind: "close_tab";
+    tabId: string;
+} | {
+    kind: "upload_file";
+    index: ElementIndex;
+    path: string;
+} | {
+    kind: "wait";
+    seconds?: number;
+} | {
+    kind: "extract_content";
+    query: string;
+} | {
+    kind: "write_file";
+    fileName: string;
+    content: string;
+    append?: boolean;
+} | {
+    kind: "append_file";
+    fileName: string;
+    content: string;
+} | {
+    kind: "read_file";
+    fileName: string;
+} | {
+    kind: "replace_file";
+    fileName: string;
+    oldStr: string;
+    newStr: string;
+} | {
+    kind: "done";
+    success: boolean;
+    text: string;
+    filesToDisplay?: string[];
+};
+/** Fields common to every action result — the action→prompt feedback contract. */
+interface ActionResultBase {
+    /** Error text. Always folded into long-term memory; increments the failure count. */
+    error?: string;
+    /** Action output text. `done` text lands here. */
+    extractedContent?: string;
+    /** True ⇒ `extractedContent` goes to a one-shot read-state, not long-term memory. */
+    includeExtractedContentOnlyOnce?: boolean;
+    /** A line persisted verbatim into agent history (preferred over `extractedContent`). */
+    longTermMemory?: string;
+    /** File paths surfaced in the done message. */
+    attachments?: string[];
+    /** Images kept separate from text for efficient prompting. */
+    images?: Array<{
+        name: string;
+        data: string;
+    }>;
+    /** Observability side channel (e.g. click coordinates). */
+    metadata?: Record<string, unknown>;
+    /** @deprecated legacy routing flag; kept for shape parity. */
+    includeInMemory?: boolean;
+}
+/** Result of a non-terminal step. Carries NO success verdict (E3). */
+export interface StepResult extends ActionResultBase {
+    isDone?: false;
+}
+/** Result of the terminal `done` action. `success` is only legal here. */
+export interface DoneResult extends ActionResultBase {
+    isDone: true;
+    success: boolean;
+}
+/** Every action returns one of these. `success` exists only on `DoneResult`. */
+export type ActionResult = StepResult | DoneResult;
+/** Build a non-terminal result. */
+export declare function stepResult(fields?: ActionResultBase): StepResult;
+/** Build a terminal `done` result. `success` cannot be set without this path. */
+export declare function doneResult(success: boolean, fields?: ActionResultBase): DoneResult;
+/** Narrow a result to the terminal variant. */
+export declare function isDoneResult(result: ActionResult): result is DoneResult;
+export {};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export * from "./tools/types";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,cAAc,eAAe,CAAC"}

package/dist/usage/ledger.d.ts

@@ -0,0 +1,27 @@
+import type { Usage } from "@ap3x/ai";
+/** Per-model rollup. `invocations` counts generateObject calls for that model. */
+export interface ModelUsageStats {
+    model: string;
+    invocations: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: number;
+}
+/** The whole-run usage summary rendered into `AgentHistoryList.usage`. */
+export interface UsageSummary {
+    perModel: ModelUsageStats[];
+    totalTokens: number;
+    totalCost: number;
+    totalInvocations: number;
+}
+export declare class UsageLedger {
+    private readonly byModel;
+    /** Fold one LLM call's usage into the running totals for `model`. */
+    record(model: string, usage: Usage): void;
+    /** The end-of-run summary (per-model + grand totals). */
+    summary(): UsageSummary;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/dist/usage/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/usage/ledger.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAwBzC,yDAAyD;IACzD,OAAO,IAAI,YAAY;CASxB"}