@maxiaochao/pi-toolkit 0.1.9 → 0.2.1

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2026-09-02 - v0.2.1
+
+- update global agent instructions for harness-native file editing
+- remove the HTML artifact output preference from the global instructions
+
+## 2026-09-02 - v0.2.0
+
+- bundle the Apache-2.0 `web-browser` skill for Chrome/Chromium CDP automation
+- auto-detect Linux/macOS browsers and Windows Chrome when running under WSL
+- include the skill's `ws` runtime dependency and document its release checks
+
 ## 2026-09-02 - v0.1.9
 
 - add the `/btw` side-chat extension

package/README.md

@@ -1,6 +1,6 @@
 # pi-toolkit
 
-Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions plus the bundled Night Owl theme.
+Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, and the Night Owl theme.
 
 ## Install
 
@@ -10,7 +10,7 @@ Install the root package to enable the toolkit extensions globally:
 pi install npm:@maxiaochao/pi-toolkit
 ```
 
-The package also provides the `/btw` side-chat extension and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
+The package also provides the `/btw` side-chat extension, the `web-browser` skill for Chrome/Chromium CDP automation, and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
 
 The package postinstall hook synchronizes the bundled global instructions to:
 
@@ -42,6 +42,15 @@ The `/btw` side chat is a separate agent session. It can inspect the main conver
 
 The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
 
+The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
+
+The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:
+
+```bash
+node skills/web-browser/scripts/start.js --headless
+node skills/web-browser/scripts/nav.js https://example.com
+```
+
 ## Tiny Subagent
 
 The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:

package/global/AGENTS.md

@@ -100,11 +100,10 @@ After each significant step:
 2. Does the standard library cover it? Use it.
 3. Only then: write the minimum code that works.
 
----
+## 9. Use Available Editing Tools
 
+**Follow the current harness's tool surface; do not assume a shell patch helper exists.**
 
-## Output Format Preference
-
-For complex explanations, prefer a runnable HTML artifact over a long Markdown-only response when the content benefits from visual structure or interaction. This includes workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Keep ordinary prose, short answers, diffs, and focused code reviews in Markdown.
-
-When using HTML, create a self-contained, responsive artifact in the project's established output location, or `.cache/html/<descriptive-name>.html` when no convention exists. Use semantic HTML, accessible controls, escaped code blocks, and small useful interactions. Return a concise Markdown summary with a clickable local file path; if a preview/server tool is available, start it and return the preview URL only after verifying the page is not blank and its assets load.
+- Use the native file-editing tools exposed by the current environment. In pi, use `edit` for precise replacements and `write` for new files or complete rewrites.
+- Do not run `apply_patch` as a shell command unless `command -v apply_patch` confirms that executable is available.
+- If the harness exposes `apply_patch` as a dedicated tool rather than a command, invoke it only through that tool interface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.1.9",
-  "description": "Personal pi coding agent toolkit: /todos extension + /cache_export interactive cache dashboard.",
+  "version": "0.2.1",
+  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -39,6 +39,9 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
   "scripts": {
     "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs",
     "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts",

package/skills/web-browser/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/skills/web-browser/NOTICE

@@ -0,0 +1,15 @@
+Web Browser Skill
+
+This directory is derived from the web-browser skill in:
+https://github.com/mitsuhiko/agent-stuff
+
+The upstream repository is licensed under Apache License 2.0. A copy of that
+license is included in LICENSE.
+
+Changes in pi-toolkit include configurable CDP host/port support, device
+emulation, screenshot improvements, and Chrome launch support for Linux and
+Windows Chrome under WSL.
+
+The upstream skill credits Mario Zechner for the original browser automation
+approach:
+https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/

package/skills/web-browser/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: web-browser
+description: "Automate and interact with web pages through Chrome or Chromium using the Chrome DevTools Protocol (CDP): navigate, click, fill forms, inspect content, take screenshots, and debug console or network activity. Use when an agent needs a real browser. Supports common macOS/Linux installs and Windows Chrome from WSL. Prefer headless Chrome unless visible browser interaction is required."
+license: Apache-2.0; see LICENSE
+---
+
+# Web Browser Skill
+
+Minimal CDP tools for collaborative site exploration.
+
+## Start Chrome (Prefer Headless)
+
+```bash
+./scripts/start.js --headless            # Recommended: isolated reusable profile
+./scripts/start.js --headless --profile  # Headless with a copy of your profile
+./scripts/start.js                       # Visible browser window when needed
+./scripts/start.js --headless --reset-profile  # Clear cached profile before launch
+```
+
+Starts Chrome with remote debugging (default port `:9222`). **Agents should use `--headless` by default** because it is less disruptive and supports navigation, evaluation, screenshots, emulation, and logging. User extensions are disabled for headless launches; a copied profile still provides its cookies and other browser state, but extension-based features are unavailable. Headed launches continue to load extensions normally. Use headed mode only when a person needs to see or interact with the browser, such as for `pick.js`, manual authentication, or debugging a headless-specific difference.
+
+The start script only reuses a running browser when its profile and launch settings match. Close the running skill browser before switching between headless and headed mode.
+
+Profile behavior:
+- Default mode uses: `~/.cache/agent-web/browser/fresh-profile`
+- `--profile` mode uses: `~/.cache/agent-web/browser/profile-copy`
+- The skill **does not attach to your live Chrome profile directly**
+- If `:9222` is already used by an unknown instance, start will fail instead of reusing it
+
+If Chrome is installed in a non-standard location, set:
+
+```bash
+BROWSER_BIN=/path/to/chrome ./scripts/start.js --headless
+```
+
+The launcher auto-detects common macOS and Linux paths. Under WSL, it also detects Windows Chrome in the standard `Program Files` locations and launches it through PowerShell with an isolated Windows-local profile.
+
+Optional debug endpoint override:
+
+```bash
+BROWSER_DEBUG_PORT=9333 ./scripts/start.js --headless
+```
+
+## Navigate
+
+```bash
+./scripts/nav.js https://example.com
+./scripts/nav.js https://example.com --new
+```
+
+Navigate current tab or open new tab.
+
+## Device Emulation (Mobile)
+
+```bash
+./scripts/emulate.js --list
+./scripts/emulate.js iphone-14
+./scripts/emulate.js pixel-7 --landscape
+./scripts/emulate.js --reset
+```
+
+Set an active device emulation preference (viewport, DPR, touch, UA) for browser skill commands. Use `--reset` to clear.
+
+Commands like `nav.js`, `eval.js`, `pick.js`, `dismiss-cookies.js`, and `screenshot.js` automatically apply the active preference.
+
+## Evaluate JavaScript
+
+```bash
+./scripts/eval.js 'document.title'
+./scripts/eval.js 'document.querySelectorAll("a").length'
+./scripts/eval.js 'document.querySelector("button")?.click(); "clicked"'
+./scripts/eval.js 'await Promise.resolve(document.title)'
+./scripts/eval.js 'JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => ({ text: a.textContent.trim(), href: a.href })).filter(link => !link.href.startsWith("https://")))'
+```
+
+Execute JavaScript in the active tab. Input can be an expression or statement list; the console-style completion value is printed and promises/top-level `await` are awaited. Be careful with string escaping, best to use single quotes.
+
+## Screenshot
+
+```bash
+./scripts/screenshot.js
+./scripts/screenshot.js --full-page
+./scripts/screenshot.js --device iphone-14
+./scripts/screenshot.js --device pixel-7 --full-page
+```
+
+Takes a screenshot and returns a temp file path.
+
+- Default: current viewport
+- `--full-page`: captures full document height
+- `--device <preset>`: temporary mobile emulation for that screenshot only
+
+## Pick Elements
+
+```bash
+./scripts/pick.js "Click the submit button"
+```
+
+Interactive element picker. Click to select, Cmd/Ctrl+Click for multi-select, Enter to finish. This requires headed Chrome; launch `start.js` without `--headless`.
+
+## Dismiss Cookie Dialogs
+
+```bash
+./scripts/dismiss-cookies.js          # Accept cookies
+./scripts/dismiss-cookies.js --reject # Reject cookies (where possible)
+```
+
+Automatically dismisses EU cookie consent dialogs.
+
+Run after navigating to a page:
+```bash
+./scripts/nav.js https://example.com && ./scripts/dismiss-cookies.js
+```
+
+## Quick Mobile Debug Flow
+
+```bash
+./scripts/start.js --headless
+./scripts/nav.js https://example.com
+./scripts/emulate.js iphone-14
+./scripts/nav.js https://example.com      # reload with mobile UA
+./scripts/dismiss-cookies.js
+./scripts/screenshot.js --full-page
+```
+
+## Background Logging (Console + Errors + Network)
+
+Automatically started by `start.js` and writes JSONL logs to:
+
+```
+~/.cache/agent-web/logs/YYYY-MM-DD/<targetId>.jsonl
+```
+
+Manually start:
+```bash
+./scripts/watch.js
+```
+
+Tail latest log:
+```bash
+./scripts/logs-tail.js           # dump current log and exit
+./scripts/logs-tail.js --follow  # keep following
+```
+
+Summarize network responses:
+```bash
+./scripts/net-summary.js
+```