browser-debugging-daemon 1.0.0

package/index.js

@@ -0,0 +1,223 @@
+/**
+ * browser-debugging-daemon SDK
+ *
+ * Programmatic access to browser automation, autonomous subagent,
+ * and task orchestration — no daemon or MCP server needed.
+ *
+ * @example
+ * import { BrowserAgent } from 'browser-debugging-daemon';
+ * const agent = new BrowserAgent();
+ * await agent.start();
+ * const obs = await agent.observe();
+ * await agent.click({ id: 12 });
+ * const result = await agent.delegate('Search for AI news');
+ * await agent.stop();
+ */
+
+import { BrowserRuntime } from "./runtime/BrowserRuntime.js";
+import { BrowserSubagent } from "./subagent/BrowserSubagent.js";
+import { TaskRunner } from "./orchestrator/TaskRunner.js";
+import { ArtifactStore } from "./runtime/ArtifactStore.js";
+import {
+    clearOverlays,
+    collectInteractableElements,
+    collectPageContent,
+    refreshTarget,
+} from "./shared.js";
+
+/**
+ * High-level facade that composes BrowserRuntime, BrowserSubagent,
+ * and TaskRunner behind a single API.
+ */
+export class BrowserAgent {
+    /**
+     * @param {object} [options]
+     * @param {string} [options.baseDir]  - Directory for artifacts/state (default: auto-resolved)
+     * @param {object} [options.plannerOptions] - Options forwarded to OpenAIPlanner
+     * @param {number} [options.defaultMaxSteps] - Default max steps for delegate (default: 12)
+     * @param {number} [options.handoffTimeoutMs] - Handoff timeout for task runs (default: 300000)
+     * @param {BrowserRuntime} [options.runtime] - Inject a custom BrowserRuntime
+     * @param {BrowserSubagent} [options.subagent] - Inject a custom BrowserSubagent
+     */
+    constructor(options = {}) {
+        const baseDir = options.baseDir || import.meta.dirname;
+
+        this.runtime = options.runtime || new BrowserRuntime(baseDir);
+        this.subagent = options.subagent || new BrowserSubagent(this.runtime, {
+            plannerOptions: options.plannerOptions,
+            defaultMaxSteps: options.defaultMaxSteps,
+            ...(options.plannerOptions || {}),
+        });
+        this.taskRunner = new TaskRunner(baseDir, {
+            runtime: this.runtime,
+            subagent: this.subagent,
+            plannerOptions: options.plannerOptions,
+            handoffTimeoutMs: options.handoffTimeoutMs,
+        });
+    }
+
+    // ── Browser lifecycle ──────────────────────────────────
+
+    async start(options = {}) {
+        return this.runtime.start(options);
+    }
+
+    async stop() {
+        return this.runtime.stop();
+    }
+
+    // ── Browser control ────────────────────────────────────
+
+    async goto(url) {
+        return this.runtime.goto(url);
+    }
+
+    async observe() {
+        return this.runtime.observe();
+    }
+
+    async click(id) {
+        return this.runtime.click(id);
+    }
+
+    async type(id, text, options = {}) {
+        return this.runtime.type(id, text, options);
+    }
+
+    async hover(id) {
+        return this.runtime.hover(id);
+    }
+
+    async keypress(key) {
+        return this.runtime.keypress(key);
+    }
+
+    async scroll(direction) {
+        return this.runtime.scroll(direction);
+    }
+
+    async evaluate(expression) {
+        return this.runtime.evaluate(expression);
+    }
+
+    async selectOption(id, values) {
+        return this.runtime.selectOption(id, values);
+    }
+
+    async handleDialog(options = {}) {
+        return this.runtime.handleDialog(options);
+    }
+
+    async goBack() {
+        return this.runtime.goBack();
+    }
+
+    async tabAction(action, options = {}) {
+        return this.runtime.tabAction(action, options);
+    }
+
+    async waitFor(options = {}) {
+        return this.runtime.waitFor(options);
+    }
+
+    async upload(id, options = {}) {
+        return this.runtime.upload(id, options);
+    }
+
+    async drag(fromId, toId) {
+        return this.runtime.drag(fromId, toId);
+    }
+
+    async dragFile(options = {}) {
+        return this.runtime.dragFile(options);
+    }
+
+    // ── Autonomous delegation ──────────────────────────────
+
+    async delegate(taskInstruction, options = {}) {
+        return this.subagent.delegateTask(taskInstruction, options);
+    }
+
+    async verifyProgress(input) {
+        return this.subagent.verifyProgress(input);
+    }
+
+    // ── Task orchestration ─────────────────────────────────
+
+    createRun(taskInstruction, options = {}) {
+        return this.taskRunner.createRun(taskInstruction, options);
+    }
+
+    createRunFromTemplate(templateId, overrides = {}) {
+        return this.taskRunner.createRunFromTemplate(templateId, overrides);
+    }
+
+    listRuns(limit = 20) {
+        return this.taskRunner.listRuns(limit);
+    }
+
+    getRun(id) {
+        return this.taskRunner.getRun(id);
+    }
+
+    replyToRun(id, instruction) {
+        return this.taskRunner.replyToRun(id, instruction);
+    }
+
+    resumeRun(id, instruction) {
+        return this.taskRunner.resumeRun(id, instruction);
+    }
+
+    abortRun(id, reason) {
+        return this.taskRunner.abortRun(id, reason);
+    }
+
+    // ── Templates ──────────────────────────────────────────
+
+    listTemplates(limit = 100) {
+        return this.taskRunner.listTemplates(limit);
+    }
+
+    getTemplate(id) {
+        return this.taskRunner.getTemplate(id);
+    }
+
+    saveTemplate(templateInput) {
+        return this.taskRunner.saveTemplate(templateInput);
+    }
+
+    deleteTemplate(id) {
+        return this.taskRunner.deleteTemplate(id);
+    }
+
+    compareTemplateRuns(templateId, options = {}) {
+        return this.taskRunner.compareTemplateRuns(templateId, options);
+    }
+
+    // ── Diagnostics ────────────────────────────────────────
+
+    async getCdpHealth(options = {}) {
+        return this.runtime.getCdpHealth(options);
+    }
+
+    async getCdpDiagnostics(options = {}) {
+        return this.runtime.getCdpDiagnostics(options);
+    }
+
+    getDebugState(limit = 20) {
+        return this.runtime.getDebugState(limit);
+    }
+
+    async auditTextLayout(options = {}) {
+        return this.runtime.auditTextLayout(options);
+    }
+}
+
+// ── Advanced exports ────────────────────────────────────────
+// Direct class access for users who need fine-grained control.
+
+export { BrowserRuntime };
+export { BrowserSubagent };
+export { TaskRunner };
+export { ArtifactStore };
+export { clearOverlays, collectInteractableElements, collectPageContent, refreshTarget };