opencode-pair-autonomy 1.0.0

package/vendor/mcp/web-agent-mcp/src/config/env.ts

@@ -0,0 +1,107 @@
+import path from "node:path";
+import { z } from "zod";
+
+const envSchema = z.object({
+  WEB_AGENT_SERVER_NAME: z.string().default("web-agent-mcp"),
+  WEB_AGENT_SERVER_VERSION: z.string().default("0.1.0"),
+  WEB_AGENT_DATA_DIR: z.string().default(path.resolve(process.cwd(), ".data")),
+  WEB_AGENT_HEADLESS: z
+    .enum(["true", "false"])
+    .optional()
+    .transform((value) => value === "true"),
+  WEB_AGENT_DEFAULT_LOCALE: z.string().default("en-US"),
+  WEB_AGENT_DEFAULT_TIMEZONE_ID: z.string().optional(),
+  WEB_AGENT_CHROME_USER_DATA_DIR: z.string().optional(),
+  WEB_AGENT_CHROME_PROFILE_DIRECTORY: z.string().optional(),
+  WEB_AGENT_DEFAULT_HUMANIZE: z
+    .enum(["true", "false"])
+    .optional()
+    .transform((value) => value === "true"),
+  WEB_AGENT_DEFAULT_VIEWPORT_WIDTH: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(1440),
+  WEB_AGENT_DEFAULT_VIEWPORT_HEIGHT: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(960),
+  WEB_AGENT_DEFAULT_LAUNCH_ARGS: z.string().optional(),
+  WEB_AGENT_SESSION_MAX_CONSECUTIVE_ERRORS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(3),
+  WEB_AGENT_SESSION_RESTART_COOLDOWN_MS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(30000),
+  WEB_AGENT_HISTORY_DIR: z.string().optional(),
+  WEB_AGENT_ARTIFACTS_DIR: z.string().optional(),
+  WEB_AGENT_PROFILES_DIR: z.string().optional(),
+});
+
+export type WebAgentEnv = {
+  serverName: string;
+  serverVersion: string;
+  dataDir: string;
+  historyDir: string;
+  artifactsDir: string;
+  profilesDir: string;
+  headless: boolean;
+  defaultLocale: string;
+  defaultTimezoneId?: string;
+  chromeUserDataDir?: string;
+  chromeProfileDirectory?: string;
+  defaultHumanize: boolean;
+  defaultLaunchArgs: string[];
+  defaultViewport: {
+    width: number;
+    height: number;
+  };
+  sessionMaxConsecutiveErrors: number;
+  sessionRestartCooldownMs: number;
+};
+
+export function loadEnv(source: NodeJS.ProcessEnv = process.env): WebAgentEnv {
+  const parsed = envSchema.parse(source);
+  const historyDir =
+    parsed.WEB_AGENT_HISTORY_DIR ??
+    path.join(parsed.WEB_AGENT_DATA_DIR, "history");
+  const artifactsDir =
+    parsed.WEB_AGENT_ARTIFACTS_DIR ??
+    path.join(parsed.WEB_AGENT_DATA_DIR, "artifacts");
+  const profilesDir =
+    parsed.WEB_AGENT_PROFILES_DIR ??
+    path.join(parsed.WEB_AGENT_DATA_DIR, "profiles");
+  const defaultLaunchArgs = parsed.WEB_AGENT_DEFAULT_LAUNCH_ARGS
+    ? parsed.WEB_AGENT_DEFAULT_LAUNCH_ARGS.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : [];
+
+  return {
+    serverName: parsed.WEB_AGENT_SERVER_NAME,
+    serverVersion: parsed.WEB_AGENT_SERVER_VERSION,
+    dataDir: parsed.WEB_AGENT_DATA_DIR,
+    historyDir,
+    artifactsDir,
+    profilesDir,
+    headless: parsed.WEB_AGENT_HEADLESS,
+    defaultLocale: parsed.WEB_AGENT_DEFAULT_LOCALE,
+    defaultTimezoneId: parsed.WEB_AGENT_DEFAULT_TIMEZONE_ID,
+    chromeUserDataDir: parsed.WEB_AGENT_CHROME_USER_DATA_DIR,
+    chromeProfileDirectory: parsed.WEB_AGENT_CHROME_PROFILE_DIRECTORY,
+    defaultHumanize: parsed.WEB_AGENT_DEFAULT_HUMANIZE,
+    defaultLaunchArgs,
+    defaultViewport: {
+      width: parsed.WEB_AGENT_DEFAULT_VIEWPORT_WIDTH,
+      height: parsed.WEB_AGENT_DEFAULT_VIEWPORT_HEIGHT,
+    },
+    sessionMaxConsecutiveErrors:
+      parsed.WEB_AGENT_SESSION_MAX_CONSECUTIVE_ERRORS,
+    sessionRestartCooldownMs: parsed.WEB_AGENT_SESSION_RESTART_COOLDOWN_MS,
+  };
+}

