finch-ego-lite 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# Ego Browser for Finch
+
+Let Finch work directly on the web while you stay aware of every page the Agent opens and every task space it uses.
+
+## What you can do
+
+After enabling this mini tool, simply ask Finch to:
+
+- “Open Taobao and check the current price of a Switch game.”
+- “Research this product on Google and summarize the key findings.”
+- “Check my store orders and pause when you need my confirmation.”
+- “Fill in this web form, but let me review it before submitting.”
+
+Finch opens websites in isolated Ego Lite task spaces. You do not need to learn browser automation or copy page content into the conversation manually.
+
+## Follow the Agent’s work
+
+The Ego button beside the Composer shows the current connection status. Open its menu to:
+
+- see active task spaces and page counts;
+- view each page title and website;
+- jump directly to any page in Ego Lite;
+- tell whether the Agent is working, waiting for you, or under user control;
+- close a completed task space and all pages inside it.
+
+When a task space contains many pages, the menu shows up to six at a time and lets you scroll through the rest.
+
+## Take control when needed
+
+For sign-in, CAPTCHA, payment confirmation, or other sensitive steps, the Agent can pause and hand the task space to you. When finished, choose “Let Agent continue” and Finch will resume from the same page.
+
+Task spaces are isolated from your everyday browser windows while still being able to reuse your existing login state. The Agent does not compete with the pages you are currently using, and you can inspect or take over its workspace at any time.
+
+## Get started
+
+1. Install and launch [Ego Lite](https://lite.ego.app/) on macOS. Ego Lite is a browser designed for collaboration between people and AI Agents, and provides the web environment used by this mini tool.
+2. Enable this mini tool in Finch.
+3. Tell Finch which website to visit and what you want done.
+4. Use the Ego button beside the Composer to follow progress, open pages, or take control.
+
+> Ego Lite currently supports macOS only. On Windows or Linux, this mini tool explains that the platform is not supported and provides a link to the Ego Lite website for future updates.
+
+## About Finch
+
+[Finch](https://finchwork.app/) is a lightweight, easy-to-use desktop AI Agent. It combines conversation, memory, local files, Skills, and mini tools to turn natural-language ideas into real results.
+
+Ego Browser for Finch gives Finch observable, interruptible web access: the Agent explores and acts, while you retain the ability to inspect and confirm its work.
+
+---
+
+# Ego Browser for Finch 中文说明
+
+让 Finch 真正走进网页完成任务，同时让你随时知道 Agent 正在看什么、做什么。
+
+## 它能帮你做什么
+
+启用后，你可以直接对 Finch 说：
+
+- “打开淘宝，帮我看看 Switch 游戏现在多少钱。”
+- “去 Google 调研这个产品，把重要结论整理出来。”
+- “登录后台检查订单，有需要我确认的步骤就停下来。”
+- “打开这个网页，填写表单并在提交前让我检查。”
+
+Finch 会在 Ego Lite 的独立任务空间中打开网页。你不需要学习浏览器自动化，也不用手动复制网页内容给 Agent。
+
+## 随时看见 Agent 的工作现场
+
+输入框旁的 Ego 按钮会显示当前连接状态。展开菜单后，你可以：
+
+- 查看 Agent 正在使用的任务空间和页面数量；
+- 看到每个页面的标题与所属站点；
+- 点击任意页面，直接跳转到 Ego Lite 中查看；
+- 分辨当前由 Agent 操作、等待你操作，还是由你控制；
+- 在任务结束后关闭整个任务空间及其中的页面。
+
+页面较多时，菜单最多展示六项并支持滚动，不会占满屏幕。
+
+## 需要你操作时，控制权会交给你
+
+登录、验证码、支付确认或其他敏感步骤需要你亲自处理时，Agent 可以暂停并把任务空间交给你。完成后点击“让 Agent 继续”，Finch 会从同一个页面接着工作。
+
+任务空间与日常浏览窗口彼此独立，但可以沿用你已有的登录状态。这样 Agent 不会抢占你正在使用的浏览器页面，你也可以随时进入现场检查。
+
+## 开始使用
+
+1. 在 macOS 上安装并启动 [Ego Lite](https://lite.ego.app/)。Ego Lite 是专为人与 AI Agent 协作设计的浏览器，也是本小工具连接网页的运行环境。
+2. 在 Finch 中启用本小工具。
+3. 直接告诉 Finch 想访问的网站和要完成的事情。
+4. 通过输入框旁的 Ego 按钮查看进度、打开页面或接管操作。
+
+> Ego Lite 目前仅支持 macOS。在 Windows 或 Linux 上，本小工具会显示平台暂不支持，并提供 Ego Lite 官网入口了解后续进展。
+
+## 关于 Finch
+
+[Finch](https://finchwork.app/) 是一款轻量、易用的桌面 AI Agent。它能结合对话、记忆、本地文件、Skills 与小工具，把自然语言中的想法逐步变成真实结果。
+
+Ego Browser for Finch 为 Finch 增加了可观察、可接管的网页操作能力：Agent 负责探索和执行，你始终保留查看与确认的权利。

package/dist/index.js

@@ -0,0 +1,510 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const WEBSITE = 'https://lite.ego.app/';
+const STATUS_MARKER = '__EGO_STATUS__';
+let commandQueue = Promise.resolve();
+function egoBinary() {
+    const local = join(homedir(), '.local', 'bin', 'ego-browser');
+    if (existsSync(local))
+        return local;
+    return 'ego-browser';
+}
+async function processRunning() {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        await execFileAsync('pgrep', ['-f', '/ego lite.app/Contents/MacOS/ego lite'], { timeout: 2000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function runCommand(file, args, timeout = 20_000) {
+    const execute = () => new Promise((resolve, reject) => {
+        const child = execFile(file, args, {
+            timeout,
+            maxBuffer: 10 * 1024 * 1024,
+            env: { ...process.env, PATH: `${join(homedir(), '.local', 'bin')}:${process.env.PATH ?? ''}` },
+        }, (error, stdout, stderr) => {
+            const output = [stdout, stderr].filter(Boolean).join('\n').trim();
+            if (error) {
+                reject(new Error(output || error.message));
+                return;
+            }
+            resolve(output);
+        });
+        // ego-browser waits for stdin EOF even when a script is supplied with -e.
+        child.stdin?.end();
+    });
+    const result = commandQueue.then(execute, execute);
+    commandQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+async function installedVersion(binary) {
+    try {
+        const output = await runCommand(binary, ['--version'], 3000);
+        return output.split('\n').find((line) => line.startsWith('ego-browser '))?.replace('ego-browser ', '').trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusScript(detailed) {
+    return `
+const spaces = await listTaskSpaces();
+let initialTab = null;
+if (${detailed ? 'true' : 'false'} && spaces.some(space => space.ownership === 'agent')) {
+  initialTab = await currentTab().catch(() => null);
+}
+let initialSpaceId = null;
+const result = [];
+for (const space of spaces) {
+  const item = Object.assign({}, space);
+  if (${detailed ? 'true' : 'false'} && space.ownership === 'agent') {
+    try {
+      await switchTaskSpace(space.id);
+      item.tabs = await listTabs();
+      if (initialTab && item.tabs.some(tab => tab.targetId === initialTab.targetId)) initialSpaceId = space.id;
+    } catch (error) {
+      item.tabsError = String(error && error.message ? error.message : error);
+    }
+  }
+  result.push(item);
+}
+if (initialSpaceId !== null && initialTab) {
+  try {
+    await switchTaskSpace(initialSpaceId);
+    await switchTab(initialTab.targetId);
+  } catch (error) {}
+}
+cliLog('${STATUS_MARKER}' + JSON.stringify(result));
+`;
+}
+function parseSpaces(output) {
+    const markerIndex = output.lastIndexOf(STATUS_MARKER);
+    if (markerIndex < 0)
+        throw new Error(output || 'Ego Browser did not return status data');
+    const json = output.slice(markerIndex + STATUS_MARKER.length).split('\n')[0];
+    return JSON.parse(json);
+}
+async function getStatus(detailed = false) {
+    if (process.platform !== 'darwin') {
+        return { supported: false, installed: false, running: false, spaces: [], pageCount: 0 };
+    }
+    const binary = egoBinary();
+    if (!binary)
+        return { supported: true, installed: false, running: false, spaces: [], pageCount: 0 };
+    const version = await installedVersion(binary);
+    if (!version)
+        return { supported: true, installed: false, running: false, spaces: [], pageCount: 0 };
+    const running = await processRunning();
+    if (!running)
+        return { supported: true, installed: true, running: false, version, spaces: [], pageCount: 0 };
+    try {
+        const output = await runCommand(binary, ['nodejs', '-e', statusScript(detailed)], 10_000);
+        const spaces = parseSpaces(output);
+        const pageCount = spaces.reduce((sum, space) => {
+            if (space.tabs)
+                return sum + space.tabs.length;
+            return sum + (space.recentTabTitles?.length ?? 0);
+        }, 0);
+        return { supported: true, installed: true, running: true, version, spaces, pageCount };
+    }
+    catch (error) {
+        return {
+            supported: true,
+            installed: true,
+            running: true,
+            version,
+            spaces: [],
+            pageCount: 0,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function launchEgo() {
+    if (process.platform !== 'darwin')
+        throw new Error('Ego Lite currently supports macOS only.');
+    await execFileAsync('open', ['-a', 'ego lite'], { timeout: 5000 });
+}
+async function openWebsite() {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', WEBSITE] : [WEBSITE];
+    await execFileAsync(command, args, { timeout: 5000 });
+}
+function key(value) {
+    return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+function unkey(value) {
+    return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+}
+function compactTitle(title, fallback, maxLength = 32) {
+    const chars = Array.from(title.trim() || fallback);
+    return chars.length > maxLength ? `${chars.slice(0, maxLength).join('')}…` : chars.join('');
+}
+function domainOf(url, fallback) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.protocol}//${parsed.hostname.replace(/^www\./, '')}`;
+    }
+    catch {
+        return fallback;
+    }
+}
+function ownershipText(ownership, t) {
+    if (ownership === 'agent')
+        return t('ownership.agent');
+    if (ownership === 'agentDelegatedToUser')
+        return t('ownership.delegated');
+    return t('ownership.user');
+}
+function statusText(status, t) {
+    if (!status.supported)
+        return t('status.unsupported', { platform: process.platform });
+    if (!status.installed)
+        return t('status.notInstalled', { website: WEBSITE });
+    if (!status.running)
+        return t('status.notRunning', { version: status.version ?? 'unknown' });
+    if (status.error)
+        return t('status.error', { error: status.error });
+    const spaces = status.spaces.map((space) => ({
+        id: space.id,
+        name: space.name,
+        ownership: space.ownership,
+        pages: space.tabs?.length ?? space.recentTabTitles?.length ?? 0,
+        tabs: space.tabs?.map(({ targetId, title, url, active }) => ({ targetId, title, url, active })),
+    }));
+    return JSON.stringify({ ready: true, version: status.version, pageCount: status.pageCount, spaces }, null, 2);
+}
+export function activate(ctx) {
+    const t = (key, values) => ctx.i18n.t(key, values);
+    ctx.subscriptions.push(ctx.icons.register('ego-browser-icons', {
+        ego: {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor"><path stroke-width=".77" d="M4.78 3.634c1.066 0 2.042.38 2.803 1.012-.421.91-.668 2.099-.668 3.384s.248 2.474.669 3.384a4.396 4.396 0 1 1-2.804-7.78Zm4.938 0c.446 0 .95.367 1.367 1.19.405.8.667 1.934.667 3.206s-.262 2.406-.667 3.206c-.416.823-.92 1.19-1.367 1.19-.38 0-.803-.266-1.179-.858A5.15 5.15 0 0 0 9.944 8.03c0-1.37-.535-2.616-1.405-3.54.376-.59.799-.856 1.179-.856Zm5.05.007c.024.015.076.06.152.184.12.196.24.505.348.921.212.826.348 1.987.348 3.284s-.136 2.459-.348 3.285c-.107.415-.229.724-.348.92a.6.6 0 0 1-.151.183.6.6 0 0 1-.15-.184c-.12-.195-.242-.504-.348-.92-.213-.825-.348-1.987-.348-3.284s.135-2.458.348-3.284c.106-.416.228-.725.347-.92a.6.6 0 0 1 .15-.185Z"/></svg>',
+        },
+        'bot-off': {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13.67 8H18a2 2 0 0 1 2 2v4.33"/><path d="M2 14h2"/><path d="M20 14h2"/><path d="M22 22 2 2"/><path d="M8 8H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h12a2 2 0 0 0 1.414-.586"/><path d="M9 13v2"/><path d="M9.67 4H12v2.33"/></svg>',
+        },
+        compass: {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z"/></svg>',
+        },
+        bot: {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"/><rect width="16" height="12" x="4" y="8" rx="2"/><path d="M2 14h2"/><path d="M20 14h2"/><path d="M15 13v2"/><path d="M9 13v2"/></svg>',
+        },
+        x: {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>',
+        },
+        play: {
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 5a2 2 0 0 1 3.008-1.728l11.997 6.998a2 2 0 0 1 .003 3.458l-12 7A2 2 0 0 1 5 19z"/></svg>',
+        },
+    }));
+    let cachedStatus;
+    let refreshInFlight;
+    let pendingDetailedRefresh = false;
+    let refreshStatus = () => { };
+    const action = ctx.composerActions.register('ego-browser', {
+        async getBadge() {
+            const online = cachedStatus?.installed === true
+                && cachedStatus.running === true
+                && !cachedStatus.error;
+            if (cachedStatus?.supported === false)
+                return { text: t('badge.unsupported'), active: false };
+            return online
+                ? { text: t('badge.online'), active: true }
+                : { text: t('badge.offline'), active: false };
+        },
+        async getMenu() {
+            refreshStatus(true);
+            if (!cachedStatus) {
+                return [{
+                        id: '__checking__',
+                        label: t('menu.checking.label'),
+                        description: t('menu.checking.description'),
+                        iconName: 'timer',
+                        disabled: true,
+                    }, {
+                        id: '__install__',
+                        label: t('menu.help.label'),
+                        description: 'lite.ego.app',
+                        iconName: 'lightbulb',
+                    }];
+            }
+            const status = cachedStatus;
+            if (!status.supported) {
+                return [{
+                        id: '__unsupported__',
+                        label: t('menu.unsupported.label'),
+                        description: t('menu.unsupported.description'),
+                        hoverText: t('menu.unsupported.hover', { platform: process.platform }),
+                        iconName: 'ext:ego-browser-icons/bot-off',
+                        disabled: true,
+                    }, {
+                        id: '__unsupported_divider__',
+                        label: '',
+                        separator: true,
+                    }, {
+                        id: '__install__',
+                        label: t('menu.learn.label'),
+                        description: 'lite.ego.app',
+                        iconName: 'lightbulb',
+                    }];
+            }
+            if (!status.installed) {
+                return [{
+                        id: '__install__',
+                        label: t('menu.install.label'),
+                        description: t('menu.install.description'),
+                        hoverText: t('menu.install.hover'),
+                        iconName: 'rocket',
+                    }];
+            }
+            if (!status.running) {
+                return [{
+                        id: '__install__',
+                        label: t('menu.help.label'),
+                        description: 'lite.ego.app',
+                        iconName: 'lightbulb',
+                    }, {
+                        id: '__launch_divider__',
+                        label: '',
+                        separator: true,
+                    }, {
+                        id: '__launch__',
+                        label: t('menu.launch.label'),
+                        description: status.version,
+                        iconName: 'ext:ego-browser-icons/play',
+                    }];
+            }
+            const items = [{
+                    id: '__summary__',
+                    label: t('menu.summary.spaces', { count: status.spaces.length }),
+                    description: t('menu.summary.pages', { count: status.pageCount }),
+                    iconName: 'ext:ego-browser-icons/compass',
+                    disabled: true,
+                }, {
+                    id: '__spaces_divider__',
+                    label: '',
+                    separator: true,
+                }];
+            for (const space of status.spaces) {
+                const tabs = space.tabs ?? [];
+                const children = tabs.map((tab, index) => ({
+                    id: `tab:${key([space.id, tab.targetId])}`,
+                    label: compactTitle(tab.title, t('page.untitled')),
+                    hoverText: `${tab.title || t('page.untitled')}\n${domainOf(tab.url, t('site.unknown'))}`,
+                    current: tab.active,
+                    iconName: 'globe',
+                    group: `space-${space.id}`,
+                    groupLabel: index === 0 ? ownershipText(space.ownership, t) : undefined,
+                    groupMaxVisible: index === 0 ? 6 : undefined,
+                }));
+                if (space.ownership === 'agentDelegatedToUser') {
+                    children.push({
+                        id: `resume:${key(space.id)}`,
+                        label: t('menu.resume.label'),
+                        description: t('menu.resume.description'),
+                        iconName: 'message-circle',
+                    });
+                }
+                if (children.length === 0) {
+                    children.push({
+                        id: `space:${key(space.id)}`,
+                        label: ownershipText(space.ownership, t),
+                        description: t('menu.summary.pages', { count: space.recentTabTitles?.length ?? 0 }),
+                        iconName: space.ownership === 'agent' ? 'bot' : 'users',
+                        disabled: true,
+                    });
+                }
+                children.push({ id: `close-divider:${space.id}`, label: '', separator: true });
+                children.push({
+                    id: `close:${key(space.id)}`,
+                    label: t('menu.close.label'),
+                    description: t('menu.close.description'),
+                    iconName: 'ext:ego-browser-icons/x',
+                });
+                items.push({
+                    id: `space-menu:${space.id}`,
+                    label: space.name || t('menu.space.fallback', { id: space.id }),
+                    description: ownershipText(space.ownership, t),
+                    iconName: space.ownership === 'agent'
+                        ? 'ext:ego-browser-icons/bot'
+                        : 'ext:ego-browser-icons/compass',
+                    children,
+                });
+            }
+            if (status.spaces.length === 0) {
+                items.push({
+                    id: '__empty__',
+                    label: t('menu.empty.label'),
+                    description: t('menu.empty.description'),
+                    hoverText: t('menu.empty.hover'),
+                    iconName: 'ext:ego-browser-icons/bot-off',
+                });
+            }
+            return items;
+        },
+        async execute(_actionContext, itemId, actions) {
+            try {
+                if (itemId === '__install__') {
+                    await openWebsite();
+                    return;
+                }
+                if (itemId === '__empty__') {
+                    await actions.composer.fill(t('composer.startPrompt'));
+                    return;
+                }
+                if (itemId === '__launch__') {
+                    await launchEgo();
+                    await ctx.ui.showToast({ title: t('toast.launched'), variant: 'success', position: 'TC' });
+                    cachedStatus = undefined;
+                    action.notifyUpdate();
+                    refreshStatus(true);
+                    return;
+                }
+                if (itemId.startsWith('resume:')) {
+                    const spaceId = unkey(itemId.slice('resume:'.length));
+                    await actions.composer.fill(t('composer.resumePrompt', { id: spaceId }));
+                    return;
+                }
+                if (itemId.startsWith('close:')) {
+                    const spaceId = unkey(itemId.slice('close:'.length));
+                    const space = cachedStatus?.spaces.find((item) => item.id === spaceId);
+                    const result = await ctx.ui.showConfirmDialog({
+                        title: t('dialog.close.title'),
+                        description: space?.name || t('menu.space.fallback', { id: spaceId }),
+                        message: t('dialog.close.message', { count: space?.tabs?.length ?? space?.recentTabTitles?.length ?? 0 }),
+                        confirmLabel: t('dialog.close.confirm'),
+                        cancelLabel: t('dialog.close.cancel'),
+                        variant: 'danger',
+                    });
+                    if (!result.confirmed)
+                        return;
+                    const binary = egoBinary();
+                    if (!binary || !(await installedVersion(binary)))
+                        throw new Error(t('error.notInstalled'));
+                    const script = `const result = await completeTaskSpace(${JSON.stringify(spaceId)}, { keep: false }); cliLog(JSON.stringify(result));`;
+                    await runCommand(binary, ['nodejs', '-e', script], 15_000);
+                    cachedStatus = undefined;
+                    action.notifyUpdate();
+                    refreshStatus(true);
+                    await ctx.ui.showToast({ title: t('toast.closed'), variant: 'success', position: 'TC' });
+                    return;
+                }
+                if (itemId.startsWith('tab:')) {
+                    const [spaceId, targetId] = unkey(itemId.slice('tab:'.length));
+                    await launchEgo();
+                    const binary = egoBinary();
+                    const script = `await switchTaskSpace(${JSON.stringify(spaceId)}); await switchTab(${JSON.stringify(targetId)}); cliLog('ok');`;
+                    await runCommand(binary, ['nodejs', '-e', script], 10_000);
+                }
+            }
+            catch (error) {
+                ctx.logger.error('Ego Composer action failed', error);
+                await ctx.ui.showToast({
+                    title: t('toast.actionFailed'),
+                    description: error instanceof Error ? error.message : String(error),
+                    variant: 'error',
+                    position: 'TC',
+                });
+            }
+        },
+    });
+    ctx.subscriptions.push(action);
+    ctx.subscriptions.push(ctx.i18n.onDidChangeLocale(() => action.notifyUpdate()));
+    ctx.subscriptions.push(ctx.tools.register({
+        name: 'ego_browser',
+        title: 'Ego Browser',
+        description: `Operate Ego Browser through its preloaded JavaScript helpers.
+action:
+  status — check installation, runtime, task-space ownership, and open pages
+  run    — 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.`,
+        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.' },
+            },
+            required: ['action'],
+        },
+        risk: 'high',
+        defaultEnabled: true,
+        async execute(input, exec) {
+            const request = input;
+            if (request.action === '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 (request.script.length > 100_000 || request.script.includes('\0')) {
+                return { content: [{ type: 'text', text: 'The Ego Browser script is invalid or too large.' }], isError: true };
+            }
+            if (process.platform !== 'darwin') {
+                return { content: [{ type: 'text', text: t('status.unsupported', { platform: process.platform }) }], isError: true };
+            }
+            const binary = egoBinary();
+            const version = binary ? await installedVersion(binary) : undefined;
+            if (!binary || !version) {
+                return {
+                    content: [{ type: 'text', text: `Ego Lite is not installed. Install it from ${WEBSITE}, finish onboarding, then retry.` }],
+                    isError: true,
+                };
+            }
+            if (!(await processRunning())) {
+                exec.progress.report({ stage: 'launching', message: t('progress.launching') });
+                await launchEgo();
+                await new Promise((resolve) => setTimeout(resolve, 1800));
+            }
+            const timeout = Math.min(300, Math.max(1, request.timeout_seconds ?? 60)) * 1000;
+            exec.progress.report({ stage: 'browsing', message: t('progress.browsing') });
+            try {
+                const output = await runCommand(binary, ['nodejs', '-e', request.script], timeout);
+                cachedStatus = undefined;
+                action.notifyUpdate();
+                refreshStatus(false);
+                return { content: [{ type: 'text', text: output || 'Ego Browser script completed.' }] };
+            }
+            catch (error) {
+                cachedStatus = undefined;
+                action.notifyUpdate();
+                refreshStatus(false);
+                const message = error instanceof Error ? error.message : String(error);
+                return { content: [{ type: 'text', text: message }], isError: true };
+            }
+        },
+    }));
+    refreshStatus = (detailed = false) => {
+        if (refreshInFlight) {
+            pendingDetailedRefresh ||= detailed;
+            return;
+        }
+        refreshInFlight = getStatus(detailed)
+            .then((status) => {
+            cachedStatus = status;
+            action.notifyUpdate();
+        })
+            .catch((error) => ctx.logger.warn('Ego background status refresh failed', error))
+            .finally(() => {
+            refreshInFlight = undefined;
+            if (pendingDetailedRefresh) {
+                pendingDetailedRefresh = false;
+                refreshStatus(true);
+            }
+        });
+    };
+    refreshStatus(true);
+    const timer = setInterval(() => refreshStatus(true), 10_000);
+    ctx.subscriptions.push({ dispose: () => clearInterval(timer) });
+    ctx.logger.info('ego-browser mini tool activated', { cached: Boolean(cachedStatus) });
+}
+export function deactivate() { }

package/i18n/en-US.json

@@ -0,0 +1,104 @@
+{
+  "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.",
+  "composerActions": {
+    "ego-browser": {
+      "tooltip": "Ego Browser"
+    }
+  },
+  "toolMeta": {
+    "name": "Ego Browser"
+  },
+  "badge": {
+    "online": "Ego online",
+    "offline": "Ego offline",
+    "unsupported": "macOS only"
+  },
+  "menu": {
+    "checking": {
+      "label": "Checking Ego status…",
+      "description": "Updates automatically"
+    },
+    "help": {
+      "label": "Install and help"
+    },
+    "learn": {
+      "label": "Learn about Ego Lite"
+    },
+    "unsupported": {
+      "label": "Ego Lite requires macOS",
+      "description": "This device is not supported",
+      "hover": "Ego Lite currently runs on macOS only. Current platform: {platform}."
+    },
+    "install": {
+      "label": "Install Ego Lite",
+      "description": "Open official website",
+      "hover": "Finish first-time setup after installation so Ego can register the ego-browser command."
+    },
+    "launch": {
+      "label": "Launch Ego Lite"
+    },
+    "summary": {
+      "spaces": "{count} task spaces",
+      "pages": "{count} pages"
+    },
+    "resume": {
+      "label": "Let Agent continue when done",
+      "description": "Insert a continue message"
+    },
+    "close": {
+      "label": "Close task space",
+      "description": "Close every page inside"
+    },
+    "space": {
+      "fallback": "Task space {id}"
+    },
+    "empty": {
+      "label": "Agent is taking a break",
+      "description": "Click to start a browsing task",
+      "hover": "Tell Agent which website to visit and what you want done."
+    }
+  },
+  "page": {
+    "untitled": "Untitled page"
+  },
+  "site": {
+    "unknown": "Unknown site"
+  },
+  "ownership": {
+    "agent": "Agent working",
+    "delegated": "Waiting for you",
+    "user": "User control"
+  },
+  "status": {
+    "unsupported": "Ego Lite currently supports macOS only. Current platform: {platform}.",
+    "notInstalled": "Ego Lite is not installed. Install it from {website} and finish first-time setup.",
+    "notRunning": "Ego Lite {version} is installed but not running.",
+    "error": "Ego Lite is running, but its status could not be read: {error}"
+  },
+  "composer": {
+    "startPrompt": "Please use Ego Browser to visit: ",
+    "resumePrompt": "I finished the manual steps in Ego task space {id}. Please continue."
+  },
+  "toast": {
+    "launched": "Ego Lite launched",
+    "closed": "Task space closed",
+    "actionFailed": "Could not open the Ego page"
+  },
+  "dialog": {
+    "close": {
+      "title": "Close this Ego task space?",
+      "message": "This will close all {count} pages inside.",
+      "confirm": "Close",
+      "cancel": "Cancel"
+    }
+  },
+  "error": {
+    "notInstalled": "Ego Browser is not installed"
+  },
+  "progress": {
+    "launching": "Launching Ego Lite…",
+    "browsing": "Agent is working in Ego Browser…"
+  }
+}

package/i18n/zh-CN.json

@@ -0,0 +1,104 @@
+{
+  "name": "Ego 浏览器",
+  "description": "让 Finch 在独立的 Ego Lite 任务空间中浏览网页，你可以随时查看它打开的每个页面。",
+  "systemPrompt": "使用 ego_browser 执行浏览器自动化。先用 action=status 检查 Ego 状态和任务空间；用 action=run 执行一段完整的 Ego Browser JavaScript。复用任务空间、尊重用户控制权、验证关键操作，并在完成后关闭任务空间。",
+  "composerActions": {
+    "ego-browser": {
+      "tooltip": "Ego 浏览器"
+    }
+  },
+  "toolMeta": {
+    "name": "Ego 浏览器"
+  },
+  "badge": {
+    "online": "Ego 在线",
+    "offline": "Ego 离线",
+    "unsupported": "仅支持 macOS"
+  },
+  "menu": {
+    "checking": {
+      "label": "正在检查 Ego 状态…",
+      "description": "完成后自动更新"
+    },
+    "help": {
+      "label": "安装与帮助"
+    },
+    "learn": {
+      "label": "了解 Ego Lite"
+    },
+    "unsupported": {
+      "label": "Ego Lite 仅支持 macOS",
+      "description": "当前设备暂不可用",
+      "hover": "Ego Lite 目前只能在 macOS 上运行。当前平台：{platform}。"
+    },
+    "install": {
+      "label": "安装 Ego Lite",
+      "description": "打开官方网站",
+      "hover": "安装后完成首次引导，Ego 会注册 ego-browser 命令。"
+    },
+    "launch": {
+      "label": "启动 Ego Lite"
+    },
+    "summary": {
+      "spaces": "{count} 个任务空间",
+      "pages": "{count} 个页面"
+    },
+    "resume": {
+      "label": "完成后让 Agent 继续",
+      "description": "插入继续指令"
+    },
+    "close": {
+      "label": "关闭任务空间",
+      "description": "关闭其中全部页面"
+    },
+    "space": {
+      "fallback": "任务空间 {id}"
+    },
+    "empty": {
+      "label": "Agent 在休息中",
+      "description": "点击发起浏览任务",
+      "hover": "告诉 Agent 想访问的网站和要完成的事情。"
+    }
+  },
+  "page": {
+    "untitled": "未命名页面"
+  },
+  "site": {
+    "unknown": "未知站点"
+  },
+  "ownership": {
+    "agent": "Agent 操作中",
+    "delegated": "等待你操作",
+    "user": "用户控制"
+  },
+  "status": {
+    "unsupported": "Ego Lite 目前仅支持 macOS。当前平台：{platform}。",
+    "notInstalled": "Ego Lite 未安装。请从 {website} 安装并完成首次引导。",
+    "notRunning": "Ego Lite 已安装（{version}），当前未运行。",
+    "error": "Ego Lite 正在运行，但状态读取失败：{error}"
+  },
+  "composer": {
+    "startPrompt": "请使用 Ego 浏览器帮我访问：",
+    "resumePrompt": "我已完成 Ego 任务空间 {id} 中的手动操作，请继续。"
+  },
+  "toast": {
+    "launched": "Ego Lite 已启动",
+    "closed": "任务空间已关闭",
+    "actionFailed": "无法打开 Ego 页面"
+  },
+  "dialog": {
+    "close": {
+      "title": "关闭 Ego 任务空间？",
+      "message": "将关闭其中 {count} 个页面。",
+      "confirm": "关闭",
+      "cancel": "取消"
+    }
+  },
+  "error": {
+    "notInstalled": "Ego Browser 未安装"
+  },
+  "progress": {
+    "launching": "正在启动 Ego Lite…",
+    "browsing": "Agent 正在操作 Ego Browser…"
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "finch-ego-lite",
+  "version": "0.1.0",
+  "description": "Let Finch browse the web in isolated Ego Lite task spaces while you follow every page it opens.",
+  "author": {
+    "name": "Puter Jam",
+    "url": "https://github.com/puterjam"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/puterjam/finch-tools.git",
+    "directory": "finch-ego-lite"
+  },
+  "homepage": "https://github.com/puterjam/finch-tools/tree/main/finch-ego-lite#readme",
+  "bugs": {
+    "url": "https://github.com/puterjam/finch-tools/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npx @finchtoys/minitools doctor ."
+  },
+  "finch": {
+    "manifestVersion": 1,
+    "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.",
+    "main": "dist/index.js",
+    "activationEvents": ["onStartup"],
+    "miniToolType": "local",
+    "categories": ["productivity", "developer"],
+    "contributes": {
+      "tools": true,
+      "composerActions": [
+        {
+          "id": "ego-browser",
+          "icon": "ext:ego-browser-icons/ego",
+          "tooltip": "Ego Browser"
+        }
+      ],
+      "iconPacks": [
+        {
+          "id": "ego-browser-icons",
+          "label": "Ego Browser Icons"
+        }
+      ],
+      "skills": true
+    },
+    "permissions": {
+      "filesystem": "none",
+      "network": false,
+      "shell": true
+    }
+  },
+  "devDependencies": {
+    "@finchtoys/minitool-api": "^0.2.9",
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "files": ["dist/", "i18n/", "skills/", "icon.png", "README.md"]
+}

package/skills/ego-browser/SKILL.md

@@ -0,0 +1,51 @@
+---
+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"
+---
+
+# 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`.