@causyne/agent 1.10.13 → 1.10.18

package/src/taskShape.ts

@@ -0,0 +1,259 @@
+import type {
+  TaskPackScore,
+  TaskPhase,
+  TaskShape,
+  WorkspaceContext
+} from './types/contracts.js';
+
+interface SignalSet {
+  strong: string[];
+  weak: string[];
+}
+
+interface ArchetypeDefinition {
+  label: string;
+  match: SignalSet;
+  phases: TaskPhase[];
+}
+
+const PACK_SIGNALS: Record<string, SignalSet> = {
+  game: {
+    strong: ['game', 'gamedev', 'permainan', 'godot', 'unity', 'unreal', 'rpg', 'platformer', 'roguelike', 'arcade', 'voxel', 'minecraft', 'tilemap', 'spritesheet', 'boss fight', 'level design'],
+    weak: ['sprite', 'player', 'enemy', 'quest', 'npc', 'gameplay', 'multiplayer', 'leaderboard']
+  },
+  web: {
+    strong: ['web app', 'webapp', 'website', 'situs', 'landing page', 'homepage', 'frontend', 'front-end', 'dashboard', 'portfolio', 'react', 'vue', 'svelte', 'angular', 'nextjs', 'next.js', 'nuxt', 'astro', 'tailwind', 'html', 'css'],
+    weak: ['web', 'ui', 'ux', 'page', 'halaman', 'responsive', 'browser', 'dom', 'component', 'layout', 'design', 'desain', 'tampilan']
+  },
+  media: {
+    strong: ['generate image', 'generate video', 'generate music', 'text to speech', 'voiceover', 'blender', 'davinci', 'resolve', 'render', '3d model', 'animation', 'animasi'],
+    weak: ['image', 'gambar', 'photo', 'foto', 'video', 'audio', 'sound', 'suara', 'music', 'musik', 'lagu', 'thumbnail', 'poster', 'logo', 'illustration']
+  },
+  system: {
+    strong: ['kill process', 'port', 'zip', 'unzip', 'tar', 'archive', 'clipboard', 'printer', 'print', 'cetak'],
+    weak: ['process', 'proses', 'compress', 'extract', 'ekstrak', 'open app', 'launch']
+  },
+  advanced: {
+    strong: ['pdf', 'forge a tool', 'custom tool', 'plugin', 'plugins', 'custom plugin', 'subagent', 'sub-agent', 'parallel agent'],
+    weak: ['symbols', 'ast', 'refactor', 'orchestrate', 'swarm']
+  }
+};
+
+const STRONG_WEIGHT = 3;
+const WEAK_WEIGHT = 1;
+const PACK_THRESHOLD = 3;
+
+// ---------------------------------------------------------------------------
+// Task archetypes. Each one carries the phase plan the agent should follow and
+// the tools that matter in each phase.
+// ---------------------------------------------------------------------------
+
+const ARCHETYPES: Record<string, ArchetypeDefinition> = {
+  integrate: {
+    label: 'Build an application that integrates live external data',
+    match: {
+      strong: ['realtime', 'real-time', 'real time', 'api', 'rest', 'webhook', 'integration', 'integrasi', 'sync', 'sinkron', 'automation', 'automasi', 'otomasi', 'automate', 'otomatis', 'booking', 'tiket', 'ticket', 'calendar', 'kalender', 'jadwal', 'schedule', 'payment', 'pembayaran'],
+      weak: ['live', 'stream', 'fetch', 'data', 'third party', 'oauth', 'token']
+    },
+    phases: [
+      { name: 'Research the data sources FIRST', tools: ['web_search', 'web_fetch'], note: 'Identify the exact official REST APIs, their auth model, rate limits and response shape before writing any code. Prefer documented JSON APIs over browser scraping — reading JSON always beats reading DOM.' },
+      { name: 'Verify access and versions', tools: ['sysRun', 'web_fetch'], note: 'Probe one real endpoint and check current package versions with `npm view <pkg> version` before pinning anything. Never assume a version from memory.' },
+      { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create the project structure and dependency manifest.' },
+      { name: 'Implement', tools: ['fs_read', 'fs_edit', 'MultiEdit'], note: 'Build the integration layer first, the UI second. Handle auth failures and rate limits explicitly.' },
+      { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Run the build, lint and type-check. Exercise the live data path end to end, not just the happy path.' }
+    ]
+  },
+  build_app: {
+    label: 'Build a new application from scratch',
+    match: {
+      strong: ['build me', 'buatkan', 'buat aku', 'create a', 'make me', 'bikin', 'develop a', 'new app', 'from scratch'],
+      weak: ['app', 'aplikasi', 'project', 'proyek', 'tool', 'system', 'sistem']
+    },
+    phases: [
+      { name: 'Plan', tools: ['update_plan'], note: 'Create a visible atomic implementation plan before touching the filesystem.' },
+      { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create structure and install dependencies at verified current versions.' },
+      { name: 'Implement', tools: ['fs_write', 'fs_edit', 'MultiEdit'], note: 'Write runnable code with every import and dependency present.' },
+      { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Build, lint and run it. Never assume code works.' }
+    ]
+  },
+  debug: {
+    label: 'Diagnose and fix a defect in existing code',
+    match: {
+      strong: ['bug', 'error', 'crash', 'fix', 'perbaiki', 'benerin', 'broken', 'rusak', 'not working', 'gagal', 'failing', 'exception', 'stack trace', 'regression'],
+      weak: ['issue', 'masalah', 'problem', 'wrong', 'salah', 'debug']
+    },
+    phases: [
+      { name: 'Reproduce', tools: ['sysRun', 'fs_read'], note: 'Reproduce the failure and capture the exact error before changing anything.' },
+      { name: 'Locate', tools: ['code_search_ripgrep', 'codebase_search', 'fs_read'], note: 'Search several phrasings in parallel. Read the file before patching it.' },
+      { name: 'Fix', tools: ['fs_edit', 'MultiEdit'], note: 'Make the smallest correct change. Do not touch unrelated code.' },
+      { name: 'Verify', tools: ['sysRun', 'code_verify_syntax'], note: 'Confirm the original reproduction now passes.' }
+    ]
+  },
+  research: {
+    label: 'Investigate and report, without changing the system',
+    match: {
+      strong: ['explain', 'jelaskan', 'analyse', 'analyze', 'analisa', 'research', 'riset', 'compare', 'bandingkan', 'what is', 'apa itu', 'how does', 'bagaimana', 'review', 'audit'],
+      weak: ['understand', 'pahami', 'find out', 'cari tahu', 'summarize', 'ringkas']
+    },
+    phases: [
+      { name: 'Gather', tools: ['code_search_ripgrep', 'fs_read', 'web_search', 'web_fetch'], note: 'Search broadly with several phrasings in parallel before concluding.' },
+      { name: 'Report', tools: [], note: 'Answer concisely and cite exact file paths or URLs. Do not modify anything unless asked.' }
+    ]
+  },
+  maintain: {
+    label: 'Operate on files, processes or the machine itself',
+    match: {
+      strong: ['organize', 'rapikan', 'clean up', 'bersihkan', 'rename', 'ganti nama', 'move', 'pindahkan', 'backup', 'cadangkan', 'delete', 'hapus', 'install', 'deploy', 'commit', 'merge'],
+      weak: ['folder', 'directory', 'file', 'berkas', 'desktop', 'downloads']
+    },
+    phases: [
+      { name: 'Survey', tools: ['fs_list', 'fs_find'], note: 'List and count what you are about to touch, and report it, before acting.' },
+      { name: 'Act', tools: ['fs_move', 'fs_write', 'sysRun'], note: 'Prefer reversible operations. Flag anything destructive for approval.' },
+      { name: 'Confirm', tools: ['fs_list'], note: 'Verify the end state matches what the user asked for.' }
+    ]
+  }
+};
+
+const ARCHETYPE_NAMES = Object.keys(ARCHETYPES);
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+function scoreSignals(text: string, signals: SignalSet): { score: number; hits: string[] } {
+  let score = 0;
+  const hits: string[] = [];
+
+  for (const term of signals.strong || []) {
+    if (text.includes(term)) {
+      score += STRONG_WEIGHT;
+      hits.push(term);
+    }
+  }
+  for (const term of signals.weak || []) {
+    // Word-boundary check for short weak terms so 'ui' cannot match 'build'
+    // and 'race' cannot match 'trace' — the exact class of false positive that
+    // used to drag ordinary tasks into game and web enforcement.
+    const pattern = new RegExp(`(^|[^a-z0-9])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z0-9])`, 'i');
+    if (pattern.test(text)) {
+      score += WEAK_WEIGHT;
+      hits.push(term);
+    }
+  }
+
+  return { score, hits };
+}
+
+/**
+ * Analyse a request into the shape of the work it implies.
+ *
+ */
+export function analyzeTask(prompt: string, workspaceContext: WorkspaceContext | null = null): TaskShape {
+  const text = String(prompt || '').toLowerCase();
+
+  // Which capability packs are worth their token cost for this request.
+  const packScores: TaskPackScore[] = [];
+  for (const packName of Object.keys(PACK_SIGNALS)) {
+    const signals = PACK_SIGNALS[packName];
+    if (!signals) continue;
+    const { score } = scoreSignals(text, signals);
+    if (score >= PACK_THRESHOLD) {
+      packScores.push({ name: packName, score });
+    }
+  }
+
+  // Workspace evidence outranks keywords: a Godot project on disk is far more
+  // reliable than any phrasing in the prompt.
+  if (workspaceContext) {
+    const signals = [
+      workspaceContext.framework,
+      workspaceContext.projectType,
+      workspaceContext.designSystem,
+      Array.isArray(workspaceContext.keyFiles) ? workspaceContext.keyFiles.join(' ') : ''
+    ].filter(Boolean).join(' ').toLowerCase();
+
+    const bump = (name: string, amount: number): void => {
+      const existing = packScores.find(p => p.name === name);
+      if (existing) existing.score += amount;
+      else packScores.push({ name, score: amount });
+    };
+
+    if (/godot|project\.godot|unity|\.tscn/.test(signals)) bump('game', 5);
+    if (/react|vue|svelte|next|nuxt|astro|angular|tailwind|vite|index\.html/.test(signals)) bump('web', 4);
+  }
+
+  packScores.sort((a, b) => b.score - a.score);
+
+  // Which archetype the work follows.
+  let bestArchetype: string | null = null;
+  let bestScore = 0;
+  for (const name of ARCHETYPE_NAMES) {
+    const definition = ARCHETYPES[name];
+    if (!definition) continue;
+    const { score } = scoreSignals(text, definition.match);
+    if (score > bestScore) {
+      bestScore = score;
+      bestArchetype = name;
+    }
+  }
+
+  // A build request that also talks about live external data is an integration
+  // job first and a build job second — that ordering is what stops the agent
+  // scaffolding a UI before it knows whether the API even exists.
+  const integrate = ARCHETYPES.integrate;
+  if (!integrate) throw new Error('integrate task archetype is unavailable');
+  const integrationScore = scoreSignals(text, integrate.match).score;
+  if (integrationScore >= STRONG_WEIGHT && bestArchetype === 'build_app') {
+    bestArchetype = 'integrate';
+    bestScore = integrationScore;
+  }
+
+  const archetype = bestArchetype || 'build_app';
+  const confidence = bestScore >= 6 ? 'high' : (bestScore >= 3 ? 'medium' : 'low');
+
+  const definition = ARCHETYPES[archetype];
+  if (!definition) throw new Error(`task archetype ${archetype} is unavailable`);
+  return {
+    archetype,
+    archetypeLabel: definition.label,
+    packs: packScores,
+    phases: definition.phases,
+    confidence
+  };
+}
+
+/**
+ * Render the analysis as a compact brief for the system prompt.
+ *
+ * This is the piece that turns "here are 28 tools" into "here is the order to
+ * use them in". It costs roughly 150-200 tokens and routinely saves whole
+ * exploratory steps, each of which costs thousands.
+ */
+export function buildTaskBrief(
+  shape: TaskShape | null | undefined,
+  availableToolNames: readonly string[] | null | undefined
+): string {
+  if (!shape) return '';
+
+  const available = new Set(availableToolNames || []);
+  const lines: string[] = [];
+
+  lines.push('# TASK SHAPE (analysed from your request)');
+  lines.push(`Work type: ${shape.archetypeLabel}.`);
+  lines.push('Follow this sequence. Do not skip ahead — each phase de-risks the next.');
+
+  shape.phases.forEach((phase, index) => {
+    const tools = (phase.tools || []).filter(name => available.has(name));
+    const toolList = tools.length > 0 ? ` [${tools.join(', ')}]` : '';
+    lines.push(`${index + 1}. ${phase.name}${toolList} — ${phase.note}`);
+  });
+
+  lines.push('Tools outside this list remain fully available; search for them with tool_search when a phase genuinely needs one.');
+
+  return lines.join('\n');
+}
+
+/** Pack names above threshold, highest score first. */
+export function packsFromShape(shape: TaskShape | null | undefined): string[] {
+  return shape && Array.isArray(shape.packs) ? shape.packs.map(p => p.name) : [];
+}

package/src/toolPacks.js

@@ -36,8 +36,8 @@ export const CORE_TOOLS = [
   'code_verify_syntax',
   'web_search',
   'web_fetch',
-  'TodoWrite',
   'update_plan',
+  'request_decision',
   'memory_write',
   'fs_read_skill',
   'skill_create',
@@ -130,9 +130,11 @@ export const PACK_NAMES = Object.keys(PACKS);
  *
  * WHAT IS IN, AND WHY EXACTLY THESE: read, write, edit, list and search cover
  * every file operation a first turn can need; `sysRun` is the escape hatch that
- * can reach anything the other seven cannot; `TodoWrite` is how a multi-step
- * task announces its plan on step one; `tool_search` is the door to the other
- * 62. With this set the agent is never stuck — worst case it spends one call
+ * can reach anything the other resident tools cannot; `update_plan` is how a
+ * multi-step task announces its plan on step one; `tool_search` is the door to
+ * deferred tools. `request_decision` is injected on the first turn only when
+ * task policy detects an unresolved durable choice. With this set the agent is
+ * never stuck — worst case it spends one call
  * discovering the tool it wants, and the tool it discovers stays loaded for the
  * rest of the task.
  *
@@ -147,7 +149,7 @@ export const RESIDENT_TOOLS = [
   'fs_list',
   'fs_search',
   'sysRun',
-  'TodoWrite',
+  'update_plan',
   'tool_search'
 ];
 

package/src/tools/browserAutomator.js

@@ -1,252 +1,56 @@
-import os from 'os';
-import fs from 'fs';
-import path from 'path';
-import { ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
-import { causyneHome } from '../utils/paths.js';
-
-function getChromeExecutablePath() {
-  const platform = os.platform();
-  if (platform === 'win32') {
-    return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
-  } else if (platform === 'darwin') {
-    return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
-  } else {
-    return '/usr/bin/google-chrome';
-  }
-}
-
-function getChromeUserDataDir() {
-  const platform = os.platform();
-  const home = os.homedir();
-  if (platform === 'win32') {
-    return `${home}\\AppData\\Local\\Google\\Chrome\\User Data`;
-  } else if (platform === 'darwin') {
-    return `${home}/Library/Application Support/Google/Chrome`;
-  } else {
-    return `${home}/.config/google-chrome`;
-  }
-}
-
-let activeBrowser = null;
-let activePage = null;
-
+import { BrowserCapabilityError, causyneBrowser } from '../browser/causyneBrowser.js';
 export const browserAct = {
-  schema: {
-    name: 'browser.act',
-    description: 'Automate Google Chrome using local profile to scrape sites or perform actions. IMPORTANT: First use "scrape" to get the page mapped to numerical indices. Then use "clickIndex" or "typeIndex" for flawless precision. Defaults to ~/.causyne/chrome_profile to protect your personal accounts from logout.',
-    parameters: {
-      type: 'object',
-      properties: {
-        usePersonalProfile: {
-          type: 'boolean',
-          description: 'Set to true ONLY if you explicitly want to use your personal Google Chrome profile. Defaults to false (uses safe dedicated profile ~/.causyne/chrome_profile).'
-        },
-        profileDirectory: {
-          type: 'string',
-          description: 'Specific profile sub-folder when usePersonalProfile is true (e.g. "Profile 1", "Default", "Profile 2").'
-        },
-        actions: {
-          type: 'array',
-          description: 'List of actions to perform in order',
-          items: {
+    schema: {
+        name: 'browser.act',
+        description: 'Use the dedicated Causyne Browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
+        parameters: {
             type: 'object',
             properties: {
-              type: { type: 'string', enum: ['goto', 'click', 'type', 'clickIndex', 'typeIndex', 'waitFor', 'scrape', 'selectOption', 'keyPress', 'scroll'] },
-              url: { type: 'string' },
-              selector: { type: 'string', description: 'CSS selector (legacy)' },
-              index: { type: 'number', description: 'Element index from the scrape map' },
-              text: { type: 'string' },
-              value: { type: 'string', description: 'Option value to select in dropdowns' },
-              key: { type: 'string', description: 'Key to press (Enter, Tab, ArrowDown, etc.)' },
-              humanDelayMs: { type: 'number', description: 'Keystroke delay in ms for natural human-like typing (default 45ms)' },
-              timeoutMs: { type: 'number' }
+                actions: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 40,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['newTab', 'switchTab', 'listTabs', 'closeTab', 'search', 'goto', 'snapshot', 'scrape', 'click', 'clickIndex', 'type', 'typeIndex', 'selectOption', 'keyPress', 'scroll', 'back', 'forward', 'reload', 'extract', 'download', 'screenshot']
+                            },
+                            tabId: { type: 'string', description: 'Tab id returned by newTab or listTabs.' },
+                            url: { type: 'string', description: 'Public http(s) URL for goto or newTab.' },
+                            query: { type: 'string', description: 'Search query.' },
+                            ref: { type: 'string', description: 'Current accessibility ref, for example e12.' },
+                            index: { type: 'number', description: 'Legacy numeric form of an accessibility ref.' },
+                            selector: { type: 'string', description: 'CSS selector when a current accessibility ref is unavailable.' },
+                            text: { type: 'string' },
+                            value: { type: 'string' },
+                            key: { type: 'string' },
+                            direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+                            amount: { type: 'number' },
+                            offset: { type: 'number', description: 'Character offset for a paged accessibility snapshot.' },
+                            outputFile: { type: 'string', description: 'Download or screenshot destination inside the selected workspace.' },
+                            fullPage: { type: 'boolean', description: 'Capture the complete page for a screenshot instead of the visible viewport.' }
+                        },
+                        required: ['type'],
+                        additionalProperties: false
+                    }
+                }
             },
-            required: ['type']
-          }
+            required: ['actions'],
+            additionalProperties: false
         }
-      },
-      required: ['actions']
-    }
-  },
-  async execute(args) {
-    const vision = await ensureCapability('vision');
-    if (!vision.ok) return { success: false, error: vision.reason, requiresConsent: vision.requiresConsent };
-    const puppeteer = await loadCapabilityPackage('puppeteer-core');
-
-    let results = [];
-
-    try {
-      if (!activeBrowser || !activeBrowser.isConnected()) {
-        const executablePath = getChromeExecutablePath();
-        const primaryUserDataDir = getChromeUserDataDir();
-        let connectedOrLaunched = false;
-        
-        // Layer 1: Attempt connection to active Chrome Remote Debugging port (9222) for zero-interruption live session reuse
+    },
+    async execute(args) {
         try {
-          const controller = new AbortController();
-          const timeoutId = setTimeout(() => controller.abort(), 600);
-          const resp = await fetch('http://127.0.0.1:9222/json/version', { signal: controller.signal });
-          clearTimeout(timeoutId);
-          if (resp.ok) {
-            const data = await resp.json();
-            if (data.webSocketDebuggerUrl) {
-              activeBrowser = await puppeteer.connect({
-                browserWSEndpoint: data.webSocketDebuggerUrl,
-                defaultViewport: null
-              });
-              connectedOrLaunched = true;
-              results.push('[Sovereign Browser] Attached directly to active Chrome session via port 9222 (Layer 1).');
-            }
-          }
-        } catch (debugErr) {
-          // Port 9222 not active, proceed to Layer 2 / Layer 3 decision
+            const results = await causyneBrowser().run(args.actions ?? []);
+            return { success: true, output: JSON.stringify(results, null, 2), data: results };
         }
-
-        // Sovereign Guard: Decide whether to launch dedicated profile (Layer 2) or personal profile (Layer 3)
-        if (!connectedOrLaunched) {
-          const fallbackDir = path.join(causyneHome(), 'chrome_profile');
-          if (!fs.existsSync(fallbackDir)) fs.mkdirSync(fallbackDir, { recursive: true });
-
-          if (!args.usePersonalProfile) {
-            // Layer 2: Sovereign Dedicated Agent Profile (100% Safe - Never risks logging out personal Chrome accounts)
-            activeBrowser = await puppeteer.launch({
-              executablePath,
-              userDataDir: fallbackDir,
-              headless: false,
-              defaultViewport: null,
-              args: ['--no-sandbox', '--disable-setuid-sandbox']
-            });
-            connectedOrLaunched = true;
-            results.push('[Sovereign Browser] Launched Chrome using Sovereign Dedicated Profile (~/.causyne/chrome_profile). Your personal Google Chrome accounts remain 100% untouched and protected.');
-          } else {
-            // Layer 3: Explicit Personal Profile Guard (Strictly when usePersonalProfile: true is requested)
-            try {
-              const profileArgs = ['--no-sandbox', '--disable-setuid-sandbox'];
-              if (args.profileDirectory) {
-                profileArgs.push(`--profile-directory=${args.profileDirectory}`);
-              }
-              activeBrowser = await puppeteer.launch({
-                executablePath,
-                userDataDir: primaryUserDataDir,
-                headless: false,
-                defaultViewport: null,
-                args: profileArgs
-              });
-              connectedOrLaunched = true;
-              results.push(`[Sovereign Browser] Launched primary profile (${args.profileDirectory || 'Default'}) explicitly requested via usePersonalProfile.`);
-            } catch (launchErr) {
-              const isProfileLock = launchErr.message.includes('already running') ||
-                                    launchErr.message.includes('SingletonLock') ||
-                                    launchErr.message.includes('EBUSY') ||
-                                    launchErr.message.includes('lock') ||
-                                    launchErr.message.includes('user data directory is already in use');
-              if (isProfileLock) {
-                // Safe fallback to dedicated profile so task never fails and never corrupts personal cookies
-                results.push(`[Sovereign Profile Guard] Your personal Chrome profile (${args.profileDirectory || 'Default'}) is currently running and locked without remote debugging port 9222. Automatically switched to Sovereign Dedicated Profile (~/.causyne/chrome_profile) to protect your personal account session from logout.`);
-                activeBrowser = await puppeteer.launch({
-                  executablePath,
-                  userDataDir: fallbackDir,
-                  headless: false,
-                  defaultViewport: null,
-                  args: ['--no-sandbox', '--disable-setuid-sandbox']
-                });
-                connectedOrLaunched = true;
-              } else {
-                throw launchErr;
-              }
+        catch (error) {
+            if (error instanceof BrowserCapabilityError) {
+                return { success: false, error: error.message, requiresConsent: error.requiresConsent };
             }
-          }
-        }
-
-        const pages = await activeBrowser.pages();
-        activePage = pages[0] || (await activeBrowser.newPage());
-      }
-
-      for (const action of args.actions) {
-        if (action.type === 'goto') {
-          await activePage.goto(action.url, { waitUntil: 'networkidle2' });
-          results.push(`Navigated to ${action.url}`);
-        } 
-        else if (action.type === 'click') {
-          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
-          await activePage.click(action.selector);
-          results.push(`Clicked ${action.selector}`);
-        } 
-        else if (action.type === 'type') {
-          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
-          await activePage.type(action.selector, action.text, { delay: action.humanDelayMs || 45 });
-          results.push(`Typed text into ${action.selector} with human keystroke delay`);
-        }
-        // Phase 1 AGI Upgrade: DOM-to-Markdown Interaction
-        else if (action.type === 'clickIndex') {
-          const selector = `[data-causyne-id="${action.index}"]`;
-          await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
-          await activePage.click(selector);
-          results.push(`Clicked element mapped to index [${action.index}]`);
-        }
-        else if (action.type === 'typeIndex') {
-          const selector = `[data-causyne-id="${action.index}"]`;
-          await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
-          await activePage.type(selector, action.text, { delay: action.humanDelayMs || 45 });
-          results.push(`Typed text into element mapped to index [${action.index}] with human keystroke delay`);
-        }
-        else if (action.type === 'selectOption') {
-          if (action.index !== undefined) {
-            const selector = `[data-causyne-id="${action.index}"]`;
-            await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
-            await activePage.select(selector, action.value || action.text);
-          } else if (action.selector) {
-            await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
-            await activePage.select(action.selector, action.value || action.text);
-          }
-          results.push(`Selected option [${action.value || action.text}] from dropdown`);
-        }
-        else if (action.type === 'keyPress') {
-          await activePage.keyboard.press(action.key || 'Enter');
-          results.push(`Pressed keyboard key [${action.key || 'Enter'}]`);
-        }
-        else if (action.type === 'scroll') {
-          await activePage.evaluate(() => {
-            window.scrollBy({ top: window.innerHeight * 0.75, behavior: 'smooth' });
-          });
-          results.push(`Scrolled page smoothly`);
-        }
-        else if (action.type === 'waitFor') {
-          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 10000 });
-          results.push(`Element ${action.selector} appeared`);
-        } 
-        else if (action.type === 'scrape') {
-          // Phase 1 AGI Upgrade: AXTree Mapper injection
-          const mappedMarkdown = await activePage.evaluate(() => {
-            let idx = 1;
-            let lines = [];
-            const elements = document.querySelectorAll('a, button, input, textarea, [role="button"], select');
-            
-            elements.forEach(el => {
-              // Ignore hidden elements
-              const style = window.getComputedStyle(el);
-              if (style.display === 'none' || style.visibility === 'hidden' || el.offsetWidth === 0) return;
-              
-              let label = el.innerText || el.value || el.placeholder || el.getAttribute('aria-label') || el.name || 'unlabeled';
-              label = label.trim().replace(/\n/g, ' ');
-              if (!label) return; // Skip empty elements
-              
-              const tagName = el.tagName.toLowerCase();
-              lines.push(`[${idx}] ${tagName}: ${label}`);
-              
-              el.setAttribute('data-causyne-id', idx.toString());
-              idx++;
-            });
-            return lines.join('\n');
-          });
-          
-          results.push(`Scraped DOM Map:\n${mappedMarkdown}`);
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
         }
-      }
-      
-      return { success: true, log: results };
-    } catch (e) {
-      return { success: false, error: e.message };
     }
-  }
 };

package/src/tools/browserAutomator.ts

@@ -0,0 +1,57 @@
+import { BrowserCapabilityError, causyneBrowser, type BrowserAction } from '../browser/causyneBrowser.js';
+
+export const browserAct = {
+  schema: {
+    name: 'browser.act',
+    description: 'Use the dedicated Causyne Browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
+    parameters: {
+      type: 'object',
+      properties: {
+        actions: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 40,
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['newTab', 'switchTab', 'listTabs', 'closeTab', 'search', 'goto', 'snapshot', 'scrape', 'click', 'clickIndex', 'type', 'typeIndex', 'selectOption', 'keyPress', 'scroll', 'back', 'forward', 'reload', 'extract', 'download', 'screenshot']
+              },
+              tabId: { type: 'string', description: 'Tab id returned by newTab or listTabs.' },
+              url: { type: 'string', description: 'Public http(s) URL for goto or newTab.' },
+              query: { type: 'string', description: 'Search query.' },
+              ref: { type: 'string', description: 'Current accessibility ref, for example e12.' },
+              index: { type: 'number', description: 'Legacy numeric form of an accessibility ref.' },
+              selector: { type: 'string', description: 'CSS selector when a current accessibility ref is unavailable.' },
+              text: { type: 'string' },
+              value: { type: 'string' },
+              key: { type: 'string' },
+              direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+              amount: { type: 'number' },
+              offset: { type: 'number', description: 'Character offset for a paged accessibility snapshot.' },
+              outputFile: { type: 'string', description: 'Download or screenshot destination inside the selected workspace.' },
+              fullPage: { type: 'boolean', description: 'Capture the complete page for a screenshot instead of the visible viewport.' }
+            },
+            required: ['type'],
+            additionalProperties: false
+          }
+        }
+      },
+      required: ['actions'],
+      additionalProperties: false
+    }
+  },
+
+  async execute(args: { actions?: BrowserAction[] }) {
+    try {
+      const results = await causyneBrowser().run(args.actions ?? []);
+      return { success: true, output: JSON.stringify(results, null, 2), data: results };
+    } catch (error) {
+      if (error instanceof BrowserCapabilityError) {
+        return { success: false, error: error.message, requiresConsent: error.requiresConsent };
+      }
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+};

package/src/tools/manageLocalAiDependencies.js

@@ -55,7 +55,7 @@ export const manageLocalDependencies = {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['setup_venv', 'pipInst', 'check_and_setupEng', 'grant_capability', 'list_capabilities', 'grant_mcp_server', 'list_mcp_servers'] },
-        group: { type: 'string', description: 'Capability group for grant_capability: vision (browser + screen capture), ocr (read text from images), system (process and load inspection), desktop (clipboard, open, recycle bin), archive (zip and unzip).' },
+        group: { type: 'string', description: 'Capability group for grant_capability: browser (dedicated Causyne Browser runtime), vision (screen capture), ocr (read text from images), system (process and load inspection), desktop (clipboard, open, recycle bin), archive (zip and unzip).' },
         engine: { type: 'string', enum: ['godot', 'blender'], description: 'Engine to locate when action is check_and_setupEng' },
         simulateMissing: { type: 'boolean', description: 'Simulate missing binary to verify sovereign fallback cascade' },
         packages: { type: 'array', items: { type: 'string' }, description: 'Exact PyPI pins only, for example pillow==11.3.0. URLs, paths, VCS references and pip options are rejected.' }