package/vendor/mcp/web-agent-mcp/src/core/action-flow.ts

@@ -0,0 +1,82 @@
+import { asWebAgentError } from "./errors.js";
+import { buildFollowUpByGoal, toPolicyEnvelope } from "./observation-flow.js";
+import { recommendObservation } from "./policy-engine.js";
+import { getRetryPolicy } from "./retry-policy.js";
+import { shouldRecommendSessionRestart } from "./session-restart-policy.js";
+
+export function buildActionSuccessPayload(input: {
+  actionId: string;
+  appliedMode: "semantic" | "physical";
+  verificationHint?: string;
+  targetSelectorKnown: boolean;
+}) {
+  return {
+    action_id: input.actionId,
+    applied_mode: input.appliedMode,
+    verification_hint: input.verificationHint,
+    follow_up_by_goal: buildFollowUpByGoal({
+      pageStateKnown: true,
+      targetSelectorKnown: input.targetSelectorKnown,
+      recentFailure: "none",
+    }),
+  };
+}
+
+export function buildActionFailurePayload(input: {
+  error: unknown;
+  actionId?: string;
+  appliedMode: "semantic" | "physical";
+  targetSelectorKnown: boolean;
+  sessionHealth?: {
+    consecutiveErrors: number;
+    maxConsecutiveErrors: number;
+    cooldownMs: number;
+    lastRestartAt?: string;
+    now: string;
+  };
+}) {
+  const mapped = asWebAgentError(input.error);
+  const recentFailure =
+    mapped.code === "STATE_ELEMENT_NOT_FOUND"
+      ? "semantic_not_found"
+      : mapped.code === "STATE_TARGET_NOT_INTERACTABLE"
+        ? "semantic_failed"
+        : mapped.type === "BROWSER"
+          ? "runtime_error"
+          : "layout_uncertain";
+
+  const fallback = toPolicyEnvelope(
+    recommendObservation({
+      goal: input.appliedMode === "physical" ? "visual_verify" : "interact",
+      page_state_known: true,
+      target_selector_known: input.targetSelectorKnown,
+      needs_precise_coordinates: input.appliedMode === "physical",
+      needs_full_page_context: false,
+      recent_failure: recentFailure,
+    }),
+  );
+  const retryPolicy = getRetryPolicy(mapped);
+  const sessionRestart = input.sessionHealth
+    ? shouldRecommendSessionRestart({
+        consecutiveErrors: input.sessionHealth.consecutiveErrors,
+        maxConsecutiveErrors: input.sessionHealth.maxConsecutiveErrors,
+        cooldownMs: input.sessionHealth.cooldownMs,
+        lastRestartAt: input.sessionHealth.lastRestartAt,
+        now: input.sessionHealth.now,
+        browserError: mapped.type === "BROWSER",
+      })
+    : { recommended: false as const };
+
+  return {
+    action_id: input.actionId,
+    applied_mode: input.appliedMode,
+    retry_hint: retryPolicy.retryHint,
+    fallback_observation: fallback,
+    follow_up_by_goal: buildFollowUpByGoal({
+      pageStateKnown: true,
+      targetSelectorKnown: input.targetSelectorKnown,
+      recentFailure,
+    }),
+    session_restart: sessionRestart,
+  };
+}

