finch-ego-lite 0.1.1 → 0.1.2

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
@@ -126,6 +126,94 @@ async function openWebsite() {
   const args = process.platform === "win32" ? ["/c", "start", "", WEBSITE] : [WEBSITE];
   await execFileAsync(command, args, { timeout: 5e3 });
 }
+var ACTION_STAGES = {
+  open_url: "opening",
+  snapshot: "reading",
+  extract: "reading",
+  click: "acting",
+  fill: "acting",
+  type: "acting",
+  press_key: "acting",
+  scroll: "scrolling",
+  screenshot: "shooting",
+  close_space: "closing",
+  run: "running"
+};
+function pickProgress(t, stage) {
+  const pool = t(`progress.${stage}`);
+  const list = pool.split("|").map((s) => s.trim()).filter(Boolean);
+  return list[Math.floor(Math.random() * list.length)] ?? pool;
+}
+async function resolveSpaceId(spaceId) {
+  if (spaceId !== void 0) return spaceId;
+  const status = await getStatus(false);
+  const agentSpaces = status.spaces.filter((space) => space.ownership === "agent");
+  if (agentSpaces.length === 1) return agentSpaces[0].id;
+  return void 0;
+}
+function buildScript(action, input, spaceId) {
+  const q = JSON.stringify;
+  const sel = input.selector ? q(input.selector) : "null";
+  const spaceLine = spaceId !== void 0 ? `await switchTaskSpace(${spaceId});` : "";
+  switch (action) {
+    case "open_url": {
+      const name = input.space_name || "web task";
+      const timeout = input.timeout_seconds ?? 20;
+      return `const space = await useOrCreateTaskSpace(${q(name)});
+await openOrReuseTab(${q(input.url ?? "")}, { wait: true, timeout: ${timeout} });
+const tab = await currentTab();
+cliLog(JSON.stringify({ spaceId: space.id, url: tab.url, title: tab.title }));`;
+    }
+    case "snapshot":
+      return `${spaceLine}
+const text = await snapshotText();
+cliLog(String(text));`;
+    case "extract":
+      return `${spaceLine}
+const sel = ${sel};
+let text;
+if (sel) {
+  text = String(await js('(() => { const el = document.querySelector(' + JSON.stringify(sel) + '); return el ? el.innerText : ""; })()'));
+} else {
+  text = String(await snapshotText());
+}
+cliLog(text);`;
+    case "click":
+      return `${spaceLine}
+await click(${sel});
+await waitForLoad({ timeout: 15 }).catch(() => {});
+const info = await pageInfo();
+cliLog(JSON.stringify({ ok: true, url: info.url, title: info.title }));`;
+    case "fill":
+      return `${spaceLine}
+await fillInput(${sel}, ${q(input.value ?? "")});
+cliLog('ok');`;
+    case "type":
+      return `${spaceLine}
+${sel !== "null" ? `await click(${sel});` : ""}
+await typeText(${q(input.text ?? "")});
+cliLog('ok');`;
+    case "press_key":
+      return `${spaceLine}
+await pressKey(${q(input.key ?? "Enter")});
+cliLog('ok');`;
+    case "scroll":
+      return `${spaceLine}
+await scrollBy({ y: ${input.delta_y ?? 300} });
+const info = await pageInfo();
+cliLog(JSON.stringify({ ok: true, sy: info.sy }));`;
+    case "screenshot":
+      return `${spaceLine}
+const path = await captureScreenshot();
+cliLog('__EGO_SHOT__' + path);`;
+    case "close_space":
+      return `await completeTaskSpace(${spaceId}, { keep: false });
+cliLog('ok');`;
+    case "run":
+    default:
+      return input.script ?? "";
+  }
+}
 function key(value) {
   return Buffer.from(JSON.stringify(value)).toString("base64url");
 }
