Open-source SEO, GEO, and marketing skills for AI agents.
feat(notfair-cmo): teach agents the workspace browser tools
Yuting Zhong06dbb31f72ff
diff --git a/notfair-cmo/src/server/skills/orchestration-skill.test.ts b/notfair-cmo/src/server/skills/orchestration-skill.test.tsindex 627d8f59..3d7c2250 100644--- a/notfair-cmo/src/server/skills/orchestration-skill.test.ts+++ b/notfair-cmo/src/server/skills/orchestration-skill.test.ts@@ -86,6 +86,43 @@ describe("ORCHESTRATION_SKILL", () => {expect(s).not.toContain("<propose_cron>");});+ it("teaches the workspace browser tool inventory", () => {+ const s = getOrchestrationSkill();+ for (const tool of [+ "browser_status",+ "browser_tabs",+ "browser_open",+ "browser_close",+ "browser_navigate",+ "browser_snapshot",+ "browser_click",+ "browser_type",+ "browser_press",+ "browser_scroll",+ "browser_back",+ "browser_shutdown",+ ]) {+ expect(s).toContain(tool);+ }+ });++ it("teaches the snapshot → act → snapshot discipline (stale refs are the #1 browser bug)", () => {+ const s = getOrchestrationSkill();+ expect(s).toMatch(/snapshot AGAIN/i);+ expect(s).toMatch(/[Ss]tale refs/);+ });++ it("teaches agents to use agent_id as their browser tab label", () => {+ const s = getOrchestrationSkill();+ expect(s).toMatch(/label.*agent_id/i);+ });++ it("teaches agents to report login/captcha/2FA as blockers via submit_task_status", () => {+ const s = getOrchestrationSkill();+ expect(s).toMatch(/captcha|2FA|login wall/i);+ expect(s).toMatch(/submit_task_status.*blocked/);+ });+it("includes a 'Your role:' section selector so role-specific content sits ABOVE", () => {// The skill should sound like a how-to manual, NOT contain role// declarations like "You are the CMO" / "You are a worker" — thosediff --git a/notfair-cmo/src/server/skills/orchestration-skill.ts b/notfair-cmo/src/server/skills/orchestration-skill.tsindex 8affb48d..3105f5a7 100644--- a/notfair-cmo/src/server/skills/orchestration-skill.ts+++ b/notfair-cmo/src/server/skills/orchestration-skill.ts@@ -90,6 +90,80 @@ recover instead of asking the user:- Terminal statuses (succeeded / failed / cancelled) are not re-writable.Once a task is closed, status calls become no-ops.+## Workspace browser tools++The workspace has a single shared Chrome instance with persistent cookies.+The user has signed in there during onboarding — so login state for Google,+Meta, Search Console, etc. is already available to you. Cookies persist+across restarts; you do not need to ask the user to sign in again.++### One labeled tab per agent++Every agent shares the same Chrome, so coordinate via tab labels.+**Always pass \`label\` equal to your \`agent_id\` when calling+\`browser_open\`.** That reserves a stable tab for your work and prevents+you (or a retry) from racing other agents.++\`\`\`+browser_open({ project_slug, label: "<your agent_id>", url: "..." })+\`\`\`++If a labeled tab already exists, \`browser_open\` reuses it (navigates+that tab instead of duplicating). Subsequent calls target it as+\`target_id: "<your agent_id>"\`.++Before opening, call \`browser_tabs\` if you suspect a prior turn left+state you can reuse — it lists every tab in the workspace with handle,+URL, and title.++### Snapshot → act → snapshot++Refs in a snapshot (\`e1\`, \`e2\`, ...) are valid ONLY until the DOM+changes. Discipline:++1. \`browser_snapshot\` to learn what's on the page (returns elements+ with stable refs + a text excerpt).+2. \`browser_click\`/\`browser_type\`/\`browser_press\` using a ref from+ that snapshot.+3. After any navigation, form submit, or modal change, snapshot AGAIN+ before the next action. Stale refs fail loudly — recover with a+ fresh snapshot, never a blind retry.++\`browser_navigate\` triggers a navigation; \`browser_scroll\` does not+invalidate refs but may reveal new ones (re-snapshot if you need them).++### Reporting blockers honestly++If the page surfaces a login wall, captcha, 2FA prompt, permission+dialog, or any state that needs the human, STOP. Do not loop. Use+\`submit_task_status\` with \`status: "blocked"\` and a summary that+quotes the exact UI ("Google asks for SMS verification on++1•••••5309"). Do not claim "not logged in" just because the current+page shows an onboarding splash — snapshot first and read the visible+UI.++Do not try to bypass interstitials by reloading or clicking around. The+user signed into this profile manually; if Google or Meta wants a+re-verification now, only the user can give it.++### Tool inventory (full list in tool descriptions)++- \`browser_status\` — is the workspace browser running, where the+ profile lives. Cheap; safe to call first.+- \`browser_tabs\` — list every tab with handle, URL, title.+- \`browser_open\` — open / reuse a tab. ALWAYS pass \`label\`.+- \`browser_close\` — close a tab by handle.+- \`browser_navigate\` — point an existing tab at a new URL.+- \`browser_snapshot\` — get refs + text. Snapshot before every action.+- \`browser_click\` — click ref. Supports right/middle/double + modifiers.+- \`browser_type\` — type into ref. \`submit: true\` presses Enter after.+- \`browser_press\` — single key / chord (Tab, Escape, Control+a, ...).+- \`browser_scroll\` — viewport scroll up/down/left/right.+- \`browser_back\` — history back.+- \`browser_shutdown\` — stop the workspace browser. Use only when the+ user explicitly asks. Cookies persist; the next \`browser_open\`+ relaunches with the same session.+## Scheduling recurring workWhen the user asks for "every day", "every Monday", "every hour", etc.,