package/vendor/mcp/web-agent-mcp/src/core/artifact-store.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { WebAgentEnv } from "../config/env.js";
+import {
+  appendJsonLine,
+  ensureDir,
+  readJsonFile,
+  writeJsonFile,
+} from "../utils/fs.js";
+import { createId } from "../utils/ids.js";
+import { nowIso } from "../utils/time.js";
+
+export type ArtifactKind =
+  | "a11y"
+  | "dom"
+  | "text"
+  | "markdown"
+  | "boxes"
+  | "screenshot"
+  | "console"
+  | "network"
+  | "eval";
+
+export type ArtifactRecord = {
+  artifact_id: string;
+  session_id?: string;
+  page_id?: string;
+  task_id?: string;
+  action_id?: string;
+  kind: ArtifactKind;
+  created_at: string;
+  url?: string;
+  title?: string;
+  parent_artifact_id?: string;
+  storage_path?: string;
+  bytes?: number;
+  meta?: Record<string, unknown>;
+};
+
+export class ArtifactStore {
+  private readonly artifactPath: string;
+  private readonly indexPath: string;
+  private readonly rootDir: string;
+
+  constructor(env: WebAgentEnv) {
+    this.rootDir = env.artifactsDir;
+    this.artifactPath = path.join(env.historyDir, "artifacts.jsonl");
+    this.indexPath = path.join(env.artifactsDir, "index.json");
+  }
+
+  async writeText(
+    kind: ArtifactKind,
+    text: string,
+    refs: Omit<
+      ArtifactRecord,
+      "artifact_id" | "created_at" | "kind" | "storage_path" | "bytes"
+    > = {},
+  ) {
+    const artifactId = createId("artifact");
+    const filePath = path.join(this.rootDir, `${artifactId}.txt`);
+    await ensureDir(this.rootDir);
+    await fs.writeFile(filePath, text, "utf8");
+    const bytes = Buffer.byteLength(text, "utf8");
+    const record = await this.saveMetadata({
+      artifact_id: artifactId,
+      kind,
+      created_at: nowIso(),
+      storage_path: filePath,
+      bytes,
+      ...refs,
+    });
+    return record;
+  }
+
+  async writeBinary(
+    kind: ArtifactKind,
+    buffer: Buffer,
+    extension: string,
+    refs: Omit<
+      ArtifactRecord,
+      "artifact_id" | "created_at" | "kind" | "storage_path" | "bytes"
+    > = {},
+  ) {
+    const artifactId = createId("artifact");
+    const filePath = path.join(this.rootDir, `${artifactId}.${extension}`);
+    await ensureDir(this.rootDir);
+    await fs.writeFile(filePath, buffer);
+    const record = await this.saveMetadata({
+      artifact_id: artifactId,
+      kind,
+      created_at: nowIso(),
+      storage_path: filePath,
+      bytes: buffer.byteLength,
+      ...refs,
+    });
+    return record;
+  }
+
+  private async saveMetadata(record: ArtifactRecord) {
+    await appendJsonLine(this.artifactPath, record);
+    const index = await readJsonFile<Record<string, ArtifactRecord>>(
+      this.indexPath,
+      {},
+    );
+    index[record.artifact_id] = record;
+    await writeJsonFile(this.indexPath, index);
+    return record;
+  }
+}

package/vendor/mcp/web-agent-mcp/src/core/errors.ts