@@ -393,17 +481,36 @@ ${domainOf(tab.url, t("site.unknown"))}`,
   ctx.subscriptions.push(ctx.tools.register({
     name: "ego_browser",
     title: "Ego Browser",
-    description: `Operate Ego Browser through its preloaded JavaScript helpers.
+    description: `Operate Ego Browser with declarative actions. Everyday browsing needs no scripts.
 action:
-  status \u2014 check installation, runtime, task-space ownership, and open pages
-  run    \u2014 execute one coherent Ego Browser JavaScript program (requires script)
-Use cliLog(...) for output. Reuse task spaces, respect user control, verify actions, and complete finished spaces.`,
+  status      \u2014 check installation, runtime, task spaces and open pages
+  open_url    \u2014 open a URL in a task space (url, space_name?) and return its spaceId
+  snapshot    \u2014 read the current page as text (space_id?)
+  click       \u2014 click an element by CSS selector (space_id?, selector)
+  fill        \u2014 fill a form field (space_id?, selector, value)
+  type        \u2014 type text; pass selector to focus the field first (space_id?, selector?, text)
+  press_key   \u2014 press a key: Enter, Tab, Escape, ArrowDown... (space_id?, key)
+  scroll      \u2014 scroll down by pixels (space_id?, delta_y?)
+  screenshot  \u2014 capture the page and return it as an image (space_id?)
+  extract     \u2014 extract innerText of a CSS selector, or the whole page (space_id?, selector?)
+  close_space \u2014 close a task space (space_id)
+  run         \u2014 advanced: run a raw Ego Browser script (script, timeout_seconds?)
+Most actions accept space_id; when omitted and exactly one agent-owned task space exists, it is used.
+Reuse task spaces, respect user ownership, verify meaningful actions, and complete spaces when done.`,
     inputSchema: {
       type: "object",
       properties: {
-        action: { type: "string", enum: ["status", "run"] },
-        script: { type: "string", description: "JavaScript program for action=run. Ego Browser helpers are preloaded." },
-        timeout_seconds: { type: "number", description: "Execution timeout for action=run, from 1 to 300 seconds. Default 60." }
+        action: { type: "string", enum: ["status", "open_url", "snapshot", "click", "fill", "type", "press_key", "scroll", "screenshot", "extract", "close_space", "run"] },
+        url: { type: "string", description: "URL to open (action=open_url)." },
+        space_id: { type: "number", description: "Task space id from status/open_url. Optional when only one agent space exists." },
+        space_name: { type: "string", description: "Semantic name for the task space (action=open_url)." },
+        selector: { type: "string", description: "CSS selector of the target element (click/fill/type/extract)." },
+        text: { type: "string", description: "Text to type (action=type)." },
+        value: { type: "string", description: "Value to fill into the field (action=fill)." },
+        key: { type: "string", description: "Key to press (action=press_key): Enter, Tab, Escape..." },
+        delta_y: { type: "number", description: "Pixels to scroll down (action=scroll, default 300)." },
+        script: { type: "string", description: "Raw Ego Browser script (action=run only)." },
+        timeout_seconds: { type: "number", description: "Execution timeout, 1 to 300 seconds. Default 60." }
       },
       required: ["action"]
     },
@@ -411,17 +518,35 @@ Use cliLog(...) for output. Reuse task spaces, respect user control, verify acti
     defaultEnabled: true,
     async execute(input, exec) {
       const request = input;
-      if (request.action === "status") {
+      const actionName = request.action ?? "";
+      if (actionName === "status") {
         const status = await getStatus(true);
         cachedStatus = status;
         action.notifyUpdate();
         return { content: [{ type: "text", text: statusText(status, t) }], isError: !status.supported || Boolean(status.error) };
       }
-      if (request.action !== "run" || typeof request.script !== "string" || !request.script.trim()) {
-        return { content: [{ type: "text", text: "action=run requires a non-empty script." }], isError: true };
+      if (!ACTION_STAGES[actionName]) {
+        return { content: [{ type: "text", text: `Unknown action: ${actionName}.` }], isError: true };
+      }
+      if (actionName === "run") {
+        if (typeof request.script !== "string" || !request.script.trim()) {
+          return { content: [{ type: "text", text: "action=run requires a non-empty script." }], isError: true };
+        }
+        if (request.script.length > 1e5 || request.script.includes("\0")) {
+          return { content: [{ type: "text", text: "The Ego Browser script is invalid or too large." }], isError: true };
+        }
+      }
+      if (actionName === "open_url" && !request.url) {
+        return { content: [{ type: "text", text: "action=open_url requires a url." }], isError: true };
+      }
+      if ((actionName === "click" || actionName === "fill" || actionName === "extract") && !request.selector) {
+        return { content: [{ type: "text", text: `action=${actionName} requires a CSS selector.` }], isError: true };
       }
-      if (request.script.length > 1e5 || request.script.includes("\0")) {
-        return { content: [{ type: "text", text: "The Ego Browser script is invalid or too large." }], isError: true };
+      if (actionName === "fill" && request.value === void 0) {
+        return { content: [{ type: "text", text: "action=fill requires a value." }], isError: true };
+      }
+      if (actionName === "type" && !request.text) {
+        return { content: [{ type: "text", text: "action=type requires text." }], isError: true };
       }
       if (process.platform !== "darwin") {
         return { content: [{ type: "text", text: t("status.unsupported", { platform: process.platform }) }], isError: true };
@@ -434,19 +559,43 @@ Use cliLog(...) for output. Reuse task spaces, respect user control, verify acti
           isError: true
         };
       }
+      let spaceId;
+      if (actionName !== "open_url" && actionName !== "run") {
+        spaceId = await resolveSpaceId(request.space_id);
+        if (spaceId === void 0) {
+          return {
+            content: [{ type: "text", text: "No task space resolved. Call action=status or action=open_url first, then pass its space_id." }],
+            isError: true
+          };
+        }
+      }
       if (!await processRunning()) {
-        exec.progress.report({ stage: "launching", message: t("progress.launching") });
+        exec.progress.report({ stage: "launching", message: pickProgress(t, "launching") });
         await launchEgo();
         await new Promise((resolve) => setTimeout(resolve, 1800));
       }
+      const script = buildScript(actionName, request, spaceId);
       const timeout = Math.min(300, Math.max(1, request.timeout_seconds ?? 60)) * 1e3;
-      exec.progress.report({ stage: "browsing", message: t("progress.browsing") });
+      exec.progress.report({ stage: ACTION_STAGES[actionName], message: pickProgress(t, ACTION_STAGES[actionName] ?? "browsing") });
       try {
-        const output = await runCommand(binary, ["nodejs", "-e", request.script], timeout);
+        const output = await runCommand(binary, ["nodejs", "-e", script], timeout);
         cachedStatus = void 0;
         action.notifyUpdate();
         refreshStatus(false);
-        return { content: [{ type: "text", text: output || "Ego Browser script completed." }] };
+        if (actionName === "screenshot") {
+          const path = output.split("__EGO_SHOT__").pop()?.split("\n")[0]?.trim();
+          if (!path || !existsSync(path)) {
+            return { content: [{ type: "text", text: output || "Screenshot failed." }], isError: true };
+          }
+          const data = readFileSync(path).toString("base64");
+          return {
+            content: [
+              { type: "text", text: `Screenshot: ${path}` },
+              { type: "image", data: `data:image/png;base64,${data}`, mimeType: "image/png" }
+            ]
+          };
+        }
+        return { content: [{ type: "text", text: output || "ok" }] };
       } catch (error) {
         cachedStatus = void 0;
         action.notifyUpdate();

package/i18n/en-US.json

@@ -1,7 +1,7 @@
 {
   "name": "Ego Browser",
   "description": "Let Finch browse the web in isolated Ego Lite task spaces while you follow every page it opens.",
-  "systemPrompt": "Use ego_browser for browser automation. Call action=status to inspect Ego availability and task spaces. Call action=run with one coherent ego-browser JavaScript program for browser work. Reuse task spaces, respect user ownership, verify meaningful actions, and complete spaces when done.",
+  "systemPrompt": "Use ego_browser for browser automation with declarative actions. Call action=status first to inspect Ego and task spaces. Use open_url, snapshot, click, fill, type, press_key, scroll, screenshot, extract and close_space for everyday tasks, passing space_id from open_url/status when needed. Fall back to action=run only for advanced cases. Reuse task spaces, respect user ownership, verify meaningful actions, and complete spaces when done.",
   "composerActions": {
     "ego-browser": {
       "tooltip": "Ego Browser"
@@ -98,7 +98,14 @@
     "notInstalled": "Ego Browser is not installed"
   },
   "progress": {
-    "launching": "Launching Ego Lite…",
+    "launching": "Waking up Ego Browser…|Pouring a coffee for the browser…|Ego is stretching…",
+    "opening": "Opening a new door…|Loading the page…|Knocking on the web…",
+    "reading": "Taking a look around…|Reading the page…|Scanning the content…",
+    "acting": "Clicking gently…|Tapping the button…|Filling things in…",
+    "scrolling": "Scrolling down…|Rolling the wheel…",
+    "shooting": "Saying cheese! 📸|Freezing the moment…",
+    "closing": "Tidying up…|Closing the tab circus…|Wrapping up…",
+    "running": "Ego is doing its thing…|Browser magic in progress…",
     "browsing": "Agent is working in Ego Browser…"
   }
 }

package/i18n/zh-CN.json

@@ -1,7 +1,7 @@
 {
   "name": "Ego 浏览器",
   "description": "让 Finch 在独立的 Ego Lite 任务空间中浏览网页，你可以随时查看它打开的每个页面。",
-  "systemPrompt": "使用 ego_browser 执行浏览器自动化。先用 action=status 检查 Ego 状态和任务空间；用 action=run 执行一段完整的 Ego Browser JavaScript。复用任务空间、尊重用户控制权、验证关键操作，并在完成后关闭任务空间。",
+  "systemPrompt": "使用 ego_browser 执行浏览器自动化。先用 action=status 检查 Ego 状态和任务空间；日常操作优先用 open_url/snapshot/click/fill/type/press_key/scroll/screenshot/extract/close_space 等声明式 action，必要时传 space_id；高级场景才用 action=run 执行脚本。复用任务空间、尊重用户控制权、验证关键操作，并在完成后关闭任务空间。",
   "composerActions": {
     "ego-browser": {
       "tooltip": "Ego 浏览器"
@@ -98,7 +98,14 @@
     "notInstalled": "Ego Browser 未安装"
   },
   "progress": {
-    "launching": "正在启动 Ego Lite…",
+    "launching": "正在唤醒 Ego 浏览器…|给浏览器泡杯咖啡…|Ego 正在伸懒腰…",
+    "opening": "正在推开新世界的大门…|网页加载中…|正在敲响网络的大门…",
+    "reading": "正在环顾页面…|正在阅读页面…|正在扫描内容…",
+    "acting": "轻轻点了一下…|正在按下按钮…|正在填写…",
+    "scrolling": "正在往下滚动…|鼠标滚轮转起来了…",
+    "shooting": "咔嚓！拍照留念 📸|定格这一刻…",
+    "closing": "正在收摊…|正在收拾战场…|任务完成，整理中…",
+    "running": "Ego 正在忙活…|浏览器魔法进行中…",
     "browsing": "Agent 正在操作 Ego Browser…"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "finch-ego-lite",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Let Finch browse the web in isolated Ego Lite task spaces while you follow every page it opens.",
   "author": {
     "name": "PuterJam",
@@ -28,7 +28,7 @@
     "id": "ego-browser",
     "name": "Ego Browser",
     "description": "Control Ego Browser and see the pages your Agent is working on.",
-    "systemPrompt": "Use ego_browser for browser automation. Call action=status to inspect Ego availability and task spaces. Call action=run with one coherent ego-browser JavaScript program for browser work. Reuse task spaces, respect user ownership, verify meaningful actions, and complete spaces when done.",
+    "systemPrompt": "Use ego_browser for browser automation with declarative actions. Call action=status first to inspect Ego and task spaces. Use open_url, snapshot, click, fill, type, press_key, scroll, screenshot, extract and close_space for everyday tasks, passing space_id from open_url/status when needed. Fall back to action=run only for advanced cases. Reuse task spaces, respect user ownership, verify meaningful actions, and complete spaces when done.",
     "main": "dist/index.js",
     "activationEvents": [
       "onStartup"

package/skills/ego-browser/SKILL.md

@@ -2,50 +2,45 @@
 name: ego-browser
 description: Use Ego Browser whenever the user needs to open a website, navigate pages, click, type, upload, take screenshots, extract page data, test web apps, log in, or automate browser actions. Ego gives Agents isolated task spaces that reuse the user's login state without competing with normal browser windows.
 metadata:
-  version: "0.1.0"
+  version: "0.1.2"
 ---
 
-# Ego Browser
-
-Use the `ego_browser` Agent tool instead of Bash.
-
-## Start
-
-Call `ego_browser` with `action: "status"` when availability or current task spaces matter. For browser work call `action: "run"` with one coherent JavaScript program in `script`.
-
-All Ego helpers are preloaded in the script. Print model-visible output with `cliLog(...)`.
-
-```js
-const task = await useOrCreateTaskSpace('inspect example page')
-await openOrReuseTab('https://example.com', { wait: true, timeout: 20 })
-cliLog(await snapshotText())
-```
-
-## Main helpers
-
-- Spaces: `listTaskSpaces`, `useOrCreateTaskSpace`, `claimTaskSpace`, `handOffTaskSpace`, `takeOverTaskSpace`, `waitForAgentControl`, `completeTaskSpace`
-- Tabs: `listTabs`, `openOrReuseTab`, `closeTab`, `gotoAndWait`, `currentTab`, `switchTab`, `pageInfo`, `ensureRealTab`
-- Observe: `snapshotText`, `captureScreenshot`, `drainEvents`
-- Act: `click`, `doubleClick`, `hover`, `dragMouse`, `scrollBy`, `scroll`, `fillInput`, `typeText`, `pressKey`, `uploadFile`
-- Wait: `wait`, `waitForLoad`, `waitForElement`, `waitForNetworkIdle`
-- Advanced: `js`, `cdp`, `serverFetch`, `browserFetch`
-
-## Task-space rules
-
-Reuse the same short, goal-named task space across follow-ups. Prefer its numeric `id` after creation. Respect `ownership`:
-
-- `agent`: the Agent may act.
-- `agentDelegatedToUser`: the user controls it; stop and wait.
-- `user`: claim only after explicit user confirmation.
-
-When login, captcha, or manual confirmation is required, call `handOffTaskSpace(id)` and tell the user what to do. Call `takeOverTaskSpace(id)` only after the user explicitly says to continue.
-
-Finish in a dedicated final call with `completeTaskSpace(id, { keep: false })`. Use `keep: true` only when the user explicitly wants the live page left open or must continue manually.
-
-## Workflow
-
-1. Semantic pages: `snapshotText()` then act with `@N`, stable `loc=...`, or CSS selectors.
-2. Canvas/rich editors: screenshot, coordinates, and real keyboard input; test a tiny write first.
-3. Extraction/state: use one `js(String.raw\`(() => { ... })()\`) expression.
-
-After meaningful actions, verify with a new snapshot, `pageInfo()`, or screenshot. Refs from `snapshotText()` are valid only for the latest snapshot. Wait and timeout values are seconds unless the name ends in `Ms`.
+# Ego Browser 工具使用指南
+
+本 skill 说明如何通过 `ego_browser` 工具完成浏览器自动化。日常浏览**不需要写脚本**——工具提供声明式 action，直接传参数即可。只有高级场景（CDP、自定义 JS、复杂逻辑）才使用 `action=run`。
+
+## 使用流程
+
+1. **`action: "status"`** — 检查 Ego 是否可用、任务空间与页面。任务开始时先调一次。
+2. **`action: "open_url"`** — 打开网址：传 `url`（可选 `space_name` 给任务空间起个语义名）。返回 `spaceId`，后续操作复用它。
+3. **按需执行操作**（见下表），关键操作后验证结果。
+4. **`action: "close_space"`** — 任务完成，关闭任务空间（`space_id`）。
+
+`space_id` 规则：多数 action 接受 `space_id`；省略时若恰好只有一个 agent 空间会自动使用，否则需要先从 `status`/`open_url` 拿到。
+
+## Action 一览
+
+| action | 参数 | 说明 |
+|---|---|---|
+| status | - | 环境、任务空间、页面状态 |
+| open_url | url, space_name? | 打开网址，返回 spaceId |
+| snapshot | space_id? | 读取页面为文本（语义树） |
+| click | space_id?, selector | 按 CSS selector 点击 |
+| fill | space_id?, selector, value | 填写表单字段 |
+| type | space_id?, selector?, text | 输入文本；传 selector 先聚焦 |
+| press_key | space_id?, key | 按键：Enter/Tab/Escape… |
+| scroll | space_id?, delta_y? | 向下滚动（默认 300px） |
+| screenshot | space_id? | 截图并作为图片返回 |
+| extract | space_id?, selector? | 提取区域 innerText 或整页文本 |
+| close_space | space_id | 关闭任务空间 |
+| run | script, timeout_seconds? | 高级：执行原始 Ego 脚本 |
+
+## 规则
+
+- **复用任务空间**：同一目标的多步操作复用同一个 `space_id`，不要每次新建。
+- **尊重归属**：`ownership` 为 `agent` 时可操作；`agentDelegatedToUser` 时用户正控制，停下等待；`user` 时必须先征得用户明确同意再接管。
+- **登录/验证码/人工确认**：交给用户处理，明确告诉用户需要做什么；用户说继续后再接管。
+- **验证关键操作**：点击、提交、填表后，用 `snapshot` 或 `pageInfo` 确认结果，不要盲目继续。
+- **选择器优先**：定位元素用 CSS selector；`snapshot` 输出的语义树可帮助挑选 selector。
+- **完成后关闭**：任务结束用 `close_space`；仅当用户明确要求保留页面时留着。
+- **超时控制**：复杂操作适当调大 `timeout_seconds`（默认 60 秒）。