@github/copilot-language-server 1.562.0 → 1.564.0

package/dist/assets/cls-builtin-plugins/plugins/browser-use/skills/activate/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: activate
+description: Activate Copilot Browser in the current session, upgrade its registration, or repair incomplete setup.
+---
+
+Perform a controlled activation of this Browser Use plugin installation.
+
+Session start normally performs this activation automatically. Use this skill to enable Browser
+immediately in the current session, upgrade the active registration, repair incomplete or
+mismatched setup, or when the user explicitly requests activation.
+
+Resolve `../../scripts/activate.mjs` relative to this skill's directory and run exactly:
+
+```text
+node <absolute-path-to-activate.mjs>
+```
+
+Wait for the activation process to finish before using Browser tools.
+
+The script checks connectivity itself for up to 15 seconds and returns early when a browser
+connects. Report the activation result without adding your own sleep or connectivity polling.
+Use `/browser-use:doctor` if Browser has connection problems.
+
+If activation fails, report the failure without retrying with modified arguments.

package/dist/assets/cls-builtin-plugins/plugins/browser-use/skills/browser-use/BROWSER-RUN.md

@@ -0,0 +1,382 @@
+# Browser Code Mode
+
+Read this reference completely before the first `run_javascript` call in a task. `run_javascript` executes
+one disposable Guest Program against one existing Browser Connection. Use it for repetitive or
+conditional work, or to batch known actions and their result checks. Direct tools remain suitable
+for short, non-repetitive steps. A run is sequential, not an atomic transaction; committed input is
+not rolled back if a later step fails.
+
+## Call shape
+
+```json
+{
+  "connectionId": "opaque ID from connection_request",
+  "summary": "Short description shown in the browser approval UI",
+  "code": "const title = await tab.locator('h1').innerText(); return { title };",
+  "timeoutMs": 15000
+}
+```
+
+`summary` is required and limited to 160 characters. It describes the intended run but is not an
+authorization or a verified execution plan. `code` is an async-function body, not JSON, a quoted
+string, or a Markdown fence. `timeoutMs` is optional, accepts integers from 1000 through 30000,
+and can only lower the 30-second active JavaScript budget. Browser operation waits do not consume
+that budget; Guest callbacks and resumptions do. Per-operation timeouts are separate.
+
+The browser issues a Run Grant before the Guest Program starts, requesting approval unless
+persistent policy or an applicable origin grant allows it. Nested operations do not prompt separately.
+Same-origin navigation remains in that Run Grant. `tab.goto()` checks approval before targeting a
+different scheme, hostname, or non-default port. Hostname aliases such as `localhost` and
+`127.0.0.1` remain distinct even on the same port. The popup says **Run on** when starting the Run
+Grant and **Extend run to** when adding an origin. A cross-origin redirect or later operation
+pauses for any required approval before page data is returned. A retained all-operations origin
+approval may authorize later runs on that origin. A current policy block defeats older grants.
+
+## Globals
+
+- `tab`: the Browser Connection's single managed tab.
+- `checkpoint(name, value)`: retain one named JSON-serializable stage result, including when a later
+  operation fails. Names contain 1 to 64 characters; at most 64 checkpoints share the output
+  budget.
+- `text(value)`: append one bounded text item.
+- `image(handle)`: append an `ImageHandle` returned by `tab.screenshot()`.
+- `console.log/info/warn/error(...values)`: append bounded diagnostic logs.
+- `sleep(milliseconds)`: await a delay capped at 10 seconds.
+- `setTimeout(callback, milliseconds)` and `clearTimeout(id)`: timers capped at 10 seconds. Pending
+  timers do not keep the Guest Program alive.
+- `exit()`: finish successfully with a `null` return value.
+
+Node.js, `process`, `require`, files, environment variables, `fetch`, network sockets, imports,
+page evaluation, raw CDP, and private Browser capabilities are unavailable.
+
+## `tab` interface
+
+```ts
+type WaitState = "attached" | "detached" | "visible" | "hidden";
+type LocatorText = string | RegExp;
+type FrameSnapshot = {
+  frameRef: string; // diagnostics and tree relationships only; not a routing argument
+  owner?: { id?: string; name?: string };
+  title: string;
+  url: string;
+  content: string;
+  omissions: string[];
+  frames: FrameSnapshot[];
+};
+
+type Snapshot = {
+  title: string;
+  url: string;
+  content: string;
+  omissions: string[];
+  focus?: { ref: string };
+  selection?: { ref: string; kind: string; start: number; end: number; collapsed: boolean };
+  frames?: FrameSnapshot[];
+};
+
+type ImageHandle = Readonly<{
+  width: number;
+  height: number;
+  mimeType: "image/jpeg";
+  sizeBytes: number;
+}>;
+
+type LocatorFilter = {
+  hasText?: LocatorText;
+  hasNotText?: LocatorText;
+  has?: Locator;
+  hasNot?: Locator;
+  visible?: boolean;
+};
+
+type ClickOptions = {
+  button?: "left" | "right" | "middle";
+  modifiers?: Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift">;
+  force?: boolean;
+  timeoutMs?: number;
+};
+
+type KeyboardInput = string | { key: string; text?: never } | { text: string; key?: never };
+
+type Locator = {
+  locator(selector: string, filter?: LocatorFilter): Locator;
+  getByRole(role: string, options?: { name?: LocatorText; exact?: boolean }): Locator;
+  getByText(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByLabel(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByPlaceholder(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByTestId(testId: string): Locator;
+  filter(options?: LocatorFilter): Locator;
+  first(): Locator;
+  last(): Locator;
+  nth(index: number): Locator;
+  and(other: Locator): Locator;
+  or(other: Locator): Locator;
+  contentFrame(): FrameLocator;
+  closedShadow(): Locator;
+  all(): Promise<Locator[]>;
+
+  click(options?: ClickOptions): Promise<null>;
+  dblclick(options?: ClickOptions): Promise<null>;
+  fill(value: string, options?: { timeoutMs?: number }): Promise<null>;
+  type(value: string, options?: { timeoutMs?: number }): Promise<null>;
+  press(input: KeyboardInput, options?: { timeoutMs?: number }): Promise<null>;
+  waitFor(options: { state: WaitState; timeoutMs?: number }): Promise<null>;
+  scrollIntoViewIfNeeded(options?: { timeoutMs?: number }): Promise<null>;
+  count(): Promise<number>;
+  isVisible(): Promise<boolean>;
+  isEnabled(): Promise<boolean>;
+  allTextContents(options?: { timeoutMs?: number }): Promise<string[]>;
+  textContent(options?: { timeoutMs?: number }): Promise<string | null>;
+  innerText(options?: { timeoutMs?: number }): Promise<string>;
+  getAttribute(name: string, options?: { timeoutMs?: number }): Promise<string | null>;
+};
+
+type FrameLocator = {
+  locator(selector: string, filter?: LocatorFilter): Locator;
+  getByRole(role: string, options?: { name?: LocatorText; exact?: boolean }): Locator;
+  getByText(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByLabel(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByPlaceholder(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByTestId(testId: string): Locator;
+  frameLocator(selector: string): FrameLocator;
+};
+
+type Tab = {
+  frameLocator(selector: string): FrameLocator;
+  locator(selector: string, filter?: LocatorFilter): Locator;
+  getByRole(role: string, options?: { name?: LocatorText; exact?: boolean }): Locator;
+  getByText(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByLabel(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByPlaceholder(text: LocatorText, options?: { exact?: boolean }): Locator;
+  getByTestId(testId: string): Locator;
+
+  url(): Promise<string>;
+  goto(url: string, options?: { timeoutMs?: number }): Promise<string>;
+  reload(options?: { timeoutMs?: number }): Promise<string>;
+  goBack(options?: { timeoutMs?: number }): Promise<string>;
+  goForward(options?: { timeoutMs?: number }): Promise<string>;
+  waitForURL(pattern: string, options?: { timeoutMs?: number }): Promise<string>;
+  snapshot(): Promise<Snapshot>;
+  screenshot(options?: { fullPage?: boolean; clip?: { x: number; y: number; width: number; height: number }; timeoutMs?: number }): Promise<ImageHandle>;
+  click(ref: string, options?: ClickOptions & { doubleClick?: boolean }): Promise<{ outcome: string }>;
+  hover(ref: string): Promise<{ outcome: string }>;
+  keyboard(input: KeyboardInput, options?: { ref?: string; timeoutMs?: number }): Promise<{ outcome: string }>;
+  type(text: string, options?: { ref?: string; submitKey?: string }): Promise<{ outcome: string }>;
+  fill(text: string, options: { ref: string }): Promise<{ outcome: string }>;
+};
+```
+
+`waitForURL()` string patterns match the complete normalized URL: `*` matches within one path
+segment and `**` crosses `/` separators. Navigation methods return the final normalized URL.
+Reload, back, and forward wait for a loading/URL transition or tab replacement after the action
+starts; they do not accept a stale pre-navigation `complete` tab.
+Navigation and URL waits default to 30 seconds; their per-operation `timeoutMs` accepts 1–120000
+milliseconds. `goto`, reload, back, and forward still wait for load completion. This budget is
+separate from the top-level active-JavaScript budget. If navigation times out, inspect the current
+URL and page before deciding the next action: the page may still be loading after dispatch.
+
+Locators support Playwright CSS, XPath, role, text, label, placeholder, test-id, and internal
+selector syntax in the main document and open Shadow DOM. In supported dev/production builds,
+when the default-Off **Advanced page surfaces · Experimental** setting was enabled before this
+Browser Connection was opened, use `frameLocator()`, nested `FrameLocator.frameLocator()`, `contentFrame()`, and
+`closedShadow()` to cross each frame or page-author Closed Shadow Root explicitly. Ordinary
+Locators never cross these boundaries. Frames use their actual non-opaque origins for browser-owned
+policy and may trigger one origin/count subset approval; the setting and approval choices are never inferred
+by the agent. Single-target methods reject ambiguity. For `click()` and `dblclick()`, exactly one
+visible match among multiple matches is selected; otherwise narrow the Locator explicitly.
+Ref and Locator clicks scroll to center/nearest, briefly sample the bounding rectangle, and dispatch at
+its center. `force: true` skips visible/enabled checks, not scrolling or rectangle sampling.
+Both wait for visible/enabled state unless forced. Refs remain bound to the snapshot element;
+Locators may resolve again before input. Neither entry guarantees the intended element receives input:
+an ordinary overlay may receive it instead. Read back the application result before continuing.
+Both retain authorization, document/ref identity, protected-target, new-window and ancestor
+frame-boundary checks, including with force. `ControlOrMeta` selects Control on Windows/Linux
+and Meta on macOS. Other actions do not accept force.
+`scrollIntoViewIfNeeded()` asks Chromium to perform the minimum `nearest` scroll
+through the viewport and every clipping/scrollable ancestor for one already-loaded strict target.
+It does this even when the target's rectangle is inside the viewport, because an overflow ancestor
+may still clip it. It cannot locate a virtual-list item that is not yet in the DOM. Offscreen
+scrolling across multiple frame boundaries is not supported; work from an exposed boundary or hand
+that scroll to the user rather than repeatedly retrying a clipped frame chain. Actions that open a
+new tab or window are rejected.
+
+Every terminal Locator action re-resolves and freezes its exact Element before input.
+A successful mutating call confirms that input was dispatched; it does not prove
+that application code accepted the input or changed its data model. Read back the smallest relevant
+state and assert the expected postcondition instead of treating dispatch as application success.
+Password, authentication-code, payment, and file controls cannot be read,
+operated, or observed through Locator wait states. An existing Protected Control is rejected before `attached`,
+`detached`, `visible`, or `hidden` is evaluated. Collection
+text preserves positions with `[PROTECTED CONTROL]`; high-confidence tokens are masked. Result
+omissions report when sensitive content was withheld.
+
+## Input semantics
+
+| API | Behavior |
+| --- | --- |
+| `Locator.click()` / `Locator.dblclick()` | Dispatch a single or double pointer click on the target. |
+| `Locator.fill(text)` | Replace the contents of a native input, textarea or contenteditable target. |
+| `Locator.type(text)` | Insert text at the target's selection without automatically clearing its contents. |
+| `Locator.press(key)` / `Locator.press({ key })` | Focus the target as needed, then dispatch a key or chord. |
+| `tab.type(text)` | Insert at the current focused editor's selection; selected text is replaced, otherwise text is inserted at the caret. |
+| `tab.type(text, { ref })` | Focus the editable target as needed, then insert at its selection, just like Locator.type. |
+| `tab.fill(text, { ref })` | Replace the complete editable target content, just like Locator.fill; empty text clears it. |
+| `tab.keyboard(key, { ref? })` / `tab.keyboard({ key }, { ref? })` | Dispatch a key or chord; without a ref preserve current focus, otherwise focus the target as needed. |
+| `tab.keyboard({ text }, { ref? })` / `Locator.press({ text })` | Insert characters individually, preserving content outside the selection; an explicit target is focused as needed. |
+
+The standalone `keyboard` tool requires exactly one of `key` or `text`; a string passed to a
+code-mode keyboard method always means a key, not literal text. Ref-based and Locator input use
+the same target-input implementation. Without a target, input preserves current focus and selection;
+it does not search for or focus another editor. A ref chooses the target, never the replacement mode.
+The standalone `type` tool inserts with or without a ref; `fill` requires a ref and replaces the target.
+
+Ordinary `type` uses plain-text virtual paste; Markdown remains literal text. `fill` first asks
+the injected engine to replace supported native values or select the target content. Only when
+text input is still needed does it paste; empty fill deletes the selection. `type` preserves content
+outside the selection. The synthetic paste
+event allows an editor to handle the insertion; it is not a sequence of trusted character keys.
+Use `keyboard({ text })` or `Locator.press({ text })` when an editor needs
+character key events: printable ASCII and line endings use keydown/keyup, other Unicode and tab
+use single-code-point text insertion. This is not OS keyboard or IME emulation.
+
+The standalone `keyboard` and `screenshot` tools, their tab methods, and Locator operation
+options accept `timeoutMs` from 1 to 120000. This is an operation execution budget, not the
+top-level `run_javascript.timeoutMs` active-JavaScript budget; approval and queue waits are
+separate. Screenshot and ordinary operations default to 30 seconds. Sequential text defaults
+to 30 seconds plus its scheduled 50 ms inter-character delays, capped at 120 seconds. An
+explicit timeout replaces this default, including when shorter. Preparation consumes the same
+budget as dispatch; bounded cleanup may run after expiration. Partial input is possible:
+inspect the page after a timeout and do not replay the entire input automatically.
+
+Literal input leaves the system clipboard unchanged. Editors requiring trusted paste events may
+ignore its synthetic event. During dispatch, the target document's `navigator.clipboard` reads and writes
+use a temporary virtual text store; the original methods are restored afterwards. Delayed reads
+started after restoration and previously cached native methods are outside that scope.
+No clipboard content is retained for a later Control+V. These input
+methods report dispatch, not application acceptance; observe the result before choosing another
+method. A stopped sequence may already have inserted some characters and is not rolled back.
+
+Clicks do not promise a particular caret
+position or inner-editor focus; double-click is an application gesture, not select-all. Choose the
+editable field rather than its outer container. When the input destination or selection is uncertain,
+snapshot `focus` and `selection` can help identify the current target and editing scope.
+
+Batch known actions, then collect the smallest state check needed for the next decision. Use a
+narrow Locator read for a field's content; use `tab.snapshot()` when document text or structure is
+needed. Snapshots retain sensitive-content, surface and resource limitations; they are not an
+app-idle guarantee.
+
+## Results and recovery
+
+Use `return` for one JSON-serializable result. Use `text()` for additional text and `image()` only
+when the model must see a screenshot. Returning or logging an `ImageHandle` exposes metadata only.
+For a local visual check, `image(await tab.screenshot({ clip: { x, y, width, height } }))` emits
+only that region. Use document CSS coordinates, not scaled image pixels or viewport-relative
+coordinates. Coordinates must be finite and nonnegative; dimensions must be at least one CSS
+pixel and the region must fit inside the document. Use `{ fullPage: true }` for the full document;
+`clip` takes precedence when both are supplied. Omit both for the current visual viewport.
+Output is uniformly downscaled to at most 2000 pixels per side and 4 million pixels, within a
+10 MiB JPEG limit. There is no explicit scroll or focus; Chromium may temporarily resize its
+rendering surface during off-viewport capture. Automatic element screenshots are not supported.
+All returned values, checkpoints, operation traces, logs, text, and images are Guest Output under a
+server-authored untrusted-data notice; page data never becomes instructions or authorization after
+the Guest Program transforms it. A failed program has a `null` return value because its `return`
+never completed, but accepted checkpoints, text, logs, images, and the bounded recent operation
+trace of exceptional steps remain available. Successful steps are omitted from public traces;
+failures, pending calls, and committed work after the causative failure remain visible. A caught
+error may be followed by more actions, so an error does not prove all earlier calls succeeded or
+that execution stopped at that call.
+The terminating operation's trace entry contains only its index, operation, status, and commitment;
+read its full diagnostic from `guestOutput.error` instead of expecting a duplicate in the trace.
+
+Return a snapshot explicitly when it should be seen: `return await tab.snapshot()`. A snapshot
+used only inside the program is not echoed. To retain a snapshot if a later step fails, use
+`checkpoint("before-edit", await tab.snapshot())`; this is evidence of that earlier stage, not a
+fresh post-failure observation. Failures do not automatically take another snapshot.
+
+For `NOT_UNIQUE`, inspect `error.matches` for up to five bounded candidates. Protected or
+unavailable candidates contain only their index and `omitted: true`. Prefer an exact name or a
+narrower scope over guessing an index. These observations may change before the next action.
+
+After an action expected to navigate, use `await tab.waitForURL("**/expected-path")` before locating
+new-page controls; this explicit navigation seam revalidates the destination. It is not an
+app-idle or data-persistence check. On an unexpected `PAGE_CHANGED`, observe the current page in a
+new run rather than replaying the preceding click. `CONNECTION_NOT_FOUND` does not identify why a
+connection disappeared: establish an approved connection again and inspect state before deciding
+what remains to be done. The tool cannot silently rebind an expired connection to a tab.
+
+Await every `tab` and Locator operation. Finishing with pending browser calls fails with
+`UNAWAITED_OPERATIONS` and cancels calls that have not committed. Browser actions that already
+committed are never rolled back.
+
+Nested failures reject a catchable `BrowserError` with `code`, `message`, `operationIndex`,
+`operation`, `source`, `pageUrl`, `committed`, an optional `locator`, and sometimes `retryHint` or
+`reason`.
+The final `guestOutput.error` repeats the diagnostic when the error is not caught. Browser-originated
+errors carry an operation identity in a closure-private WeakMap keyed by the exact Error object, not
+a Guest-visible property. Wrapping a caught browser message or copying its properties into a new
+script error does not misattribute the terminating code or source. `pageUrl` is the
+postflight URL only when its origin is already authorized by the current Run Grant; it is omitted
+rather than disclosing or misreporting an unapproved destination. When navigation has already been
+dispatched but destination approval is denied, the error keeps `APPROVAL_DENIED` and reports
+`committed: "unknown"` without revealing the destination URL. The last 32 operation summaries
+remain in `guestOutput.operations`; source locations are one-based positions in the submitted
+`code`. Use codes such as `PAGE_CHANGED`, `STALE_ELEMENT_REFERENCE`,
+`ELEMENT_NOT_ACTIONABLE`, and `ACTION_OUTCOME_UNKNOWN` instead of parsing messages. Advanced
+boundaries additionally use `ADVANCED_SURFACES_DISABLED`, `DOMAIN_BLOCKED`,
+`UNSUPPORTED_FRAME_ORIGIN`, `APPROVAL_DENIED`, and `RESOURCE_LIMIT_EXCEEDED`. A broad snapshot
+reports only `child-frames`, `closed-shadow-roots`, or `advanced-surface-limit`; do not infer a
+private policy decision or the capability setting from an omission. `ADVANCED_SURFACES_DISABLED`
+can mean an unavailable build or a disabled captured setting: use a supported build, enable the
+Experimental setting when present, and open a new connection. Unconfigured/store builds have no such
+setting to enable. Never immediately replay an action when `committed` is `true` or `"unknown"`;
+inspect current state first. This includes a keyboard continuation that fails after earlier text
+input or part of a chord was already dispatched.
+
+An authorized strict-boundary failure may refine `ELEMENT_NOT_ACTIONABLE` with one of these closed
+`reason` values, also retained for an uncaught browser error and its operation trace:
+
+| Reason | Next observation |
+| --- | --- |
+| `BOUNDARY_NOT_FOUND` | Check whether the chosen owner selector matches the current DOM. |
+| `BOUNDARY_NOT_UNIQUE` | Narrow the owner Locator deliberately. |
+| `NOT_ATTACHED_FRAME_OWNER` | Check that the chosen element owns an attached frame and observe loading state. |
+| `NO_PAGE_AUTHOR_CLOSED_ROOT` | Check the host choice; ordinary Locators already traverse open Shadow DOM. |
+
+An absent reason remains an ordinary actionability failure. These reasons do not expose raw CDP
+identity or replace authorization, Protected Control, or commit-state checks.
+
+Hard limits include 64 KiB source, 64 MiB Guest heap, 1 MiB Guest stack, 30 seconds active
+JavaScript, 10 minutes total wall time, 256 browser operations, 8 pending operations, 64 Advanced
+Surfaces per operation and per Run (distinct frame epochs and Closed Shadow Root identities), 4 MiB
+per nested result, 5000 Locator collection entries, 256 KiB result/text/checkpoints, 64 KiB logs, the
+last 32 operation summaries, at most 1024 text items, at most 1024 log items, an 8 KiB final script
+error message, and at most two images totaling 20 MiB. Text and log budgets charge their JSON UTF-8
+serialized size, including escaping and separators. The first operation-admission limit violation
+latches the Run failure even if Guest code catches it; later requests are rejected without growing
+the parent trace or reaching the browser. `OUTPUT_TOO_LARGE` retains previously accepted small
+output and asks for a narrower retry.
+
+Run Grant close is attempted once. If revocation cannot be confirmed, an existing execution failure
+remains primary with its partial Guest Output, cleanup is reported separately, and the MCP retains
+exclusive run ownership instead of forwarding direct tools. Explicitly finalize the Browser
+Connection once to revoke the whole connection. If a canceled Run open cannot confirm its
+compensating close, the Native Host also retains a fail-closed peer state and rejects direct tools
+with `RUN_IN_PROGRESS` until that finalization. Authorization remains fail-closed even if closing the
+managed tab fails; tab closure may be retried by normal connection maintenance.
+
+## Example
+
+```js
+const rows = await tab.getByRole("row").all();
+checkpoint("rows-loaded", { count: rows.length, url: await tab.url() });
+const approved = [];
+for (const row of rows) {
+  if ((await row.innerText()).includes("Pending")) {
+    await row.scrollIntoViewIfNeeded();
+    await row.getByRole("button", { name: "Approve" }).click();
+    approved.push(await row.getAttribute("data-id"));
+  }
+}
+return { approved };
+```