@omniaibot/win-x64 1.1.2 → 1.1.6

package/bin/omnibot-windows-x64/VERSION

@@ -1 +1 @@
-1.1.2
+1.1.6

package/bin/omnibot-windows-x64/omnibot/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: omnibot
+description: Use when AI agents need to read, inspect, operate, navigate, debug, or verify browser state through the omnibot CLI and connected Chromium extension.
+compatibility: Requires omnibot v2 CLI daemon and the omnibot Chromium extension connected to 127.0.0.1:18765.
+allowed-tools: Bash
+metadata:
+  author: omnibot
+  version: "2.1.0"
+---
+
+# Omnibot
+
+Omnibot is Browser Infrastructure for AI Agents.
+
+It connects Hermes, Claude Code, Codex, OpenCode, and other agent systems to a real Chromium browser through the local omnibot daemon and CLI.
+
+This skill is an execution specification for agents. It is not a human command manual.
+
+## When to Use
+
+- Use Omnibot when browser runtime state matters: login, cookies, storage, client-side rendering, extensions, or visible user tabs.
+- Use Omnibot when an agent must read rendered pages, click controls, fill forms, upload files, navigate, extract content, or collect evidence.
+- Do not use Omnibot when static files or plain HTTP content already answer the task.
+
+## Core Rules
+
+- Reliability > Convenience.
+- Explicit State > Implicit State.
+- Pattern > Command.
+- Observe -> Act -> Verify.
+- Fallback is allowed, but never first.
+- Do not use `execute-js` first.
+- Prefer semantic locators and `snapshot -i` refs before selectors.
+- Prefer condition-based `wait` over shell sleep.
+- Parse JSON output from commands that return JSON.
+- Do not claim success without verification evidence.
+
+## Session + Tab Double Lock
+
+Every page-state workflow must use both controls:
+
+- `OMNIBOT_SESSION_TOKEN=<workflow-name>` for workflow isolation.
+- `--tab-id <TAB_ID>` for page targeting.
+
+They are not substitutes. Session controls which workflow owns state. Tab ID controls which page receives the command.
+
+Do not rely on default tab, active tab, current tab, or prior targeting state. Every page command requires explicit `--tab-id`.
+
+Use the same token inside one workflow. Use different tokens for independent workflows.
+
+Standard form:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+`@eN` refs are tab-scoped. never reuse `@eN` refs across tabs.
+
+The agent dispatch pattern is token + tab-id:
+
+1. Set a stable `OMNIBOT_SESSION_TOKEN`.
+2. Discover or create the target tab.
+3. Save the returned tab id.
+4. Pass `--tab-id <TAB_ID>` on every command that touches page state.
+5. Run observe -> act -> verify on that same tab.
+
+Examples of tab-locked page-state commands:
+
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot find placeholder "Search" --action type --action-value "omnibot" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot dom dblclick n1 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot clipboard read --tab-id <TAB_ID>
+```
+
+## Observe -> Act -> Verify
+
+All page operations must follow this loop:
+
+1. Observe the current page state.
+2. Act once using the highest reliable pattern available.
+3. Verify the expected state change.
+
+Click example:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+Read/verify example:
+
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
+```
+
+If verification fails, do not repeat blindly. Re-observe, choose the next fallback tier, and verify again.
+
+## Pattern > Command
+
+Start from the task, not the command name. Use operation patterns for read, click, fill, select/check, navigation, wait, extraction, upload, and batch.
+
+Use fallback tiers only after standard patterns fail. Collect evidence separately from fallback execution. The command reference is only a lookup table; it must not decide behavior.
+
+## Read vs Snapshot Routing
+
+Choose by intent before choosing by command name:
+
+| Intent | Prefer | Why |
+| --- | --- | --- |
+| Summarize or extract page content, article text, search results, feeds, or long/lazy pages | `read` | Returns clean text/Markdown for agent reasoning. |
+| Quickly observe current visible UI structure before deciding what to do next | `snapshot -i` | Returns actionable refs and page structure for routing. |
+| Find buttons, links, inputs, or refs for a later action | `find` or `snapshot -i` | Produces actionable targets; `read` does not. |
+| Verify one concrete condition | `get`, `is`, or `wait` | Narrow evidence is more reliable than dumping a page. |
+
+Do not use `read` as the first step for click/fill workflows unless the user explicitly asked for page content first.
+
+## Quick Routing
+
+| Need | Read |
+| --- | --- |
+| Runtime check | `references/runtime-and-status.md` |
+| Reading pages | `references/operation-patterns.md#read` |
+| Clicking | `references/operation-patterns.md#click` |
+| Filling forms | `references/operation-patterns.md#fill` |
+| Select / check | `references/operation-patterns.md#select--check` |
+| Navigation | `references/operation-patterns.md#navigation` |
+| Waiting | `references/operation-patterns.md#wait` |
+| Extraction | `references/operation-patterns.md#extraction` |
+| Upload | `references/operation-patterns.md#upload` |
+| Batch | `references/operation-patterns.md#batch` |
+| Fallback | `references/fallback-operations.md` |
+| Tabs and sessions | `references/session-and-tabs.md` |
+| Debug evidence | `references/debugging-and-evidence.md` |
+| Commands | `references/command-reference.md` |
+| Anti-patterns | `references/anti-patterns.md` |
+
+## Runtime First
+
+Before troubleshooting browser behavior, check runtime state:
+
+```bash
+omnibot doctor
+omnibot tabs
+omnibot visibility status
+omnibot browser current
+omnibot license status
+```
+
+If the extension is not connected, open Chrome or Edge with the omnibot extension loaded and keep an HTTP/HTTPS tab open.
+
+## Fallback Discipline
+
+Fallback tiers are for completing operations after better patterns fail. They are not debugging shortcuts.
+
+Tier order:
+
+1. Semantic `find`.
+2. `snapshot -i` refs.
+3. Selectors.
+4. `dom` fallback.
+5. `mouse` fallback.
+6. `execute-js` fallback.
+7. Raw `cdp` fallback.
+
+When entering a lower tier, state why the higher tier failed. After any fallback action, verify with `snapshot`, `get`, `is`, `wait`, or equivalent evidence.
+
+## Debug Evidence
+
+Debugging is for evidence. Fallback is for completing operations.
+
+Use screenshots, annotated screenshots, console logs, network logs, trace, record/replay, and CDP inspection to explain failures or prove state. Do not treat `execute-js` as ordinary debug output.
+
+## Absolute Prohibitions
+
+- Missing `OMNIBOT_SESSION_TOKEN` or missing `--tab-id` on page-state commands.
+- Acting without verify or claiming success without evidence.
+- Using `execute-js` first, raw CSS before semantic find, `@eN` across tabs, implicit tab targeting, or shell sleep instead of `omnibot wait`.
+- Using removed commands: `switch-tab`, `focus-tab`, `tab switch`. These are no longer available.
+- Using `tabs[0]` or the first tab as a target. The first tab is often a user tab or transport tab.
+- Closing user tabs discovered during cleanup. Only close tabs created by the current workflow.
+
+See `references/anti-patterns.md` before using shortcuts.