@@ -0,0 +1,108 @@
+import type { ErrorType, ToolEnvelope } from "../schemas/common.js";
+import { createToolFailure } from "../schemas/common.js";
+
+export type WebAgentErrorCode =
+  | "INPUT_INVALID_URL"
+  | "INPUT_MISSING_SESSION"
+  | "STATE_PAGE_NOT_FOUND"
+  | "STATE_NAVIGATION_NOT_OBSERVED"
+  | "STATE_ELEMENT_NOT_FOUND"
+  | "STATE_TARGET_NOT_INTERACTABLE"
+  | "BROWSER_LAUNCH_FAILED"
+  | "BROWSER_DISCONNECTED"
+  | "NETWORK_TIMEOUT"
+  | "STORAGE_WRITE_FAILED"
+  | "INTERNAL_NOT_IMPLEMENTED"
+  | "INTERNAL_UNREACHABLE";
+
+const errorTypeByCode: Record<WebAgentErrorCode, ErrorType> = {
+  INPUT_INVALID_URL: "INPUT",
+  INPUT_MISSING_SESSION: "INPUT",
+  STATE_PAGE_NOT_FOUND: "STATE",
+  STATE_NAVIGATION_NOT_OBSERVED: "STATE",
+  STATE_ELEMENT_NOT_FOUND: "STATE",
+  STATE_TARGET_NOT_INTERACTABLE: "STATE",
+  BROWSER_LAUNCH_FAILED: "BROWSER",
+  BROWSER_DISCONNECTED: "BROWSER",
+  NETWORK_TIMEOUT: "NETWORK",
+  STORAGE_WRITE_FAILED: "STORAGE",
+  INTERNAL_NOT_IMPLEMENTED: "INTERNAL",
+  INTERNAL_UNREACHABLE: "INTERNAL",
+};
+
+export class WebAgentError extends Error {
+  readonly code: WebAgentErrorCode;
+  readonly type: ErrorType;
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    code: WebAgentErrorCode,
+    message: string,
+    details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "WebAgentError";
+    this.code = code;
+    this.type = errorTypeByCode[code];
+    this.details = details;
+  }
+}
+
+export function asWebAgentError(error: unknown) {
+  if (error instanceof WebAgentError) {
+    return error;
+  }
+
+  const message =
+    error instanceof Error ? error.message : "Unexpected internal error.";
+
+  if (
+    message.includes("locator(") ||
+    message.includes("waitForSelector") ||
+    message.includes("bounding box")
+  ) {
+    if (message.toLowerCase().includes("timeout")) {
+      return new WebAgentError("STATE_ELEMENT_NOT_FOUND", message);
+    }
+
+    if (
+      message.toLowerCase().includes("not visible") ||
+      message.toLowerCase().includes("not enabled")
+    ) {
+      return new WebAgentError("STATE_TARGET_NOT_INTERACTABLE", message);
+    }
+
+    return new WebAgentError("STATE_ELEMENT_NOT_FOUND", message);
+  }
+
+  if (
+    message
+      .toLowerCase()
+      .includes("target page, context or browser has been closed")
+  ) {
+    return new WebAgentError("BROWSER_DISCONNECTED", message);
+  }
+
+  if (message.toLowerCase().includes("timeout")) {
+    return new WebAgentError("NETWORK_TIMEOUT", message);
+  }
+
+  return new WebAgentError("INTERNAL_UNREACHABLE", message);
+}
+
+export function createFailureResult(
+  error: unknown,
+  envelope: Partial<ToolEnvelope> = {},
+) {
+  const mapped = asWebAgentError(error);
+  return createToolFailure({
+    ok: false,
+    code: mapped.code,
+    message: mapped.message,
+    ...envelope,
+    error: {
+      type: mapped.type,
+      details: mapped.details,
+    },
+  });
+}

package/vendor/mcp/web-agent-mcp/src/core/observation-flow.ts

@@ -0,0 +1,38 @@
+import { recommendObservation } from "./policy-engine.js";
+
+type Goal = "interact" | "read" | "visual_verify" | "debug" | "gesture";
+
+export function buildFollowUpByGoal(input: {
+  pageStateKnown: boolean;
+  targetSelectorKnown: boolean;
+  needsPreciseCoordinates?: boolean;
+  needsFullPageContext?: boolean;
+  recentFailure?: "none" | "semantic_not_found" | "semantic_failed" | "layout_uncertain" | "runtime_error";
+}) {
+  const goals: Goal[] = ["interact", "read", "visual_verify", "debug", "gesture"];
+
+  return Object.fromEntries(
+    goals.map((goal) => [
+      goal,
+      toPolicyEnvelope(
+        recommendObservation({
+          goal,
+          page_state_known: input.pageStateKnown,
+          target_selector_known: input.targetSelectorKnown,
+          needs_precise_coordinates: goal === "gesture" ? true : Boolean(input.needsPreciseCoordinates),
+          needs_full_page_context: goal === "visual_verify" ? Boolean(input.needsFullPageContext) : false,
+          recent_failure: input.recentFailure ?? "none"
+        })
+      )
+    ])
+  ) as Record<Goal, ReturnType<typeof toPolicyEnvelope>>;
+}
+
+export function toPolicyEnvelope(result: ReturnType<typeof recommendObservation>) {
+  return {
+    recommended_tool: result.recommendedTool,
+    screenshot_mode: result.screenshotMode,
+    rationale: result.rationale,
+    escalation_order: result.escalationOrder
+  };
+}

package/vendor/mcp/web-agent-mcp/src/core/policy-engine.ts

