@porcupine/kuskus 0.1.0 → 0.1.1

package/.claude/settings.local.json

@@ -3,7 +3,29 @@
     "allow": [
       "Bash(npm install 2>&1)",
       "Bash(node -e \"import\\('@modelcontextprotocol/sdk/server/stdio.js'\\).then\\(m => console.log\\(Object.keys\\(m\\)\\)\\).catch\\(e => console.error\\(e.message\\)\\)\" && node -e \"import\\('zod'\\).then\\(m => console.log\\('zod ok'\\)\\).catch\\(e => console.error\\(e.message\\)\\)\")",
-      "Bash(npx vitest run --reporter=verbose 2>&1)"
+      "Bash(npx vitest run --reporter=verbose 2>&1)",
+      "WebFetch(domain:opencode.ai)",
+      "Read(//Users/anak10thn/.config/opencode/**)",
+      "Read(//Users/anak10thn/**)",
+      "Bash(node bin/cli.js install 2>&1)",
+      "Bash(~/.local/bin/lightpanda --version 2>&1 || file ~/.local/bin/lightpanda)",
+      "Bash(echo \"ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY\" | head -c 50)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnpx vitest run --reporter=verbose 2>&1)",
+      "Bash(node -e \"\nimport\\('dotenv/config'\\);\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc\\);\n  const rt = createRuntimeDomain\\(sc\\);\n\n  console.log\\('Navigating to example.com...'\\);\n  await page.navigate\\('https://example.com'\\);\n\n  const title = await rt.evaluate\\('document.title'\\);\n  const url = await page.getURL\\(\\);\n  console.log\\('URL   :', url\\);\n  console.log\\('Title :', title\\);\n\n  const screenshot = await page.screenshot\\(\\);\n  console.log\\('Screenshot size:', screenshot.length, 'chars \\(base64\\)'\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('ERROR:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\necho \"Masukkan ANTHROPIC_API_KEY untuk test \\(atau set di .env\\):\"\nls .env 2>/dev/null && source .env 2>/dev/null\nprintenv ANTHROPIC_API_KEY | cut -c1-20 || echo \"\\(tidak ada\\)\")",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  const sc = await sm.getActiveSession\\(\\);\n\n  const page = createPageDomain\\(sc\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  // 1. Navigate\n  console.log\\('\\\\n[1] Navigate to https://example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  // 2. DOM query\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  const h1HTML = await dom.getOuterHTML\\(h1Id\\);\n  console.log\\('    h1:', h1HTML\\);\n\n  // 3. Page content\n  console.log\\('\\\\n[3] Page content \\(truncated\\)'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  const text = htmlToReadableText\\(html, { maxLength: 300 }\\);\n  console.log\\('   ', text.split\\('\\\\n'\\).slice\\(0,5\\).join\\('\\\\n    '\\)\\);\n\n  // 4. Navigate to google and search\n  console.log\\('\\\\n[4] Navigate to google.com'\\);\n  await page.navigate\\('https://google.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n\n  // 5. Screenshot \\(may return null on Lightpanda\\)\n  console.log\\('\\\\n[5] Screenshot'\\);\n  const ss = await page.screenshot\\(\\);\n  console.log\\('    Result:', ss ? ss.length + ' chars base64' : 'null \\(unsupported by Lightpanda — OK\\)'\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message, e.stack\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  const sc = await sm.getActiveSession\\(\\);\n\n  const page = createPageDomain\\(sc\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  // 1. Navigate\n  console.log\\('\\\\n[1] Navigate https://example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  // 2. DOM query\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  const h1HTML = await dom.getOuterHTML\\(h1Id\\);\n  console.log\\('    h1:', h1HTML.trim\\(\\)\\);\n\n  // 3. Page content\n  console.log\\('\\\\n[3] Page content'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  const text = htmlToReadableText\\(html, { maxLength: 400 }\\);\n  console.log\\('   ', text.replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  // 4. Screenshot\n  console.log\\('\\\\n[4] Screenshot'\\);\n  const ss = await page.screenshot\\(\\);\n  console.log\\('    Result:', ss ? ss.length + ' chars base64' : 'null \\(unsupported — OK\\)'\\);\n\n  // 5. list tabs\n  console.log\\('\\\\n[5] List tabs'\\);\n  const tabs = await sm.listTargets\\(\\);\n  console.log\\('    Tabs:', JSON.stringify\\(tabs\\)\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  const sc = await sm.getActiveSession\\(\\);\n\n  const page = createPageDomain\\(sc\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('\\\\n[1] Navigate https://example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  console.log\\('    h1:', \\(await dom.getOuterHTML\\(h1Id\\)\\).trim\\(\\)\\);\n\n  console.log\\('\\\\n[3] Page content'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  const text = htmlToReadableText\\(html, { maxLength: 300 }\\);\n  console.log\\('   ', text.replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  console.log\\('\\\\n[4] Screenshot'\\);\n  const ss = await page.screenshot\\(\\);\n  console.log\\('    Result:', ss ? ss.length + ' chars base64' : 'null \\(unsupported — OK\\)'\\);\n\n  console.log\\('\\\\n[5] List tabs'\\);\n  const tabs = await sm.listTargets\\(\\);\n  console.log\\('    Tabs:', JSON.stringify\\(tabs, null, 2\\)\\);\n\n  console.log\\('\\\\n[6] New tab + navigate'\\);\n  const sc2 = await sm.createTarget\\('https://httpbin.org/get'\\);\n  const page2 = createPageDomain\\(sc2\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  console.log\\('    Tab2 URL:', await page2.getURL\\(\\)\\);\n\n  console.log\\('\\\\n[7] list tabs after new tab'\\);\n  const tabs2 = await sm.listTargets\\(\\);\n  console.log\\('    Tabs:', tabs2.map\\(t => t.url\\)\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  console.log\\('Capabilities:', sm.capabilities\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('\\\\n[1] Navigate https://example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  console.log\\('    h1:', \\(await dom.getOuterHTML\\(h1Id\\)\\).trim\\(\\)\\);\n\n  console.log\\('\\\\n[3] Page content'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  const text = htmlToReadableText\\(html, { maxLength: 300 }\\);\n  console.log\\('   ', text.replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  console.log\\('\\\\n[4] Screenshot'\\);\n  const ss = await page.screenshot\\(\\);\n  console.log\\('    Result:', ss ? ss.length + ' chars base64' : 'null \\(skipped — Lightpanda\\)'\\);\n\n  console.log\\('\\\\n[5] List tabs'\\);\n  const tabs = await sm.listTargets\\(\\);\n  console.log\\('    Tabs:', JSON.stringify\\(tabs.map\\(t => t.url\\)\\)\\);\n\n  console.log\\('\\\\n[6] New tab'\\);\n  const sc2 = await sm.createTarget\\('https://httpbin.org/json'\\);\n  const page2 = createPageDomain\\(sc2, sm.capabilities\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  console.log\\('    Tab2 URL:', await page2.getURL\\(\\)\\);\n\n  console.log\\('\\\\n[7] List tabs after new tab'\\);\n  const tabs2 = await sm.listTargets\\(\\);\n  console.log\\('    Tabs:', tabs2.map\\(t => t.url\\)\\);\n\n  console.log\\('\\\\n[8] JS eval'\\);\n  const rt2 = createRuntimeDomain\\(sc2\\);\n  const json = await rt2.evaluate\\('JSON.stringify\\(document.title\\)'\\);\n  console.log\\('    title:', json\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message, '\\\\n', e.stack\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  console.log\\('Capabilities:', sm.capabilities\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('\\\\n[1] Navigate example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  console.log\\('    h1:', \\(await dom.getOuterHTML\\(h1Id\\)\\).trim\\(\\)\\);\n\n  console.log\\('\\\\n[3] Page content'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  console.log\\('   ', htmlToReadableText\\(html, { maxLength: 250 }\\).replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  console.log\\('\\\\n[4] Screenshot \\(expect null on Lightpanda\\)'\\);\n  console.log\\('    Result:', await page.screenshot\\(\\) ?? 'null \\(skipped\\)'\\);\n\n  console.log\\('\\\\n[5] List tabs'\\);\n  console.log\\('    Tabs:', JSON.stringify\\(\\(await sm.listTargets\\(\\)\\).map\\(t => t.url\\)\\)\\);\n\n  console.log\\('\\\\n[6] createTarget \\(single-target fallback\\)'\\);\n  const sc2 = await sm.createTarget\\('https://httpbin.org/json'\\);\n  const page2 = createPageDomain\\(sc2, sm.capabilities\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  console.log\\('    URL after createTarget:', await page2.getURL\\(\\)\\);\n\n  console.log\\('\\\\n[7] click + type'\\);\n  await page.navigate\\('https://example.com'\\);\n  await new Promise\\(r => setTimeout\\(r, 1000\\)\\);\n  const linkId = await dom.querySelector\\('a'\\);\n  if \\(linkId\\) {\n    await dom.scrollIntoView\\(linkId\\);\n    const { x, y } = await dom.getCenter\\(linkId\\);\n    console.log\\('    link center:', x, y\\);\n    await inp.click\\(x, y\\);\n    await new Promise\\(r => setTimeout\\(r, 1000\\)\\);\n    console.log\\('    URL after click:', await page.getURL\\(\\)\\);\n  }\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  console.log\\('Capabilities:', sm.capabilities\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('\\\\n[1] Navigate example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n  console.log\\('    Title:', await page.getTitle\\(\\)\\);\n\n  console.log\\('\\\\n[2] querySelector h1'\\);\n  const h1Id = await dom.querySelector\\('h1'\\);\n  console.log\\('    h1:', \\(await dom.getOuterHTML\\(h1Id\\)\\).trim\\(\\)\\);\n\n  console.log\\('\\\\n[3] Page content'\\);\n  const html = await rt.evaluate\\('document.documentElement.outerHTML'\\);\n  console.log\\('   ', htmlToReadableText\\(html, { maxLength: 200 }\\).replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  console.log\\('\\\\n[4] Screenshot \\(expect null\\)'\\);\n  console.log\\('    Result:', await page.screenshot\\(\\) ?? 'null \\(skipped — Lightpanda\\)'\\);\n\n  console.log\\('\\\\n[5] List tabs'\\);\n  console.log\\('    Tabs:', JSON.stringify\\(\\(await sm.listTargets\\(\\)\\).map\\(t => t.url\\)\\)\\);\n\n  console.log\\('\\\\n[6] createTarget fallback — navigate to httpbin'\\);\n  await sm.createTarget\\('https://httpbin.org/json'\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n\n  console.log\\('\\\\n[7] click link on example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  await new Promise\\(r => setTimeout\\(r, 800\\)\\);\n  const linkId = await dom.querySelector\\('a'\\);\n  if \\(linkId\\) {\n    const { x, y } = await dom.getCenter\\(linkId\\);\n    console.log\\('    click at', x, y\\);\n    await inp.click\\(x, y\\);\n    await new Promise\\(r => setTimeout\\(r, 1000\\)\\);\n    console.log\\('    URL after click:', await page.getURL\\(\\)\\);\n  } else {\n    console.log\\('    no link found'\\);\n  }\n\n  console.log\\('\\\\n[8] evaluate JS'\\);\n  const links = await rt.evaluate\\('JSON.stringify\\(Array.from\\(document.querySelectorAll\\(\\\\\"a\\\\\"\\)\\).map\\(a=>a.href\\)\\)'\\);\n  console.log\\('    links:', links\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message, '\\\\n', e.stack?.split\\('\\\\n'\\)[1]\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: console.log }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('[1] navigate example.com'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    URL:', await page.getURL\\(\\), '| Title:', await page.getTitle\\(\\)\\);\n\n  console.log\\('[2] h1 text'\\);\n  const h1 = await dom.querySelector\\('h1'\\);\n  console.log\\('   ', \\(await dom.getOuterHTML\\(h1\\)\\).trim\\(\\)\\);\n\n  console.log\\('[3] page content'\\);\n  const text = htmlToReadableText\\(await rt.evaluate\\('document.documentElement.outerHTML'\\), { maxLength: 200 }\\);\n  console.log\\('   ', text.replace\\(/\\\\n/g, '\\\\n    '\\)\\);\n\n  console.log\\('[4] screenshot:', await page.screenshot\\(\\) ?? 'null \\(Lightpanda — OK\\)'\\);\n\n  console.log\\('[5] tabs:', \\(await sm.listTargets\\(\\)\\).map\\(t => t.url\\)\\);\n\n  console.log\\('[6] createTarget \\(single-target fallback\\)'\\);\n  await sm.createTarget\\('https://httpbin.org/json'\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  console.log\\('    URL:', await page.getURL\\(\\)\\);\n\n  console.log\\('[7] click link'\\);\n  await page.navigate\\('https://example.com'\\);\n  await new Promise\\(r => setTimeout\\(r, 1000\\)\\);\n  const link = await dom.querySelector\\('a'\\);\n  if \\(link\\) {\n    const { x, y } = await dom.getCenter\\(link\\);\n    await inp.click\\(x, y\\);\n    await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n    console.log\\('    URL after click:', await page.getURL\\(\\)\\);\n  }\n\n  console.log\\('[8] type into input \\(httpbin form\\)'\\);\n  await page.navigate\\('https://httpbin.org/forms/post'\\);\n  await new Promise\\(r => setTimeout\\(r, 1500\\)\\);\n  const custname = await dom.querySelector\\('input[name=custname]'\\);\n  if \\(custname\\) {\n    await dom.scrollIntoView\\(custname\\);\n    const { x, y } = await dom.getCenter\\(custname\\);\n    await inp.click\\(x, y\\);\n    await inp.type\\('Kuskus Bot'\\);\n    const val = await rt.evaluate\\('document.querySelector\\(\\\\\"input[name=custname]\\\\\"\\).value'\\);\n    console.log\\('    input value:', val\\);\n  } else {\n    console.log\\('    input not found'\\);\n  }\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message, '\\\\n', e.stack?.split\\('\\\\n'\\)[1]\\); process.exit\\(1\\); }\\);\n\" 2>&1)",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: \\(m\\) => process.stdout.write\\(m+'\\\\n'\\) }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  process.stdout.write\\('[1] navigate example.com\\\\n'\\);\n  await page.navigate\\('https://example.com'\\);\n  process.stdout.write\\('    URL: ' + await page.getURL\\(\\) + '\\\\n'\\);\n  process.stdout.write\\('    Title: ' + await page.getTitle\\(\\) + '\\\\n'\\);\n\n  process.stdout.write\\('[2] h1: ' + \\(await dom.getOuterHTML\\(await dom.querySelector\\('h1'\\)\\)\\).trim\\(\\) + '\\\\n'\\);\n\n  process.stdout.write\\('[3] screenshot: ' + \\(await page.screenshot\\(\\) ?? 'null \\(Lightpanda OK\\)'\\) + '\\\\n'\\);\n\n  process.stdout.write\\('[4] tabs: ' + JSON.stringify\\(\\(await sm.listTargets\\(\\)\\).map\\(t=>t.url\\)\\) + '\\\\n'\\);\n\n  process.stdout.write\\('[5] createTarget fallback\\\\n'\\);\n  await sm.createTarget\\('https://httpbin.org/json'\\);\n  await new Promise\\(r=>setTimeout\\(r,1500\\)\\);\n  process.stdout.write\\('    URL: ' + await page.getURL\\(\\) + '\\\\n'\\);\n\n  process.stdout.write\\('[6] click link\\\\n'\\);\n  await page.navigate\\('https://example.com'\\);\n  await new Promise\\(r=>setTimeout\\(r,1000\\)\\);\n  const link = await dom.querySelector\\('a'\\);\n  if \\(link\\) {\n    const {x,y} = await dom.getCenter\\(link\\);\n    await inp.click\\(x, y\\);\n    await new Promise\\(r=>setTimeout\\(r,2000\\)\\);\n    process.stdout.write\\('    URL after click: ' + await page.getURL\\(\\) + '\\\\n'\\);\n  }\n\n  process.stdout.write\\('[7] type into form\\\\n'\\);\n  await page.navigate\\('https://httpbin.org/forms/post'\\);\n  await new Promise\\(r=>setTimeout\\(r,2000\\)\\);\n  const input = await dom.querySelector\\('input[name=custname]'\\);\n  if \\(input\\) {\n    await dom.scrollIntoView\\(input\\);\n    const {x,y} = await dom.getCenter\\(input\\);\n    await inp.click\\(x,y\\);\n    await inp.type\\('Kuskus Bot'\\);\n    const val = await rt.evaluate\\('document.querySelector\\(\\\\\"input[name=custname]\\\\\"\\).value'\\);\n    process.stdout.write\\('    typed value: ' + val + '\\\\n'\\);\n  }\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  process.stdout.write\\('\\\\nAll checks passed.\\\\n'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { process.stderr.write\\('FAIL: '+e.message+'\\\\n'\\); process.exit\\(1\\); }\\);\n\" 2>&1 | grep -v '^\\\\[32m')",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: m => process.stdout.write\\(m+'\\\\n'\\) }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createInputDomain } = await import\\('./src/cdp/domains/input.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { htmlToReadableText } = await import\\('./src/utils/dom-to-text.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n\n  const sc = await sm.getActiveSession\\(\\);\n  const page = createPageDomain\\(sc, sm.capabilities\\);\n  const dom  = createDOMDomain\\(sc\\);\n  const rt   = createRuntimeDomain\\(sc\\);\n  const inp  = createInputDomain\\(sc\\);\n\n  console.log\\('[1] navigate + title'\\);\n  await page.navigate\\('https://example.com'\\);\n  console.log\\('    ✓', await page.getURL\\(\\), '|', await page.getTitle\\(\\)\\);\n\n  console.log\\('[2] DOM query'\\);\n  const h1 = await dom.querySelector\\('h1'\\);\n  console.log\\('    ✓', \\(await dom.getOuterHTML\\(h1\\)\\).trim\\(\\)\\);\n\n  console.log\\('[3] page content'\\);\n  const text = htmlToReadableText\\(await rt.evaluate\\('document.documentElement.outerHTML'\\), {maxLength:200}\\);\n  console.log\\('    ✓', text.split\\('\\\\n'\\)[0]\\);\n\n  console.log\\('[4] screenshot capability'\\);\n  console.log\\('    ✓ screenshot:', await page.screenshot\\(\\) ?? 'null \\(Lightpanda — skipped safely\\)'\\);\n\n  console.log\\('[5] list tabs'\\);\n  console.log\\('    ✓', \\(await sm.listTargets\\(\\)\\).map\\(t=>t.url\\)\\);\n\n  console.log\\('[6] form fill + type'\\);\n  await page.navigate\\('https://httpbin.org/forms/post'\\);\n  await new Promise\\(r=>setTimeout\\(r,2000\\)\\);\n  const custname = await dom.querySelector\\('input[name=custname]'\\);\n  if \\(custname\\) {\n    await dom.scrollIntoView\\(custname\\);\n    const {x,y} = await dom.getCenter\\(custname\\);\n    await inp.click\\(x,y\\);\n    await inp.type\\('Kuskus Bot'\\);\n    const val = await rt.evaluate\\('document.querySelector\\(\\\\\"input[name=custname]\\\\\"\\).value'\\);\n    console.log\\('    ✓ typed:', val\\);\n  } else { console.log\\('    ✗ input not found'\\); }\n\n  console.log\\('[7] select dropdown'\\);\n  const sel = await dom.querySelector\\('select[name=size]'\\);\n  if \\(sel\\) {\n    await rt.evaluate\\('const el=document.querySelector\\(\\\\\"select[name=size]\\\\\"\\);el.value=\\\\\"large\\\\\";el.dispatchEvent\\(new Event\\(\\\\\"change\\\\\",{bubbles:true}\\)\\)'\\);\n    const val = await rt.evaluate\\('document.querySelector\\(\\\\\"select[name=size]\\\\\"\\).value'\\);\n    console.log\\('    ✓ select value:', val\\);\n  }\n\n  console.log\\('[8] evaluate JS'\\);\n  const links = await rt.evaluate\\('Array.from\\(document.querySelectorAll\\(\\\\\"a\\\\\"\\)\\).map\\(a=>a.textContent.trim\\(\\)\\).filter\\(Boolean\\)'\\);\n  console.log\\('    ✓ links on page:', links\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\n✓ All core checks passed.'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('✗ FAIL:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1 | grep -v '^\\\\[3')",
+      "Bash(pkill lightpanda 2>/dev/null; sleep 0.3\nnode -e \"\nimport\\('./src/utils/browser.js'\\).then\\(async \\({ ensureBrowser }\\) => {\n  const proc = await ensureBrowser\\({ port: 9222, host: '127.0.0.1', log: m => process.stdout.write\\(m+'\\\\n'\\) }\\);\n  const { SessionManager } = await import\\('./src/cdp/session.js'\\);\n  const { createPageDomain } = await import\\('./src/cdp/domains/page.js'\\);\n  const { createDOMDomain } = await import\\('./src/cdp/domains/dom.js'\\);\n  const { createRuntimeDomain } = await import\\('./src/cdp/domains/runtime.js'\\);\n  const { Executor } = await import\\('./src/agent/executor.js'\\);\n\n  const sm = new SessionManager\\({ host: '127.0.0.1', port: 9222 }\\);\n  await sm.connect\\(\\);\n  const exec = new Executor\\(sm\\);\n\n  console.log\\('[1] navigate'\\);\n  const r1 = await exec.execute\\('navigate', { url: 'https://example.com' }\\);\n  console.log\\('   ', r1\\);\n\n  console.log\\('[2] get_url'\\);\n  const r2 = await exec.execute\\('get_url', {}\\);\n  console.log\\('   ', r2\\);\n\n  console.log\\('[3] get_page_content'\\);\n  const r3 = await exec.execute\\('get_page_content', {}\\);\n  console.log\\('   ', r3.slice\\(0, 150\\)\\);\n\n  console.log\\('[4] screenshot'\\);\n  const r4 = await exec.execute\\('screenshot', {}\\);\n  console.log\\('   ', r4?.type === 'screenshot' ? 'screenshot captured' : r4\\);\n\n  console.log\\('[5] evaluate_js'\\);\n  const r5 = await exec.execute\\('evaluate_js', { script: 'document.title' }\\);\n  console.log\\('   ', r5\\);\n\n  console.log\\('[6] navigate to form'\\);\n  await exec.execute\\('navigate', { url: 'https://httpbin.org/forms/post' }\\);\n  await new Promise\\(r => setTimeout\\(r, 2000\\)\\);\n\n  console.log\\('[7] type_text'\\);\n  const r7 = await exec.execute\\('type_text', { selector: 'input[name=custname]', text: 'Kuskus Bot' }\\);\n  console.log\\('   ', r7\\);\n\n  console.log\\('[8] select_option'\\);\n  const r8 = await exec.execute\\('select_option', { selector: 'select[name=size]', value: 'large' }\\);\n  console.log\\('   ', r8\\);\n\n  console.log\\('[9] evaluate — verify values'\\);\n  const r9 = await exec.execute\\('evaluate_js', {\n    script: 'JSON.stringify\\({ name: document.querySelector\\(\\\\\"input[name=custname]\\\\\"\\).value, size: document.querySelector\\(\\\\\"select[name=size]\\\\\"\\).value }\\)'\n  }\\);\n  console.log\\('   ', r9\\);\n\n  await sm.close\\(\\);\n  proc?.kill\\(\\);\n  console.log\\('\\\\nAll executor checks passed!'\\);\n  process.exit\\(0\\);\n}\\).catch\\(e => { console.error\\('FAIL:', e.message\\); process.exit\\(1\\); }\\);\n\" 2>&1 | grep -v 'INFO\\\\|wsUrl')",
+      "Bash(pkill -x lightpanda 2>/dev/null; sleep 1 && node /tmp/kuskus-test.mjs 2>&1 | grep -v \"INFO\\\\|wsUrl\")",
+      "Bash(pkill -x lightpanda 2>/dev/null; npx vitest run --reporter=verbose 2>&1)",
+      "Bash(npm install openai 2>&1 | tail -3)"
     ]
   }
 }

