yunti-browser-runtime 0.1.0

package/docs/RELEASE.md

@@ -0,0 +1,148 @@
+# Release Runbook
+
+This runbook describes the local release checklist for Yunti Browser Runtime.
+
+## Prerequisites
+
+- Node.js 22 or newer.
+- A clean local checkout of the project.
+- Access to the public repository that will be listed in `package.json`.
+- npm publish permission for the `yunti-browser-runtime` package name.
+
+## Required External Confirmation
+
+Before publishing, confirm the package metadata points to live public URLs:
+
+```bash
+npm run check:metadata
+```
+
+Expected pre-first-release state:
+
+- GitHub repository URL returns a non-404 status.
+- GitHub issues URL returns a non-404 status or the issue tracker URL is updated.
+- `npm view yunti-browser-runtime` may return E404 if `0.1.0` is the first release.
+
+If the GitHub URLs return 404, do not publish. Create or publicize the repository,
+or update `repository`, `homepage`, and `bugs.url` in `package.json`.
+Detailed remediation options are tracked in
+[`docs/PUBLISHING_BLOCKERS.md`](PUBLISHING_BLOCKERS.md).
+
+`npm run check:metadata` exits non-zero when repository, homepage, or issue URLs
+are not publicly reachable. It treats npm E404 as acceptable for a first release
+and reports that state in JSON.
+
+## Local Release Gate
+
+Run the consolidated release gate:
+
+```bash
+npm run release:check
+```
+
+This command verifies:
+
+- public docs do not contain local/internal residue;
+- public Markdown relative links resolve to existing files;
+- `package.json` and `extension/manifest.json` use the same version;
+- npm bin smoke checks for `yunti-browser-runtime --help` and `--version` pass;
+- Agent config smoke checks for Codex, Claude Code, Cursor, and Cline pass;
+- doctor JSON smoke check returns structured diagnostics and local file checks;
+- all JavaScript files pass `node --check`;
+- the unit test suite passes;
+- `npm pack --json --dry-run` includes required runtime, extension, skill,
+  release documentation, and release helper files.
+- `npm run package:extension` creates an extension zip containing only the
+  required runtime files.
+
+After external package metadata is live, run the stricter prepublish gate:
+
+```bash
+npm run release:prepublish
+```
+
+This runs `npm run check:metadata` first, then `npm run release:check`.
+For the current `dingguangyi0/yunti-browser-runtime` repository metadata, this
+gate is expected to pass before publishing.
+
+## Extension Package
+
+Build and inspect the browser extension zip:
+
+```bash
+npm run package:extension
+unzip -l dist/yunti-browser-runtime-extension-0.1.0.zip
+```
+
+`npm run release:check` also validates this zip automatically by parsing the
+actual archive entries.
+
+The zip should contain only the extension runtime files:
+
+- `background.js`
+- `cdp.js`
+- `content.css`
+- `content.js`
+- `network-monitor.js`
+- `manifest.json`
+- `popup.css`
+- `popup.html`
+- `popup.js`
+- `session-manager.js`
+- `settings.js`
+- `tool-handlers.js`
+
+## Optional Real-Browser Smoke Test
+
+Run this when Playwright and Chromium are available:
+
+```bash
+YUNTI_E2E=1 npm run test:e2e
+```
+
+The default `npm test` run skips the real-browser smoke test unless `YUNTI_E2E=1`
+is set.
+
+## Publish
+
+After the external URL confirmation and local release gate pass:
+
+```bash
+npm run release:dry-run
+npm run release:publish
+```
+
+The dry-run and publish scripts both run `npm run release:prepublish` before
+publishing. They also pin `https://registry.npmjs.org/` so a local mirror
+registry configuration cannot accidentally receive the release.
+`npm run release:publish` also runs `npm run release:whoami` before publishing.
+
+If npm auth is missing, log in first:
+
+```bash
+npm adduser --registry=https://registry.npmjs.org/
+npm run release:whoami
+```
+
+If the npm account requires two-factor authentication for publishing, pass the
+current one-time password to the publish script:
+
+```bash
+npm run release:publish -- --otp=<6-digit-code>
+```
+
+Alternatively, publish with a granular access token that has package publish
+permission and bypass 2FA enabled.
+
+After publishing, verify:
+
+```bash
+npm run release:verify-published
+```
+
+## Post-Release
+
+- Re-run `npm run doctor` in a fresh local setup.
+- Re-run `npm run print-config -- --agent codex --human`.
+- Load or package the extension from the published source.
+- Update `docs/PROJECT_STATUS.md` with the release result and published version.