package/bin/omnibot-windows-x64/omnibot/references/anti-patterns.md

@@ -0,0 +1,37 @@
+# Anti-Patterns
+
+| Bad | Why bad | Good |
+| --- | --- | --- |
+| Missing `OMNIBOT_SESSION_TOKEN` | Workflows can share implicit state across agents. | `OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>` |
+| Missing `--tab-id` | The command may target the wrong page. | Pass `--tab-id <TAB_ID>` on every page-state command. |
+| `execute-js` first | JavaScript bypasses standard browser interaction and hides better evidence. | Try semantic find, snapshot refs, selectors, DOM, and mouse first. For CSS-only dropdowns, use JavaScript only after the trigger clicked, options remain absent from `snapshot -i`, and higher tiers cannot complete open-then-select. |
+| Reusing `@eN` across tabs | Refs are tab-scoped and may point to a different element elsewhere. | Take a fresh `snapshot -i --tab-id <TAB_ID>` per tab. |
+| Relying on implicit tab targeting | It is unavailable and unsafe for concurrent workflows. | Use explicit `--tab-id` on every page-state command. |
+| Using sleep instead of wait | Fixed sleeps are flaky and either too short or too slow. | Use `omnibot wait --text`, `--url`, selector state, load state, or `--fn`. |
+| Acting without verify | Command success is not task success. | Run `snapshot`, `get`, `is`, or `wait` after every action. |
+| Claiming success without evidence | The browser may not have changed as expected. | Cite verified URL, text, element state, screenshot, console, or network evidence. |
+| Raw CSS before semantic find | CSS is more brittle and less tied to user intent. | Start with `find role/text/label/placeholder/testid`. |
+| Screenshot when text extraction is enough | Screenshots cost more and are harder to parse. | Use `read` for page content or `get text` for a selector. |
+| Using `read` before an action workflow | `read` returns text, not stable action targets. | Use `find`, `snapshot -i`, `get`, or `is` for click/fill/verify workflows. |
+| Headless expecting existing user login | Headless does not automatically share the user's visible browser session. | Use visible/background mode for existing login or explicitly log in headless. |
+| Mixing multiple workflows in one session token | Agents can overwrite each other's default state. | Use different tokens: `research`, `checkout`, `debug`. |
+| Using default tab state in concurrent agents | There is no default tab. Every page command requires explicit `--tab-id`. | Discover or create a tab, save its id, and pass `--tab-id`. |
+| Not checking doctor/tabs before troubleshooting | You may debug page logic when the runtime is disconnected. | Run `omnibot doctor` and `omnibot tabs` first. |
+| Using `tabs[0]` or the first tab | The first tab is often a user tab or the transport tab, not the workflow target. | Create or identify the intended tab and store its full id. |
+| Treating transport as target | Extension routing may use a different tab than the page being acted on. | Always pass `--tab-id <TAB_ID>` and verify with `get url --tab-id <TAB_ID>`. |
+| Closing discovered user tabs | Cleanup can destroy the user's real work. | Track only tool-created tabs and close only those ids. |
+| Leaving worker-token tabs untracked | Cross-token test tabs can remain open or auto-close later. | Add every worker-created tab id to cleanup tracking. |
+
+## Red Flags
+
+- "I can just use the current tab."
+- "This is only one click, no need to verify."
+- "JavaScript is faster."
+- "The ref probably still points to the same element."
+- "A screenshot is enough even though I need text."
+- "Sleep should be fine."
+- "The trigger clicked, so another `find text` should eventually select the option."
+- "`snapshot -i` cannot see the option, so the element must not exist."
+- "This dropdown is custom, so I can start with JavaScript."
+
+All of these mean: stop, re-enter the standard pattern, and make state explicit.