@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/automation/browser-task-tools/server.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Per-task `aitne-browser` MCP server composer —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * One instance per task. The runner builds a fresh server bound to
+ * the task's live Playwright `Page`, hands it to the Claude SDK via
+ * `mcpServers: { "aitne-browser": <instance> }`, and tears it down
+ * with the BrowserContext when the task terminates.
+ *
+ * Why per-task (not the shared `aitne-observations` shape):
+ *   - Tool handlers need direct access to the per-task `Page` to call
+ *     `page.click(...)`, `page.screenshot(...)`, etc.
+ *   - The Page changes when a popup auto-close fires; the runtime
+ *     ref lets the composer pin a single value handlers read at call
+ *     time rather than a closure over a stale Page.
+ *   - Per-task counters (extract-cap, loop-guard) need handler-local
+ *     state that's reset per task.
+ *
+ * Tool name catalogue + Zod schemas come from `./schemas.ts`. Pure
+ * decision logic comes from `./final-confirm-gate.ts`,
+ * `./loop-guard.ts`, `./extract-cap.ts`, `./extract-output.ts`,
+ * `./navigate-guard.ts`, `./dom-snapshot-output.ts`,
+ * `./screenshot-output.ts`. This file is I/O-shaped and excluded
+ * from the 100% coverage gate (vitest.config.ts) per the §13
+ * testing table.
+ */
+import type Database from "better-sqlite3";
+import { type McpSdkServerConfigWithInstance } from "@anthropic-ai/claude-agent-sdk";
+import { type BrowserTaskTransitionEmitter } from "../../../browser-task/browser-task-transition-events.js";
+import type { FinalConfirmHandler } from "../final-confirm-handler.js";
+import { type AccessibilityNodeLike } from "./dom-snapshot-output.js";
+import { type ExtractCapState } from "./extract-cap.js";
+import { type LoopGuardState } from "./loop-guard.js";
+/**
+ * Minimal Playwright `Page` surface the tools need. Typed locally so
+ * this module does not transitively pull `playwright-core` types into
+ * peer tests. The runner downcasts at the composition boundary.
+ */
+export interface PageLike {
+    url(): string;
+    goto(url: string, options?: {
+        timeout?: number;
+        waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    }): Promise<PageResponseLike | null>;
+    screenshot(options?: {
+        fullPage?: boolean;
+        type?: "png" | "jpeg";
+        quality?: number;
+    }): Promise<Buffer>;
+    accessibility: {
+        snapshot(options?: {
+            interestingOnly?: boolean;
+        }): Promise<AccessibilityNodeLike | null>;
+    };
+    click(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    fill(selector: string, value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    type(selector: string, value: string, options?: {
+        timeout?: number;
+        delay?: number;
+    }): Promise<void>;
+    keyboard: {
+        press(key: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+    };
+    mouse: {
+        click(x: number, y: number, options?: {
+            button?: "left";
+        }): Promise<void>;
+        move(x: number, y: number): Promise<void>;
+    };
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+        state?: "attached" | "detached" | "visible" | "hidden";
+    }): Promise<unknown>;
+    waitForURL(urlOrPredicate: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForTimeout(ms: number): Promise<void>;
+    textContent(selector: string, options?: {
+        timeout?: number;
+    }): Promise<string | null>;
+    evaluate<T>(pageFunction: string | ((arg: unknown) => T), arg?: unknown): Promise<T>;
+    locator(selector: string): LocatorLike;
+}
+export interface LocatorLike {
+    first(): LocatorLike;
+    count(): Promise<number>;
+    /** Page-side callback. The function body executes in the browser
+     *  context where DOM types ARE available; the daemon-side typing is
+     *  intentionally `unknown` because daemon tsconfig.lib excludes DOM. */
+    evaluate<T>(pageFunction: string | ((el: unknown) => T)): Promise<T>;
+    innerText(options?: {
+        timeout?: number;
+    }): Promise<string>;
+}
+export interface PageResponseLike {
+    status(): number;
+    url(): string;
+}
+/** Notifier shape the runner injects so the composer can DM the
+ *  originating channel for `ask_user` and `finish`. Production wires
+ *  the messaging adapter's `sendNotification`; tests pass a fake. */
+export interface BrowserTaskMcpNotifier {
+    /** DM the originating channel with the clarification question +
+     *  attached screenshot. Best-effort; failure is logged but does
+     *  not block the tool's structural side effects. */
+    notifyAskUser(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        clarificationId: string;
+        question: string;
+        contextSummary: string;
+        screenshotKey: string | null;
+    }): Promise<void>;
+    /** DM the originating channel with the agent's final report.
+     *  Best-effort. */
+    notifyFinish(input: {
+        taskId: string;
+        originatingChannel: string | null;
+        report: string;
+        screenshotKeys: readonly string[];
+    }): Promise<void>;
+}
+/**
+ * Per-task runtime context. The runner allocates one, mutates the
+ * shared refs as the task progresses (page swap on popup, loop-guard
+ * + extract-cap state advance), and passes it to
+ * `createBrowserTaskMcpServer`.
+ *
+ * `pageRef.current` is read fresh at every tool call so a popup-handled
+ * page swap is transparent. The runner replaces `pageRef.current`
+ * synchronously from the `context.on("page")` handler if the auto-
+ * close logic ever decides to swap rather than close (today: always
+ * close — but the ref gives us future flexibility).
+ */
+export interface BrowserTaskRuntime {
+    taskId: string;
+    /**
+     * Composed allowlist regex frozen at task creation. When `null`
+     * (the default for browser-task as of the 2026-05-27 open-navigation
+     * revision), no positive selector is enforced and the CDP layer
+     * gates only on the denylist.
+     */
+    allowlistRegex: RegExp | null;
+    /**
+     * User-managed hostname denylist (compiled regexes) read from
+     * `runtime-settings.browserTaskHostnameDenylist`. Passed to the §14.7
+     * screenshot retention check. Empty by default — the framework no
+     * longer hardcodes brand entries.
+     */
+    hostnameDenylist?: ReadonlyArray<RegExp>;
+    /** Whether `click` / `press_key` should run the final-confirm gate. */
+    requireFinalConfirm: boolean;
+    /** Where DMs (ask_user / finish) get routed. May be null if no
+     *  primary channel exists; the runner already resolved this via
+     *  §14.8 attestation. */
+    originatingChannel: string | null;
+    /** PA_DATA_DIR — where trace assets land. */
+    paDataDir: string;
+    /** Live Playwright Page. Replace via assignment to support popup
+     *  swap. */
+    pageRef: {
+        current: PageLike;
+    };
+    /** Per-task loop-guard window (§14.5). The composer replaces the
+     *  state in place on every observe(). */
+    loopGuardRef: {
+        current: LoopGuardState;
+    };
+    /** Per-task cumulative extract-cap counter (§14.6). */
+    extractCapRef: {
+        current: ExtractCapState;
+    };
+    /** Final-confirm token issuer + waiter. Shared with B-4's
+     *  `purchase-handler`. The runner injects the daemon-singleton
+     *  instance. */
+    finalConfirmHandler: FinalConfirmHandler;
+    /** DM dispatcher for `ask_user` / `finish`. */
+    notifier: BrowserTaskMcpNotifier;
+    /** Better-sqlite3 handle for action-log + clarifications writes. */
+    db: Database.Database;
+    /** AbortController for the SDK query — wired to §14.11 Q#4 cancel
+     *  semantics. The composer passes the signal down into the
+     *  final-confirm `awaitReply` call so an in-flight cancel
+     *  short-circuits the wait. */
+    abortSignal: AbortSignal;
+    /** BROWSER_TASK_REDESIGN_PLAN.md §9a.5 Shape B — emit a `browser_task`
+     *  SSE event after every state-changing DB write in the tool layer
+     *  (ask_user → awaiting_user, final-confirm gate → final_confirm
+     *  then running on token consume, finish → completed). Defaults to
+     *  the no-op emitter for fixtures that don't stand up a broadcaster. */
+    transitionEmitter: BrowserTaskTransitionEmitter;
+    /** True after the agent has called `yield_for_clarification` —
+     *  read by the runner's post-execute hook to distinguish a clean
+     *  yield from `ask_user_without_yield` (§5 / §14.5 ergonomic). */
+    yieldFlag: {
+        current: boolean;
+    };
+    /** True after the agent has called `finish` — read by the runner
+     *  to confirm a clean completion vs. an SDK-side natural-end. */
+    finishFlag: {
+        current: boolean;
+    };
+    /** Tool-step duration clock. Override via the runner for tests;
+     *  production wires `() => Date.now()`. */
+    nowFn?: () => number;
+}
+/** Allocate a fresh runtime container with empty per-task counters.
+ *  The runner calls this once per task. */
+export declare function createBrowserTaskRuntime(input: {
+    taskId: string;
+    allowlistRegex: RegExp | null;
+    requireFinalConfirm: boolean;
+    originatingChannel: string | null;
+    paDataDir: string;
+    page: PageLike;
+    finalConfirmHandler: FinalConfirmHandler;
+    notifier: BrowserTaskMcpNotifier;
+    db: Database.Database;
+    abortSignal: AbortSignal;
+    transitionEmitter?: BrowserTaskTransitionEmitter;
+    hostnameDenylist?: ReadonlyArray<RegExp>;
+}): BrowserTaskRuntime;
+/** Construct the per-task MCP server. Returns the SDK config the
+ *  caller passes verbatim into `query({ options: { mcpServers: {
+ *  [BROWSER_TASK_MCP_SERVER_NAME]: <return value> } } })`. */
+export declare function createBrowserTaskMcpServer(runtime: BrowserTaskRuntime): McpSdkServerConfigWithInstance;
+declare function parseUrlPattern(pattern: string): RegExp;
+/** Exported for tests that want to verify the action-vocab regex is
+ *  the one the runtime actually uses. */
+export declare const __testing: {
+    ACTION_VOCAB_REGEX: RegExp;
+    parseUrlPattern: typeof parseUrlPattern;
+};
+export {};