@@ -0,0 +1,113 @@
+import type { RecommendObservationInput } from "../schemas/policy.js";
+
+export type ObservationRecommendation = {
+  recommendedTool: "observe.a11y" | "observe.dom" | "observe.text" | "observe.boxes" | "observe.screenshot";
+  screenshotMode: "none" | "element" | "viewport" | "full";
+  rationale: string[];
+  escalationOrder: string[];
+};
+
+export function recommendObservation(input: RecommendObservationInput): ObservationRecommendation {
+  const rationale: string[] = [];
+  const escalationOrder = [
+    "observe.a11y",
+    "observe.dom",
+    "observe.text",
+    "observe.boxes",
+    "observe.screenshot"
+  ];
+
+  if (input.goal === "read") {
+    rationale.push("Reading tasks should prefer cheap textual context before any visual artifact.");
+    return {
+      recommendedTool: "observe.text",
+      screenshotMode: "none",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  if (input.goal === "debug") {
+    rationale.push("Debug flows usually need structural context before expensive screenshots.");
+    rationale.push(
+      input.recent_failure === "runtime_error"
+        ? "Runtime errors often benefit from DOM plus later console/network review."
+        : "A screenshot is useful only after structural context is insufficient."
+    );
+    return {
+      recommendedTool: input.page_state_known ? "observe.dom" : "observe.a11y",
+      screenshotMode: "none",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  if (input.goal === "visual_verify") {
+    rationale.push("Visual verification explicitly needs pixels, so screenshot escalation is justified.");
+    if (input.needs_full_page_context) {
+      rationale.push("Full-page context was requested, so prefer a full-page screenshot.");
+      return {
+        recommendedTool: "observe.screenshot",
+        screenshotMode: "full",
+        rationale,
+        escalationOrder
+      };
+    }
+
+    return {
+      recommendedTool: "observe.screenshot",
+      screenshotMode: input.target_selector_known ? "element" : "viewport",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  if (input.goal === "gesture" || input.needs_precise_coordinates) {
+    rationale.push("Gesture execution needs precise spatial data before acting.");
+    rationale.push("Bounding boxes are cheaper than screenshots and usually sufficient for coordinates.");
+    return {
+      recommendedTool: "observe.boxes",
+      screenshotMode: "none",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  if (input.recent_failure === "semantic_not_found" || input.recent_failure === "semantic_failed") {
+    rationale.push("A semantic failure suggests spatial fallback is needed.");
+    return {
+      recommendedTool: "observe.boxes",
+      screenshotMode: "none",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  if (input.goal === "interact") {
+    rationale.push("Interaction tasks should start with structured page state, not screenshots.");
+    if (input.page_state_known && input.target_selector_known) {
+      rationale.push("Known page state plus known target favors a lightweight DOM check.");
+      return {
+        recommendedTool: "observe.dom",
+        screenshotMode: "none",
+        rationale,
+        escalationOrder
+      };
+    }
+
+    return {
+      recommendedTool: "observe.a11y",
+      screenshotMode: "none",
+      rationale,
+      escalationOrder
+    };
+  }
+
+  rationale.push("Default to structured accessibility context as the cheapest general-purpose observation.");
+  return {
+    recommendedTool: "observe.a11y",
+    screenshotMode: "none",
+    rationale,
+    escalationOrder
+  };
+}

package/vendor/mcp/web-agent-mcp/src/core/retry-policy.ts

@@ -0,0 +1,42 @@
+import type { WebAgentError } from "./errors.js";
+
+export type RetryPolicyDecision = {
+  retryable: boolean;
+  maxAttempts: number;
+  retryHint?: string;
+};
+
+export function getRetryPolicy(error: WebAgentError): RetryPolicyDecision {
+  switch (error.code) {
+    case "STATE_ELEMENT_NOT_FOUND":
+      return {
+        retryable: true,
+        maxAttempts: 2,
+        retryHint:
+          "Refresh observation first, then retry with observe.boxes or an element screenshot.",
+      };
+    case "STATE_TARGET_NOT_INTERACTABLE":
+      return {
+        retryable: true,
+        maxAttempts: 2,
+        retryHint: "Re-check layout and visibility before retrying the action.",
+      };
+    case "NETWORK_TIMEOUT":
+      return {
+        retryable: true,
+        maxAttempts: 2,
+        retryHint: "Retry once if the page is still loading or unstable.",
+      };
+    case "BROWSER_DISCONNECTED":
+      return {
+        retryable: true,
+        maxAttempts: 1,
+        retryHint: "Restart the session before retrying.",
+      };
+    default:
+      return {
+        retryable: false,
+        maxAttempts: 0,
+      };
+  }
+}