webhand 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 sakamoto66
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.ja.md ADDED
@@ -0,0 +1,89 @@
1
+ # webhand
2
+
3
+ [English](README.md) | 日本語
4
+
5
+ **人がサービスに慣れるように、サービスを学んでから操作するブラウザエージェントです。** Claude Code のプラグインとして動き、予約や申し込み、フォームへの入力などを言葉で頼むと、学んだことをもとにブラウザを操作して片付けます。
6
+
7
+ ```text
8
+ /webhand HOTEL PLANISPHERE で来月の土曜から2泊、2名で予約して
9
+ ```
10
+
11
+ - **サービスを学ぶ。** 人の操作の記録やサービスのソースコードから、ページの構成、手順、注意点を学び、サービス情報と手順書にまとめます。
12
+ - **学んだことをもとに操作する。** Claude が学んだ内容から GOAL、手順、入力値を計画し、Jev がサービス情報と計画をもとにクリックと入力を選びます。届かなければ、Claude が原因を考えて計画を見直します。
13
+ - **学ぶ前から使える。** 初めてのサイトでも、頼んだ内容から計画して操作します。よく使うサービスから学ばせていけます。
14
+
15
+ > ⚠️ **webhand が操作するページの内容は Jev(TypeSafe の API)に送られます。** 保存プロファイルを使う場合は、ログインしたページも含みます。[安全とプライバシー](#安全とプライバシー)を参照してください。
16
+
17
+ ## はじめに
18
+
19
+ 1. プラグインを追加します(Claude Code)。
20
+
21
+ ```text
22
+ /plugin marketplace add sakamoto66/webhand
23
+ /plugin install webhand@webhand
24
+ ```
25
+
26
+ 2. Jev の API キーを環境変数に設定し、Claude Code を起動し直します(`TYPESAFE_MODEL` で使うモデルも変えられます)。
27
+
28
+ ```bash
29
+ echo 'export TYPESAFE_API_KEY=...' >> ~/.bashrc # 使っているシェルの設定ファイルに
30
+ ```
31
+
32
+ 3. 用事を頼みます。
33
+
34
+ ```text
35
+ /webhand HOTEL PLANISPHERE で来月の土曜から2泊、2名で予約して
36
+ ```
37
+
38
+ 必要なもの: Node.js 22 以上と Google Chrome(Linux、または WSL から Windows 側。[WSL で Windows 側の Chrome を使う](docs/reference.ja.md#wsl-で-windows-側の-chrome-を使う)を参照)。CLI はインストール不要で、スキルが `npx -y webhand@0.3 ...` で実行します。毎回の起動を速くしたい場合は `npm i -g webhand` で入れておくと、スキルは `webhand ...` を使います。
39
+
40
+ ```bash
41
+ npx -y webhand@0.3 catalog # 動作確認
42
+ ```
43
+
44
+ ## しくみ
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ U([ユーザー]) -->|依頼| P[Claude: GOAL・手順・入力値を計画]
49
+ P --> R[Jev: 次の操作を選ぶ]
50
+ R -->|操作| B[(Chrome)]
51
+ B -->|観測| R
52
+ R -->|GOAL 到達 / 助けが必要| C{Claude: 確認}
53
+ C -->|完了| F([finish])
54
+ C -->|未達| P
55
+ C -->|入力値の不足・ログイン・CAPTCHA| U
56
+ ```
57
+
58
+ 1. **学習する**: `/webhand-learn` で、人の操作の記録、ソースコード、または過去の実行ログから、サービス情報と手順書を作ります。
59
+ 2. **頼む**: `/webhand ホテルを予約して` のように投稿します。Claude が学習済みのデータから GOAL、手順、入力値を計画し、足りない情報はユーザーに質問します。
60
+ 3. **セッションを選ぶ**: 新規(使い捨て、既定)か、ログイン状態を残した保存プロファイルかを選びます。
61
+ 4. **実行する**: 計画した URL を開きます。Jev は、サービス情報、計画、表示中のページ、これまでの操作履歴をもとに次の操作を選び、GOAL までループします。
62
+ 5. **見直す**: GOAL に届かなければ、Claude が原因を書いて計画を見直し、再挑戦します(既定で最大3回)。
63
+
64
+ 判断(計画、入力値、確認、見直し)は Claude が、クリックと入力の繰り返しは Jev が担います。Jev は、ページで見つけた要素と Claude が書いた入力値の中から選ぶだけです。Claude に制御が戻るのは、Jev が GOAL 到達を報告したとき、入力値や人の操作が必要なとき、行き詰まったとき、操作が効いたか分からないときだけです。一覧は[役割分担](docs/reference.ja.md#役割分担)にあります。
65
+
66
+ ## 安全とプライバシー
67
+
68
+ - **外部に送られるもの**: 操作中のページの文字と操作対象は Jev(TypeSafe の API)に送られます。保存プロファイルを使う場合は、ログインしたページも含みます。実行のたびに、送ってよい画面か判断してください。
69
+ - **プロファイル**: 既定では使い捨てのプロファイルを使い、実行が終わると削除します。ログイン状態は webhand 専用の保存プロファイル(`--session profile:NAME`)にだけ残し、実行ごとにユーザーが選びます。普段使いの Chrome プロファイルには接続しません。
70
+ - **資格情報**: パスワードや確認コードは、ユーザーが Chrome に直接入力します。Claude は受け取らず、webhand は password 欄の値を読みません。
71
+ - **推測で入力しない**: 入力されるのは、Claude が計画で書いた値と、あなたが渡した値だけです。足りなければ尋ねます。
72
+ - **やみくもに再試行しない**: ページへの変更操作はリトライしません。操作が効いたか分からないときは、繰り返さずに停止します。
73
+ - **ページの本文は信頼しない**: ページの内容はデータとして扱い、指示としては扱いません。
74
+ - **記録とログ**: 学習モードでは、パスワード、ワンタイムコード、カード番号などの欄と、URL のクエリ値をすべて伏せます。実行ログには、入力した値ではなく値のラベルを残します。それでも `~/.webhand/runs/` のログにはページの文字が残るため、共有しないでください。
75
+ - **使う前に確認**: 手順書は `draft` で作られ、ユーザーが `approved` にするまで通常の実行には使いません。秘密情報や個人情報は手順書に書かず、`params` で渡します。
76
+
77
+ ## ドキュメント
78
+
79
+ | 文書 | 内容 |
80
+ | --- | --- |
81
+ | [リファレンス](docs/reference.ja.md) | 保存場所、役割分担と結果、セッション、コマンド、学習モード、ページの領域、ログ |
82
+ | [利用ガイド](docs/usage.ja.md) | スキルと CLI の使い方、よくあるつまずき |
83
+ | [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) | 開発に参加する人向け。コード構成、規則、テスト、研究、リリース手順 |
84
+
85
+ ## ライセンス
86
+
87
+ MIT License(`LICENSE`)。
88
+
89
+ `assets/snapshot.js`、`src/policies/base.ts`、`src/policies/jev.ts`、`tasks/fixtures/hotel.html` は [jev-ultrafast](https://github.com/browser-use/jev-ultrafast)(MIT)を改変したものです。`THIRD_PARTY_LICENSE_jev-ultrafast.txt` を参照してください。
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # webhand
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [日本語](README.ja.md)
4
+
5
+ **A browser agent that learns a service before operating it, the way people get used to a service.** It runs as a Claude Code plugin: ask in plain words for a booking, an application, or a form to fill in, and it operates the browser based on what it has learned.
6
+
7
+ ```text
8
+ /webhand On HOTEL PLANISPHERE, book 2 nights for 2 people starting next month's first Saturday
9
+ ```
10
+
11
+ - **It learns services.** From a recording of a person using a service, or from the service's source code, it learns the pages, the steps, and the pitfalls, and writes them down as service information and runbooks.
12
+ - **It operates from what it learned.** Claude plans the GOAL, steps, and input values from what was learned, and Jev picks each click and entry from the service information and the plan. If the GOAL is not reached, Claude works out why and replans.
13
+ - **It works before learning, too.** On a site it has never seen, it plans from your request alone. You can teach it the services you use most, one at a time.
14
+
15
+ > ⚠️ **The content of the pages webhand operates is sent to Jev (the TypeSafe API)**, including pages you are logged in to when you use a saved profile. See [Safety and privacy](#safety-and-privacy).
16
+
17
+ ## Quick start
18
+
19
+ 1. Add the plugin in Claude Code.
20
+
21
+ ```text
22
+ /plugin marketplace add sakamoto66/webhand
23
+ /plugin install webhand@webhand
24
+ ```
25
+
26
+ 2. Set Jev's API key as an environment variable and restart Claude Code. (`TYPESAFE_MODEL` selects the model.)
27
+
28
+ ```bash
29
+ echo 'export TYPESAFE_API_KEY=...' >> ~/.bashrc # or your shell's profile
30
+ ```
31
+
32
+ 3. Ask for something.
33
+
34
+ ```text
35
+ /webhand On HOTEL PLANISPHERE, book 2 nights for 2 people starting next month's first Saturday
36
+ ```
37
+
38
+ Requirements: Node.js 22 or later and Google Chrome (on Linux, or the Windows side from WSL; see [Using Windows Chrome from WSL](docs/reference.md#using-windows-chrome-from-wsl)). The CLI needs no installation: the skills run it with `npx -y webhand@0.3 ...`. For faster startup, install it globally with `npm i -g webhand`; the skills then use `webhand ...`.
39
+
40
+ ```bash
41
+ npx -y webhand@0.3 catalog # smoke check
42
+ ```
43
+
44
+ ## How it works
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ U([You]) -->|request| P[Claude: plan GOAL, steps, values]
49
+ P --> R[Jev: pick the next action]
50
+ R -->|act| B[(Chrome)]
51
+ B -->|observe| R
52
+ R -->|GOAL reached or needs help| C{Claude: check}
53
+ C -->|done| F([finish])
54
+ C -->|not yet| P
55
+ C -->|missing value, login, CAPTCHA| U
56
+ ```
57
+
58
+ 1. **Learn**: `/webhand-learn` turns a recorded demonstration, the service's source code, or the log of an earlier run into service information and a runbook.
59
+ 2. **Ask**: Post a request such as `/webhand book a hotel`. Claude plans the GOAL, steps, and input values from what webhand has learned, and asks you for anything missing.
60
+ 3. **Choose a session**: A fresh, throwaway session (the default), or a saved profile that keeps you logged in.
61
+ 4. **Run**: The planned URL opens. Jev picks the next action from the service information, the plan, the current page, and the action history, and loops until the GOAL.
62
+ 5. **Replan**: If the GOAL is not reached, Claude writes down why, revises the plan, and tries again (up to 3 attempts by default).
63
+
64
+ Claude makes the judgment calls (the plan, the values, the check, the replan), and Jev makes the many clicks and entries in between. Jev only chooses among the elements found on the page and the values Claude wrote. Control returns to Claude only when Jev reports the GOAL, needs a value or a person, gets stuck, or cannot tell whether an action took effect. The full list is in [Division of roles](docs/reference.md#division-of-roles).
65
+
66
+ ## Safety and privacy
67
+
68
+ - **What leaves your machine**: The text and actions of the page being operated go to Jev (the TypeSafe API). With a saved profile, that includes pages you are logged in to. Decide before each run whether that is acceptable.
69
+ - **Profiles**: Runs use a temporary profile by default, deleted when the run ends. Login state lives only in profiles dedicated to webhand (`--session profile:NAME`), which you choose per run. webhand never connects to your everyday Chrome profile.
70
+ - **Credentials**: You type passwords and codes into Chrome yourself. Claude does not receive them, and webhand does not read the values of password fields.
71
+ - **No guessed input**: The only values entered are the ones Claude wrote in the plan and the ones you gave. If something is missing, it asks.
72
+ - **No blind retries**: A change to the page is never retried. If webhand cannot tell whether an action took effect, it stops instead of trying again.
73
+ - **Page text is untrusted**: Content on the page is treated as data, never as instructions.
74
+ - **Recordings and logs**: Learning mode masks password, one-time code, and card fields and all URL query values. Run logs keep the label of each typed value, not the value. Logs under `~/.webhand/runs/` still contain page text, so do not share them.
75
+ - **Review before use**: Runbooks start as `draft` and are used for normal runs only after you set them to `approved`. Keep secrets and personal data out of runbooks; pass them as `params`.
76
+
77
+ ## Documentation
78
+
79
+ | Document | Contents |
80
+ | --- | --- |
81
+ | [Reference](docs/reference.md) | Where files live, roles and results, sessions, commands, learning mode, page regions, logs |
82
+ | [Usage guide](docs/usage.md) | Skills and CLI step by step, common pitfalls |
83
+ | [DEVELOPMENT.md](DEVELOPMENT.md) | For contributors: code layout, rules, tests, research, release steps |
84
+
85
+ ## License
86
+
87
+ MIT License (`LICENSE`).
88
+
89
+ `assets/snapshot.js`, `src/policies/base.ts`, `src/policies/jev.ts`, and `tasks/fixtures/hotel.html` are modified from [jev-ultrafast](https://github.com/browser-use/jev-ultrafast) (MIT). See `THIRD_PARTY_LICENSE_jev-ultrafast.txt`.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Browser Use
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,113 @@
1
+ (() => {
2
+ if (window.__browserLabRecorder) return;
3
+ window.__browserLabRecorder = true;
4
+ const read = () => __SNAPSHOT__;
5
+ const inFrame = window !== window.top;
6
+ const secretWords = /pass|pwd|\bpw\b|secret|token|otp|cvv|cvc|card|ssn|\bpin\b|パスワード|暗証|認証コード|カード/i;
7
+ const secretAutocomplete = /(^|\s)(current-password|new-password|one-time-code|cc-[a-z-]+)(\s|$)/;
8
+ const everPassword = new WeakSet();
9
+ const secret = (e, label) => e.type === 'password' || everPassword.has(e) ||
10
+ secretAutocomplete.test(e.getAttribute('autocomplete') || '') ||
11
+ secretWords.test([e.name, e.id, e.getAttribute('aria-label'), e.getAttribute('placeholder'), label].join(' '));
12
+ // A GET form copies field values into the URL under any key, so no query value is kept.
13
+ const safeUrl = () => {
14
+ const url = new URL(location.href);
15
+ for (const key of [...url.searchParams.keys()]) url.searchParams.set(key, '<redacted>');
16
+ if (url.hash.includes('=')) url.hash = '<redacted>';
17
+ return url.href;
18
+ };
19
+ // A region key is built from labels and headings. A segment whose name looks secret keeps only its kind.
20
+ const safeRegion = key => (key || '').split('/').map(segment => {
21
+ const [kind, ...name] = segment.split(':');
22
+ return name.length && secretWords.test(name.join(':')) ? kind + ':<redacted>' : segment;
23
+ }).join('/');
24
+ const send = event => {
25
+ const payload = {...event, url: safeUrl()};
26
+ window.__browserLabRecord?.(inFrame ? {...payload, kind: 'unsupported', reason: 'iframe'} : payload);
27
+ };
28
+ // Listeners on window see shadow DOM events retargeted to the host; use the original target.
29
+ const origin = event => event.composedPath()[0];
30
+ const describe = target => {
31
+ const element = target instanceof Element ? target : target?.parentElement;
32
+ if (!element) return null;
33
+ read();
34
+ const lab = window.__browserLab;
35
+ const found = lab?.describe(element) ??
36
+ {role: 'none', label: (element.innerText || '').trim().slice(0, 80), element};
37
+ return {...found, region: safeRegion(lab?.region?.(found.element))};
38
+ };
39
+ let timer = null;
40
+ const sendPage = () => {
41
+ if (inFrame) return;
42
+ const state = read();
43
+ if (!state) return;
44
+ // The outline only: where each region is and how much it holds. No text from inside it.
45
+ const regions = state.regions.map(r => ({key: safeRegion(r.key), position: r.position,
46
+ text_chars: r.text_chars, actions: r.actions, offscreen_actions: r.offscreen_actions}));
47
+ window.__browserLabRecord?.({kind: 'page', url: safeUrl(), title: state.title, text: state.text.slice(0, 2000), regions});
48
+ };
49
+ const action = event => {
50
+ send({kind: 'action', ...event});
51
+ clearTimeout(timer);
52
+ timer = setTimeout(sendPage, 400);
53
+ };
54
+ const textField = e => e.matches?.('input:not([type=checkbox],[type=radio],[type=button],[type=submit],[type=reset],[type=image]),textarea,select');
55
+
56
+ addEventListener('focusin', event => {
57
+ if (event.isTrusted && origin(event).type === 'password') everPassword.add(origin(event));
58
+ }, true);
59
+ addEventListener('click', event => {
60
+ if (!event.isTrusted) return;
61
+ const found = describe(origin(event));
62
+ if (!found || textField(found.element) || ['checkbox', 'radio'].includes(found.element.type)) return;
63
+ action({operation: 'click', role: found.role, label: found.label, region: found.region});
64
+ }, true);
65
+ const onChange = event => {
66
+ if (!event.isTrusted) return;
67
+ const found = describe(origin(event)), e = found?.element;
68
+ if (!e) return;
69
+ const base = {role: found.role, label: found.label, region: found.region};
70
+ if (e.type === 'file') send({kind: 'unsupported', reason: 'file_input', ...base});
71
+ else if (['checkbox', 'radio'].includes(e.type)) action({operation: 'toggle', checked: e.checked, ...base});
72
+ else if (secret(e, found.label)) action({operation: 'fill', value: '<redacted>', ...base});
73
+ else if (e.tagName === 'SELECT') {
74
+ action({operation: 'select', value: [...e.selectedOptions].map(o => o.label).join(', '), ...base});
75
+ } else action({operation: 'fill', value: e.value, ...base});
76
+ };
77
+ addEventListener('focusout', event => {
78
+ if (!event.isTrusted || !origin(event).isContentEditable) return;
79
+ const found = describe(origin(event));
80
+ if (found) action({operation: 'fill', role: found.role, label: found.label, region: found.region,
81
+ value: secret(found.element, found.label) ? '<redacted>' : found.element.innerText.slice(0, 500)});
82
+ }, true);
83
+ const onSubmit = event => {
84
+ if (!event.isTrusted) return;
85
+ action({operation: 'submit', role: 'form', label: event.target.getAttribute('aria-label') || event.target.name || ''});
86
+ };
87
+ // change and submit are not composed, so they stop at their shadow root and never reach window.
88
+ // Each open shadow root gets these two listeners; composed events are heard on window only once.
89
+ const listen = root => {
90
+ root.addEventListener('change', onChange, true);
91
+ root.addEventListener('submit', onSubmit, true);
92
+ };
93
+ listen(window);
94
+ const attach = Element.prototype.attachShadow;
95
+ Element.prototype.attachShadow = function (...args) {
96
+ const root = attach.apply(this, args);
97
+ if (root.mode === 'open') listen(root);
98
+ return root;
99
+ };
100
+ // Declarative shadow roots are created by the parser without attachShadow.
101
+ const listenDeclarative = () => {
102
+ const walker = document.createTreeWalker(document, NodeFilter.SHOW_ELEMENT);
103
+ for (let e = walker.nextNode(); e; e = walker.nextNode()) if (e.shadowRoot) listen(e.shadowRoot);
104
+ };
105
+ addEventListener('DOMContentLoaded', listenDeclarative);
106
+ // Enter is the only key ever looked at. Nothing else typed reaches this listener's output.
107
+ addEventListener('keydown', event => {
108
+ if (!event.isTrusted || event.key !== 'Enter') return;
109
+ const found = describe(origin(event));
110
+ if (found) action({operation: 'press_enter', role: found.role, label: found.label, region: found.region});
111
+ }, true);
112
+ addEventListener('load', sendPage);
113
+ })();