Skip to content

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.ts
index 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" — those
diff --git a/notfair-cmo/src/server/skills/orchestration-skill.ts b/notfair-cmo/src/server/skills/orchestration-skill.ts
index 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 work
When the user asks for "every day", "every Monday", "every hour", etc.,