package/.env.example

@@ -1,8 +1,19 @@
 # ── CLI only ──────────────────────────────────────────────────────────────────
 # Required only for `kuskus run/repl/script` commands.
 # The MCP server does NOT use an API key — the host model drives the agent.
+
+# Provider: anthropic | openai
+# Leave unset to auto-detect from model name (claude-* → anthropic, gpt-* → openai)
+# AGENT_PROVIDER=anthropic
+
+# API keys — only the key for your chosen provider is needed
 ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+
+# Model name — provider is auto-detected if AGENT_PROVIDER is not set
 AGENT_MODEL=claude-sonnet-4-6
+# AGENT_MODEL=gpt-4o
+
 AGENT_MAX_STEPS=20
 AGENT_MAX_TOKENS=4096
 AGENT_INCLUDE_SCREENSHOT=true
@@ -11,7 +22,8 @@ AGENT_SCREENSHOT_QUALITY=80
 # ── Browser (CLI + MCP) ────────────────────────────────────────────────────────
 CDP_URL=ws://localhost:9222
 CDP_LAUNCH_BROWSER=false
-CDP_BROWSER_PATH=lightpanda
+# Override auto-detect with a specific Chrome/Chromium binary
+# CDP_BROWSER_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
 CDP_BROWSER_PORT=9222
 
 # ── Logging ───────────────────────────────────────────────────────────────────