package/docs/ROADMAP.md

@@ -0,0 +1,42 @@
+# Roadmap
+
+## Phase 0: Scaffold
+
+- Create standalone repository structure.
+- Document project intent and status.
+- Define local-first architecture.
+
+## Phase 1: Local Runtime MVP
+
+- MCP stdio server starts a local bridge automatically.
+- Browser extension registers local tabs with the bridge.
+- Agent can list browser targets.
+- Agent can inspect a page snapshot.
+- Agent can send CDP commands through a stable browser route.
+- Agent can click, type, navigate, screenshot, and read network/console logs.
+
+## Phase 2: Install Experience
+
+- Add `npm run doctor`.
+- Add `npm run package:extension`.
+- Add MCP config printer.
+- Add clear Chrome/Edge extension loading instructions.
+
+## Phase 3: Reliability
+
+- Add session TTL and fast stale-session failures.
+- Add better error messages for wrong parameter combinations.
+- Add smoke tests for bridge, MCP, and extension message contracts.
+
+## Phase 4: Productization
+
+- Rename tools to `yunti_*`.
+- Keep compatibility aliases only when useful.
+- Publish an npm package.
+- Prepare public docs and examples.
+
+## Future: Remote Mode
+
+Remote multi-user operation is intentionally out of the first release. It should
+be designed as a separate server layer on top of the local runtime, not mixed
+into the local core.

package/docs/SECURITY.md

@@ -0,0 +1,56 @@
+# Security, Permissions, And Privacy Notes
+
+## Current Boundary
+
+The first release is local single-user software:
+
+- bridge binds to `127.0.0.1` by default;
+- bridge routes require `x-yunti-browser-token` except limited `/health`;
+- CORS only echoes local debug origins and browser-extension origins by default;
+- extension talks to the local bridge;
+- MCP tools default to `userId=local`;
+- no remote relay is part of the documented install path.
+
+## Data Handling
+
+- Cookies and raw authorization headers are not returned by network tools.
+- Network URLs, headers, request bodies, and console messages are sanitized.
+- Learning memory is stored under `~/.yunti_agent/users/{userId}/memory`.
+- The content script does not call product-specific login APIs.
+
+## Browser Permissions
+
+The extension uses browser permissions required for automation:
+
+- `tabs` for tab inventory and activation;
+- `debugger` for CDP commands;
+- `storage` for local bridge URL, token, user, and page-match settings;
+- `webRequest` for sanitized network observations;
+- `activeTab` for visible-tab capture fallback paths.
+
+The extension currently declares broad `http://*/*` and `https://*/*` host
+access so it can register and operate arbitrary local user-selected pages. It
+also declares localhost bridge access for the local HTTP bridge. A narrower
+allowlist can be configured in the extension popup with page match patterns, and
+store-distributed releases should re-review whether broad host permissions are
+still appropriate for the intended audience.
+
+Users should only load the extension from a trusted local checkout.
+
+## Privacy Notes
+
+- The runtime is local-first and does not send browser observations to a Yunti
+  hosted service.
+- Raw cookies, authorization headers, passwords, and token-like fields are not
+  returned by the documented tools.
+- Learning memory is local filesystem data and should not contain secrets.
+- Agents should summarize sensitive-looking output instead of repeating it.
+
+## Not Yet Implemented
+
+- Signed extension release package.
+- Remote multi-user isolation layer.
+- Per-tool allow/deny policy.
+
+Remote deployment must be designed separately and should not reuse the local
+single-user defaults without an authentication and ownership model.

package/docs/TOOL_GUIDE.md

@@ -0,0 +1,69 @@
+# Tool Guide
+
+## Agent Workflow
+
+1. Call `yunti_get_tool_usage_hints` when unsure about parameters or routing.
+2. Call `yunti_list_browser_targets` to understand the live browser state.
+3. Keep the returned `browserSessionId` for follow-up page/CDP tools.
+4. If the session becomes stale, call `yunti_list_browser_targets` again and
+   retry with the latest route.
+5. For multi-step page work, prefer one stable `browserSessionId` throughout the
+   task.
+
+Sessions expire when the extension stops polling the local bridge. Stale-session
+errors include a reason and recovery hint; do not keep retrying an expired id.
+
+## Core Tools
+
+- `yunti_list_browser_targets`: canonical live inventory for tabs and targets.
+- `yunti_list_pages`: compatibility alias for the same live inventory.
+- `yunti_get_page_snapshot`: lightweight page state and visible context.
+- `yunti_take_snapshot`: element-oriented snapshot for uid-based actions.
+- `yunti_click`, `yunti_fill`, `yunti_hover`: common DOM actions.
+- `yunti_cdp_send_command`: low-level CDP access routed through the extension.
+- `yunti_get_network_log`, `yunti_list_network_requests`: sanitized network
+  observations.
+- `yunti_list_console_messages`: console diagnostics.
+- `yunti_remember_learning`, `yunti_get_learning_memory`: local agent memory.
+
+## Routing Rules
+
+- Standalone local mode defaults to `userId=local`.
+- Agents do not need to pass `userId` unless they intentionally override
+  `YUNTI_BROWSER_USER_ID`.
+- `browserSessionId` identifies a registered browser page route.
+- `browserSessionId` expires without extension heartbeat; refresh live inventory
+  when a stale-session error appears.
+- New tabs can return a new `browserSessionId`; use the returned value for
+  follow-up calls on that tab.
+- Raw `targetId` or `tabId` is for CDP/tab operations, not a replacement for
+  `browserSessionId`.
+
+## CDP Rules
+
+- Do not run CDP method names in a shell.
+- Use `yunti_cdp_send_command` with `method` and optional `params`.
+- `params` must be an object when provided.
+- For `Target.activateTarget` or `Target.closeTarget`, pass top-level `tabId`
+  or `targetId` with a valid `browserSessionId`.
+- Use `Runtime.evaluate` for JavaScript evaluation, but keep related multi-step
+  work in one eval when page state must stay in the same execution context.
+
+## Parameter Rules
+
+- `yunti_click` and `yunti_hover` require a `uid`, a `selector`, or both `x`
+  and `y`; use `yunti_take_snapshot` to get stable uids.
+- `yunti_fill` requires `value` and either `uid` or `selector`; it does not
+  support coordinate-only targeting.
+- `yunti_close_page` closes by `browserSessionId`; to close by raw `tabId` or
+  `targetId`, use `yunti_cdp_send_command` with `Target.closeTarget`.
+- `yunti_forget_learning_memory` requires `id`, or `all=true` plus
+  `confirmed=true` when deleting every memory.
+
+## Safety Rules
+
+- Read-only inspection is allowed by default.
+- Destructive, financial, credential, upload, or submit actions should require
+  explicit user confirmation in the agent workflow.
+- Tool outputs redact likely cookies, authorization headers, passwords, and
+  token-like values.

package/extension/background.js

@@ -0,0 +1,55 @@
+import { createCdpController } from "./cdp.js"
+import { installNetworkMonitor } from "./network-monitor.js"
+import { createSessionManager } from "./session-manager.js"
+import { createToolDispatcher } from "./tool-handlers.js"
+
+const sessionManager = createSessionManager()
+const {
+  forwardConsoleEvent,
+  postBridge,
+  pollers,
+  sessionsByTab,
+  startPolling,
+} = sessionManager
+
+const cdp = createCdpController({
+  sessionsByTab,
+  pollers,
+  postBridge,
+  startPolling,
+  forwardConsoleEvent,
+})
+
+const { detachCdpTab, installCdpEventForwarder } = cdp
+const { executeToolRequest } = createToolDispatcher({
+  sessionsByTab,
+  pollers,
+  postBridge,
+  startPolling,
+  cdp,
+})
+
+sessionManager.setToolRequestHandler(executeToolRequest)
+
+installNetworkMonitor({
+  sessionsByTab,
+  postBridge,
+  getPlatformMatches: sessionManager.getPlatformMatches,
+})
+installCdpEventForwarder()
+
+chrome.tabs.onRemoved.addListener((tabId) => {
+  void detachCdpTab(tabId, null, "tab_removed").catch(() => {})
+  sessionManager.forgetTab(tabId)
+})
+
+chrome.tabs.onActivated.addListener(({ tabId }) => {
+  void sessionManager.activateTab(tabId)
+})
+
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  void sessionManager.handleMessage(message, sender).then(sendResponse, (error) =>
+    sendResponse({ ok: false, error: error?.message || String(error) })
+  )
+  return true
+})