package/README.md

@@ -0,0 +1,430 @@
+<p align="center">
+  <img src="assets/logo.png" width="160" alt="Kuskus" />
+</p>
+
+<h1 align="center">Kuskus</h1>
+
+<p align="center">
+  AI browser agent via Chrome DevTools Protocol — CLI + MCP Server
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@porcupine/kuskus"><img src="https://img.shields.io/npm/v/@porcupine/kuskus?color=a78bfa&label=npm" alt="npm" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node" />
+  <img src="https://img.shields.io/badge/browser-Chromium-blue" alt="Chromium" />
+  <img src="https://img.shields.io/badge/protocol-CDP-blue" alt="CDP" />
+</p>
+
+---
+
+Kuskus controls a browser directly over the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) by auto-detecting an installed Chrome/Chromium build (or downloading one on demand).
+
+Ships as two artifacts:
+
+| | CLI | MCP Server |
+|---|---|---|
+| **Usage** | `kuskus run "task..."` | Claude Desktop, Cursor, OpenCode, etc. |
+| **LLM** | Claude (via `ANTHROPIC_API_KEY`) | Host model — no key needed |
+| **Role** | Full agent loop | Expose browser tools to any AI |
+
+---
+
+## Requirements
+
+- Node.js >= 20
+- Chrome or Chromium (auto-detected; falls back to downloading a Chromium build into `~/.local`)
+
+---
+
+## CLI
+
+### Install
+
+```bash
+npm install -g @porcupine/kuskus
+```
+
+Or use directly with npx (no install needed):
+
+```bash
+npx @porcupine/kuskus run "your task here"
+```
+
+### Setup
+
+```bash
+cp .env.example .env
+```
+
+Set the API key for your chosen provider:
+
+```env
+# Anthropic (Claude) — default
+ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+```
+
+Provider is **auto-detected from the model name** — no need to set it explicitly:
+
+| Model prefix | Provider |
+|---|---|
+| `claude-*` | Anthropic |
+| `gpt-*`, `o1*`, `o3*`, `o4*`, `chatgpt-*` | OpenAI |
+
+### Commands
+
+#### `run` — one-shot task
+
+```bash
+kuskus run "go to news.ycombinator.com and summarize the top 5 posts"
+```
+
+Options:
+
+```
+--cdp-url <url>      CDP WebSocket URL (default: ws://localhost:9222)
+--provider <name>    LLM provider: anthropic or openai (auto-detected if not set)
+--model <model>      Model name (default: claude-sonnet-4-6)
+--max-steps <n>      Max agent steps (default: 20)
+--screenshots <dir>  Save step screenshots to directory
+--launch             Auto-launch Chrome/Chromium before running
+--no-headless        Launch Chrome/Chromium with a visible window
+--force-launch       Shut down an existing debugging browser before launching
+--output <format>    Output format: text or json (default: text)
+--debug              Log raw CDP messages
+```
+
+#### `repl` — interactive session
+
+```bash
+kuskus repl --launch
+```
+
+Special commands inside REPL:
+
+```
+!screenshot   Capture and save the current viewport
+!tabs         List open browser tabs
+!history      Show action history
+!clear        Reset agent memory
+!exit         Quit
+```
+
+#### `script` — batch tasks from JSON
+
+```bash
+kuskus script ./tasks.json --output json
+```
+
+`tasks.json` format:
+
+```json
+[
+  "go to github.com/lightpanda-io/browser and read the description",
+  "search google for nodejs best practices 2025 and list the top 3 links"
+]
+```
+
+#### `install` — manually install Chromium
+
+```bash
+kuskus install
+# or force re-download
+kuskus install --force
+```
+
+#### `mcp` — start MCP server
+
+```bash
+kuskus mcp
+```
+
+> Chromium is downloaded and launched automatically. No API key required.
+
+---
+
+## MCP Server
+
+The MCP server exposes browser control tools to any AI host — Claude Desktop, Cursor, OpenCode, or any MCP-compatible client. The host model drives the reasoning; Kuskus only executes browser actions.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kuskus": {
+      "command": "npx",
+      "args": ["-y", "@porcupine/kuskus", "mcp"],
+      "env": {
+        "CDP_URL": "ws://localhost:9222"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "kuskus": {
+      "type": "local",
+      "command": ["npx", "-y", "@porcupine/kuskus", "mcp"],
+      "enabled": true,
+      "environment": {
+        "CDP_URL": "ws://localhost:9222"
+      }
+    }
+  }
+}
+```
+
+### Cursor / other MCP clients
+
+```json
+{
+  "mcpServers": {
+    "kuskus": {
+      "command": "npx",
+      "args": ["-y", "@porcupine/kuskus", "mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+#### Navigation
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Navigate to a URL |
+| `browser_go_back` | Go back in history |
+| `browser_go_forward` | Go forward in history |
+| `browser_get_url` | Get current URL |
+
+#### Observation
+| Tool | Description |
+|------|-------------|
+| `browser_screenshot` | Capture viewport as PNG |
+| `browser_get_content` | Get page text content |
+| `browser_element_info` | Get element attributes and text |
+
+#### Interaction
+| Tool | Description |
+|------|-------------|
+| `browser_click` | Click element by CSS selector |
+| `browser_type` | Type text into an input |
+| `browser_key_press` | Press a key (Enter, Tab, Escape…) |
+| `browser_scroll` | Scroll up or down |
+| `browser_hover` | Hover over an element |
+| `browser_select` | Select a `<select>` option |
+| `browser_checkbox` | Check or uncheck a checkbox |
+
+#### JavaScript
+| Tool | Description |
+|------|-------------|
+| `browser_evaluate` | Execute JS and return result |
+| `browser_extract` | Extract structured data via JS |
+
+#### Tabs
+| Tool | Description |
+|------|-------------|
+| `browser_list_tabs` | List all open tabs |
+| `browser_new_tab` | Open a new tab |
+| `browser_switch_tab` | Switch to a tab by ID |
+| `browser_close_tab` | Close a tab |
+
+#### Utility
+| Tool | Description |
+|------|-------------|
+| `browser_wait` | Wait N milliseconds (max 10s) |
+
+### MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `browser://screenshot` | Current viewport as PNG |
+| `browser://page/content` | Current page text |
+| `browser://page/url` | Current URL |
+| `browser://tabs` | Open tabs as JSON |
+
+---
+
+## Architecture
+
+```
+Entry Points
+  kuskus run / repl / script          kuskus mcp
+          │                                │
+          ▼                                ▼
+    Agent Core                       MCP Server
+  (plan → execute loop)          (expose tools directly)
+  Claude API + tool use           no LLM — host model drives
+          │                                │
+          └──────────────┬─────────────────┘
+                         ▼
+                  Executor (CDP tools)
+                         │
+                  SessionManager
+                  (single WebSocket,
+                   session multiplexing)
+                         │
+              Chromium Browser
+              ws://localhost:9222
+```
+
+### How the agent loop works
+
+```
+┌─────────────────────────────────────────────┐
+│  1. Observe   get_page_content + screenshot  │
+│  2. Plan      Claude picks next tool         │
+│  3. Execute   CDP command via Chromium       │
+│  4. Remember  append step to rolling history │
+│  5. Repeat    until finish or max steps      │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Configuration
+
+All options via environment variables (`.env` file supported):
+
+```env
+# CLI only — not needed for MCP
+ANTHROPIC_API_KEY=sk-ant-...      # for Claude models
+OPENAI_API_KEY=sk-...             # for GPT / o-series models
+
+# Provider: anthropic | openai — auto-detected from model name if not set
+# AGENT_PROVIDER=anthropic
+
+AGENT_MODEL=claude-sonnet-4-6    # or gpt-4o, o3-mini, etc.
+AGENT_MAX_STEPS=20
+AGENT_MAX_TOKENS=4096
+AGENT_INCLUDE_SCREENSHOT=true
+AGENT_SCREENSHOT_QUALITY=80
+
+# Browser (CLI + MCP)
+CDP_URL=ws://localhost:9222
+# CDP_BROWSER_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+CDP_BROWSER_PORT=9222
+
+# Logging
+LOG_LEVEL=info                     # debug | info | warn | error
+LOG_FORMAT=pretty                  # pretty | logfmt
+```
+
+---
+
+## Browser Runtime
+
+Kuskus looks for Chrome/Chromium automatically. It checks common install locations (`/Applications/Google Chrome.app`, `chromium`, etc.) and honours `CDP_BROWSER_PATH`, `CHROME_PATH`, and `GOOGLE_CHROME_BIN` if set.
+
+When no suitable binary is found (and auto-install is allowed) Kuskus downloads the latest **Chromium for Testing** build to `~/.local/chrome/<version>` and symlinks it to `~/.local/bin/chromium`.
+
+Supported platforms for auto-download:
+
+| OS | Arch |
+|----|------|
+| Linux | x86_64, arm64 |
+| macOS | x86_64 (Intel), arm64 (Apple Silicon) |
+
+Use `CDP_BROWSER_PATH` to point at a custom binary if you prefer a specific channel (e.g. Chrome Canary) or an alternative CDP-compatible browser.
+
+---
+
+## Examples
+
+```bash
+# With Claude (default)
+kuskus run "go to https://github.com/lightpanda-io/browser and summarize the README" --launch
+
+# With GPT-4o — provider auto-detected from model name
+kuskus run "go to news.ycombinator.com and list the top 5 posts" --model gpt-4o --launch
+
+# With o3-mini
+kuskus run "go to https://httpbin.org/json and extract all fields" --model o3-mini --launch
+
+# Force provider explicitly
+kuskus run "..." --provider openai --model gpt-4o-mini --launch
+
+# Interactive REPL
+kuskus repl --launch
+kuskus repl --model gpt-4o --launch
+
+# Extract data as JSON
+kuskus run "go to news.ycombinator.com, extract title and URL of each front page post" --launch --output json
+
+# Batch tasks
+kuskus script ./tasks.json --model gpt-4o --output json
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/porcupine/kuskus
+cd kuskus
+npm install
+cp .env.example .env
+
+# Run tests
+npm test
+
+# Try the CLI
+node bin/cli.js install         # download Chromium for Testing
+node bin/cli.js run "..." --launch
+```
+
+### Project structure
+
+```
+kuskus/
+├── bin/
+│   └── cli.js              CLI entrypoint (run/repl/script/mcp/install)
+├── src/
+│   ├── cdp/
+│   │   ├── client.js       WebSocket CDP client + session multiplexing
+│   │   ├── session.js      Target/tab manager
+│   │   └── domains/
+│   │       ├── page.js     Navigate, screenshot, reload
+│   │       ├── dom.js      querySelector, getBoxModel, focus
+│   │       ├── input.js    Click, hover, scroll, key press
+│   │       ├── runtime.js  Evaluate JS
+│   │       ├── network.js  Request monitoring/intercept
+│   │       └── target.js   Multi-tab management
+│   ├── agent/
+│   │   ├── index.js        KuskusAgent orchestrator
+│   │   ├── planner.js      LLM planning loop (provider-agnostic)
+│   │   ├── providers.js    Anthropic + OpenAI adapters, auto-detection
+│   │   ├── executor.js     Tool → CDP command mapping
+│   │   ├── tools.js        Tool definitions (JSON Schema)
+│   │   ├── memory.js       Rolling step history
+│   │   └── prompts.js      System prompt
+│   ├── mcp/
+│   │   ├── server.js       MCP server (stdio transport)
+│   │   └── handlers.js     Tool + resource handlers
+│   └── utils/
+│       ├── chromium.js     Chrome/Chromium detector + downloader
+│       ├── browser.js      Launch + CDP readiness check
+│       ├── dom-to-text.js  HTML → readable text for LLM
+│       ├── screenshot.js   Save screenshots to disk
+│       └── logger.js       Structured logger (pino)
+├── tests/
+└── examples/
+```
+
+---
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,46 @@
+# Kuskus Skill Overview
+
+Kuskus is a CLI and MCP server that lets an AI agent control a real Chrome/Chromium browser over the Chrome DevTools Protocol. Use it when you need rich browser interactions (navigation, DOM scraping, screenshots) in automated workflows.
+
+## Capabilities
+- Launches or attaches to a local Chrome/Chromium instance (headless or visible).
+- Auto-detects Anthropic or OpenAI models based on name; supports GPT-4o and Claude Sonnet out of the box.
+- Exposes a full tool palette (navigation, DOM queries, input, waits, screenshots) via JSON-schema definitions.
+- Provides a REPL for interactive runs and a script runner for batch tasks.
+- MCP server mode surfaces the same browser tools to host applications (Claude Desktop, Cursor, etc.).
+
+## Quick Start (CLI)
+```bash
+npm install -g @porcupine/kuskus
+export OPENAI_API_KEY=sk-...
+
+# one-shot task (visible browser)
+kuskus run "Visit https://example.com and report the heading" --model gpt-4o --launch --no-headless
+
+# interactive REPL with Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Key flags:
+- `--launch` / `--no-headless` – start Chrome automatically, optionally with a window.
+- `--force-launch` – shut down any existing debugging browser before launching.
+- `--output json` – return structured data when tools emit payloads.
+
+## MCP Integration
+Start the MCP server and let the host model drive planning:
+
+```bash
+npx @porcupine/kuskus mcp --launch --no-headless
+```
+
+Configure your MCP-compatible client to use the `kuskus` command. Available tools include page navigation, content extraction, screenshot capture, and tab management.
+
+## Deployment Notes
+- Chrome auto-detection checks standard install paths and environment overrides (`CDP_BROWSER_PATH`, `CHROME_PATH`, `GOOGLE_CHROME_BIN`).
+- When no browser is found, the CLI downloads the latest Chromium-for-Testing build into `~/.local/chrome/<version>`.
+- Ensure `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is set before running tasks that use those providers.
+
+## Troubleshooting
+- Use `--debug` to stream CDP traffic and planner logs.
+- If a previous headless session is blocking `--no-headless`, add `--force-launch` to close it before relaunch.
+- Screenshots can be saved automatically with `--screenshots <dir>`.