@vpxa/aikit 0.1.147 → 0.1.149

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.147",
+  "version": "0.1.149",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/scaffold/dist/definitions/plugins.mjs

@@ -1 +1 @@
-const e={aikit:{description:`AI Kit search, analysis, memory, and developer tools`,source:`scaffold/skills/aikit/SKILL.md`,required:!0},brainstorming:{description:`Brainstorming & design exploration workflow`,source:`scaffold/skills/brainstorming/SKILL.md`,required:!0,sidecars:[`scaffold/skills/brainstorming/spec-document-reviewer-prompt.md`]},"multi-agents-development":{description:`Multi-agent orchestration, task decomposition, parallel dispatch, and review pipeline patterns`,source:`scaffold/skills/multi-agents-development/SKILL.md`,required:!0,sidecars:[`scaffold/skills/multi-agents-development/implementer-prompt.md`,`scaffold/skills/multi-agents-development/spec-review-prompt.md`,`scaffold/skills/multi-agents-development/code-quality-review-prompt.md`,`scaffold/skills/multi-agents-development/architecture-review-prompt.md`,`scaffold/skills/multi-agents-development/parallel-dispatch-example.md`]},"adr-skill":{description:`Architecture Decision Records — create, maintain, and review ADRs for significant technical decisions`,source:`scaffold/skills/adr-skill/SKILL.md`,required:!0,sidecars:[`scaffold/skills/adr-skill/assets/templates/adr-madr.md`,`scaffold/skills/adr-skill/assets/templates/adr-readme.md`,`scaffold/skills/adr-skill/assets/templates/adr-simple.md`,`scaffold/skills/adr-skill/references/adr-conventions.md`,`scaffold/skills/adr-skill/references/examples.md`,`scaffold/skills/adr-skill/references/review-checklist.md`,`scaffold/skills/adr-skill/references/template-variants.md`,`scaffold/skills/adr-skill/scripts/bootstrap_adr.js`,`scaffold/skills/adr-skill/scripts/new_adr.js`,`scaffold/skills/adr-skill/scripts/set_adr_status.js`]},"c4-architecture":{description:`C4 model architecture diagrams using Mermaid — system context, container, component, and deployment views`,source:`scaffold/skills/c4-architecture/SKILL.md`,required:!0,sidecars:[`scaffold/skills/c4-architecture/references/advanced-patterns.md`,`scaffold/skills/c4-architecture/references/c4-syntax.md`,`scaffold/skills/c4-architecture/references/common-mistakes.md`]},"frontend-design":{description:`Frontend design system — visual design thinking, typography, color, layout, motion, accessibility, and anti-pattern detection`,source:`scaffold/skills/frontend-design/SKILL.md`,required:!1},"lesson-learned":{description:`Extract engineering lessons from recent code changes via git history analysis`,source:`scaffold/skills/lesson-learned/SKILL.md`,required:!0,sidecars:[`scaffold/skills/lesson-learned/references/anti-patterns.md`,`scaffold/skills/lesson-learned/references/se-principles.md`]},present:{description:`Rich interactive dashboards, charts, tables, timelines, and data visualizations via the present MCP tool`,source:`scaffold/skills/present/SKILL.md`,required:!0},react:{description:`React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration`,source:`scaffold/skills/react/SKILL.md`,required:!1},"requirements-clarity":{description:`Clarify ambiguous requirements through focused dialogue — score 0-100 until ≥90 before implementation`,source:`scaffold/skills/requirements-clarity/SKILL.md`,required:!0},"session-handoff":{description:`Comprehensive handoff documents for seamless AI agent session transfers and context preservation`,source:`scaffold/skills/session-handoff/SKILL.md`,required:!0,sidecars:[`scaffold/skills/session-handoff/references/handoff-template.md`,`scaffold/skills/session-handoff/references/resume-checklist.md`,`scaffold/skills/session-handoff/scripts/check_staleness.js`,`scaffold/skills/session-handoff/scripts/create_handoff.js`,`scaffold/skills/session-handoff/scripts/list_handoffs.js`,`scaffold/skills/session-handoff/scripts/validate_handoff.js`]},typescript:{description:`TypeScript development patterns — type system, compiler config, advanced types, async patterns, module organization`,source:`scaffold/skills/typescript/SKILL.md`,required:!1},docs:{description:`Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture`,source:`scaffold/skills/docs/SKILL.md`,required:!0},"repo-access":{description:`Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone`,source:`scaffold/skills/repo-access/SKILL.md`,required:!0,sidecars:[`scaffold/skills/repo-access/references/platform-matrix.md`,`scaffold/skills/repo-access/references/error-patterns.md`]},"browser-use":{description:`AI Kit owned browser runtime — zero setup authentication recovery, data extraction, form filling, and web interaction. Built-in Chromium with headless/UI/panel modes. Pairs with repo-access as final escalation for SSO/login wall recovery.`,source:`scaffold/skills/browser-use/SKILL.md`,required:!1,sidecars:[`scaffold/skills/browser-use/references/recipes.md`,`scaffold/skills/browser-use/references/auth-patterns.md`]}};export{e as PLUGINS};
+const e={aikit:{description:`AI Kit search, analysis, memory, and developer tools`,source:`scaffold/skills/aikit/SKILL.md`,required:!0},brainstorming:{description:`Brainstorming & design exploration workflow`,source:`scaffold/skills/brainstorming/SKILL.md`,required:!0,sidecars:[`scaffold/skills/brainstorming/spec-document-reviewer-prompt.md`]},"multi-agents-development":{description:`Multi-agent orchestration, task decomposition, parallel dispatch, and review pipeline patterns`,source:`scaffold/skills/multi-agents-development/SKILL.md`,required:!0,sidecars:[`scaffold/skills/multi-agents-development/implementer-prompt.md`,`scaffold/skills/multi-agents-development/spec-review-prompt.md`,`scaffold/skills/multi-agents-development/code-quality-review-prompt.md`,`scaffold/skills/multi-agents-development/architecture-review-prompt.md`,`scaffold/skills/multi-agents-development/parallel-dispatch-example.md`]},"adr-skill":{description:`Architecture Decision Records — create, maintain, and review ADRs for significant technical decisions`,source:`scaffold/skills/adr-skill/SKILL.md`,required:!0,sidecars:[`scaffold/skills/adr-skill/assets/templates/adr-madr.md`,`scaffold/skills/adr-skill/assets/templates/adr-readme.md`,`scaffold/skills/adr-skill/assets/templates/adr-simple.md`,`scaffold/skills/adr-skill/references/adr-conventions.md`,`scaffold/skills/adr-skill/references/examples.md`,`scaffold/skills/adr-skill/references/review-checklist.md`,`scaffold/skills/adr-skill/references/template-variants.md`,`scaffold/skills/adr-skill/scripts/bootstrap_adr.js`,`scaffold/skills/adr-skill/scripts/new_adr.js`,`scaffold/skills/adr-skill/scripts/set_adr_status.js`]},"c4-architecture":{description:`C4 model architecture diagrams using Mermaid — system context, container, component, and deployment views`,source:`scaffold/skills/c4-architecture/SKILL.md`,required:!0,sidecars:[`scaffold/skills/c4-architecture/references/advanced-patterns.md`,`scaffold/skills/c4-architecture/references/c4-syntax.md`,`scaffold/skills/c4-architecture/references/c4.schema.json`,`scaffold/skills/c4-architecture/references/common-mistakes.md`]},"frontend-design":{description:`Frontend design system — visual design thinking, typography, color, layout, motion, accessibility, and anti-pattern detection`,source:`scaffold/skills/frontend-design/SKILL.md`,required:!1},"lesson-learned":{description:`Extract engineering lessons from recent code changes via git history analysis`,source:`scaffold/skills/lesson-learned/SKILL.md`,required:!0,sidecars:[`scaffold/skills/lesson-learned/references/anti-patterns.md`,`scaffold/skills/lesson-learned/references/se-principles.md`]},present:{description:`Rich interactive dashboards, charts, tables, timelines, and data visualizations via the present MCP tool`,source:`scaffold/skills/present/SKILL.md`,required:!0},react:{description:`React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration`,source:`scaffold/skills/react/SKILL.md`,required:!1},"requirements-clarity":{description:`Clarify ambiguous requirements through focused dialogue — score 0-100 until ≥90 before implementation`,source:`scaffold/skills/requirements-clarity/SKILL.md`,required:!0},"session-handoff":{description:`Comprehensive handoff documents for seamless AI agent session transfers and context preservation`,source:`scaffold/skills/session-handoff/SKILL.md`,required:!0,sidecars:[`scaffold/skills/session-handoff/references/handoff-template.md`,`scaffold/skills/session-handoff/references/resume-checklist.md`,`scaffold/skills/session-handoff/scripts/check_staleness.js`,`scaffold/skills/session-handoff/scripts/create_handoff.js`,`scaffold/skills/session-handoff/scripts/list_handoffs.js`,`scaffold/skills/session-handoff/scripts/validate_handoff.js`]},typescript:{description:`TypeScript development patterns — type system, compiler config, advanced types, async patterns, module organization`,source:`scaffold/skills/typescript/SKILL.md`,required:!1},docs:{description:`Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture`,source:`scaffold/skills/docs/SKILL.md`,required:!0},"repo-access":{description:`Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone`,source:`scaffold/skills/repo-access/SKILL.md`,required:!0,sidecars:[`scaffold/skills/repo-access/references/platform-matrix.md`,`scaffold/skills/repo-access/references/error-patterns.md`]},"browser-use":{description:`AI Kit owned browser runtime — zero setup authentication recovery, data extraction, form filling, and web interaction. Built-in Chromium with headless/UI/panel modes. Pairs with repo-access as final escalation for SSO/login wall recovery.`,source:`scaffold/skills/browser-use/SKILL.md`,required:!1,sidecars:[`scaffold/skills/browser-use/references/recipes.md`,`scaffold/skills/browser-use/references/auth-patterns.md`]}};export{e as PLUGINS};

package/scaffold/dist/definitions/skills/_shared-viewer-inject.mjs

@@ -0,0 +1,108 @@
+const e=`#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+function die(message) {
+  process.stderr.write('Error: ' + message + '
+');
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = { template: null, data: null, out: null, id: null };
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--template' || arg === '--data' || arg === '--out' || arg === '--id') {
+      const value = argv[index + 1];
+
+      if (!value || value.startsWith('--')) {
+        die(arg + ' requires a value');
+      }
+
+      args[arg.slice(2)] = value;
+      index += 1;
+      continue;
+    }
+
+    die('Unknown argument: ' + arg + '. Usage: node scripts/inject-viewer.mjs --template <html> --data <json> --out <output.html> [--id <placeholder-id>]');
+  }
+
+  if (!args.template) {
+    die('--template is required');
+  }
+
+  if (!args.data) {
+    die('--data is required');
+  }
+
+  if (!args.out) {
+    die('--out is required');
+  }
+
+  return args;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\{}()[]^$+*?.]/g, '\\$&');
+}
+
+function buildScriptPattern(id) {
+  const typeLookahead = "(?=[^>]*\\btype=['"]application\\/json['"] )".replace(' )', ')');
+  const idLookahead = id
+    ? ("(?=[^>]*\\bid=['"]" + escapeRegExp(id) + "['"] )").replace(' )', ')')
+    : "(?=[^>]*\\bid=['"][^'"]+['"] )".replace(' )', ')');
+
+  return new RegExp(
+    '(<script\\b' + typeLookahead + idLookahead + '[^>]*>)[\\s\\S]*?(<\/script>)',
+    'i',
+  );
+}
+
+const args = parseArgs(process.argv);
+
+let template;
+try {
+  template = readFileSync(args.template, 'utf8');
+} catch (error) {
+  die('Cannot read template: ' + args.template + ' - ' + error.message);
+}
+
+let data;
+try {
+  data = readFileSync(args.data, 'utf8');
+} catch (error) {
+  die('Cannot read data: ' + args.data + ' - ' + error.message);
+}
+
+try {
+  JSON.parse(data);
+} catch (error) {
+  die('Invalid JSON in ' + args.data + ': ' + error.message);
+}
+
+const pattern = buildScriptPattern(args.id);
+if (!pattern.test(template)) {
+  if (args.id) {
+    die('No <script type="application/json" id="' + args.id + '"> found in template');
+  }
+
+  die('No <script type="application/json" id="..."> found in template');
+}
+
+const safeData = data.replace(/<\\/script/gi, '<\\/script');
+const output = template.replace(pattern, '$1
+' + safeData + '
+$2');
+
+try {
+  mkdirSync(dirname(args.out), { recursive: true });
+  writeFileSync(args.out, output, 'utf8');
+} catch (error) {
+  die('Cannot write output: ' + args.out + ' - ' + error.message);
+}
+
+process.stdout.write('Injected ' + args.data + ' -> ' + args.out + '
+');
+`;export{e as INJECT_VIEWER_SCRIPT};

package/scaffold/dist/definitions/skills/browser-use.mjs

@@ -1,4 +1,4 @@
-var e=[{file:`SKILL.md`,content:"---\nname: browser-use\ndescription: \"Browser automation for AI agents using AI Kit's owned `browser` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) `web_fetch` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that `web_fetch` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: on-demand\n  inputs: [url, auth-error, browser-task, login-wall]\n  outputs: [page-content, screenshots, extracted-data, authenticated-session, network-captures]\n  requires: []\n  relatedSkills: [repo-access, present, aikit]\nargument-hint: \"URL or browser task description\"\n---\n\n# Browser Automation for AI Agents\n\nUse AI Kit's `browser` MCP tool for authentication barriers, data extraction, form interactions, network capture, and web automation. Single tool, action-based dispatch, owned Chromium runtime.\n\n## Runtime\n\n- Tool: `browser({ action: ... })`\n- 11 actions: `open`, `read`, `act`, `navigate`, `network`, `console`, `fetch`, `eval`, `screenshot`, `dialog`, `session`\n- Modes: `headless` (CI), `ui` (desktop), `panel` (VS Code)\n- Install: `aikit browser install`\n- Auto-idle shutdown after timeout\n\n## When to Activate\n\n- `web_fetch` returns login HTML, SAML redirect, or CAPTCHA\n- `http` returns 401/403 and user confirms browser access works\n- `repo-access` Strategy Ladder exhausted — SSO/OAuth blocks CLI\n- Anti-bot detection (Cloudflare, \"verify you are human\")\n- User asks to browse, scrape, automate, test, or interact with a web app\n- Need screenshots, accessibility snapshots, or JS-rendered content\n- Need to capture network traffic or make authenticated API calls using page session\n\n## When NOT to Activate\n\n- Public pages `web_fetch` handles correctly\n- API endpoints reachable via `http` with auth headers\n- Static downloads via `http`\n- Tasks only needing raw HTML/links/outline\n\n## Two Automation Modes\n\n### Script Mode (Default — Imperative)\n\nDirect sequential `browser()` calls. Best for one-off tasks, testing, API capture.\n\n~~~text\n// Open → Read → Act → Read loop\nbrowser({ action: 'open', url: 'https://app.example.com', mode: 'ui' })\nbrowser({ action: 'read', pageId })\nbrowser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })\nbrowser({ action: 'read', pageId })  // verify state changed\n~~~\n\n**Network Intelligence pattern:**\n\n~~~text\nbrowser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })\n// ... navigate/interact to trigger API calls ...\nbrowser({ action: 'network', pageId, subAction: 'get' })\nbrowser({ action: 'network', pageId, subAction: 'export-har' })\n~~~\n\n**Authenticated API calls (using page cookies/session):**\n\n~~~text\nbrowser({ action: 'fetch', pageId, fetchUrl: 'https://app.example.com/api/data', fetchMethod: 'GET' })\n~~~\n\nExecutes `fetch()` in the page, so cookies, session state, and CSRF tokens are reused automatically.\n\n**Console capture:**\n\n~~~text\nbrowser({ action: 'console', pageId, consoleSubAction: 'enable' })\n// ... trigger page actions ...\nbrowser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })\n~~~\n\n### Recipe Mode (Declarative)\n\nStructured step-by-step format for reusable workflows and domain skills. Each step declares Action, Verify, On Failure, and Extract fields.\n\nLoad [references/recipes.md](references/recipes.md) for full recipe templates and the recipe format specification.\n\nBrief recipe format:\n\n~~~text\nStep N: <description>\n  Action: browser({ ... })\n  Verify: <condition to check after action>\n  On Failure: <recovery strategy>\n  Extract: <data to capture for next steps>\n~~~\n\n## Action Reference\n\n| Action | Purpose | Key Params |\n|--------|---------|------------|\n| `open` | Launch page | `url`, `mode` (ui/headless/panel), `waitUntil` |\n| `read` | Extract content | `pageId`, `readMode` (snapshot/dom/markdown/text), `selector` |\n| `act` | DOM interaction | `pageId`, `kind`, `ref`/`selector`, `text`/`key`/`value` |\n| `navigate` | Page navigation | `pageId`, `url` or `type` (back/forward/reload/waitFor) |\n| `network` | Capture traffic | `pageId`, `subAction` (enable/get/clear/export-har), `filter` |\n| `console` | Capture console | `pageId`, `consoleSubAction` (enable/get/clear), `level` |\n| `fetch` | Page-context HTTP | `pageId`, `fetchUrl`, `fetchMethod`, `fetchHeaders`, `fetchBody` |\n| `eval` | Execute JS | `pageId`, `code` |\n| `screenshot` | Capture image | `pageId`, `selector`, `fullPage`, `clip`, `format` |\n| `dialog` | Handle dialogs | `pageId`, `accept`, `promptText` |\n| `session` | Manage sessions | `sessionAction` (list/close/cookies/set-cookie/get-storage/...) |\n\n## Read Modes\n\n| Mode | Output | Use Case |\n|------|--------|----------|\n| `snapshot` | ARIA accessibility tree with refs | Element targeting, form interaction |\n| `dom` | Raw HTML | HTML structure, debugging |\n| `markdown` | Clean readable text | Content extraction, summarization |\n| `text` | Plain text | Simple text extraction |\n\n## Interaction Kinds\n\n| Kind | Required Params | Notes |\n|------|-----------------|-------|\n| `click` | `ref` or `selector` | Left-click element |\n| `type` | `ref`/`selector` + `text` | Type into input/textarea |\n| `press` | `key` | Keyboard key (Enter, Tab, Escape) |\n| `hover` | `ref`/`selector` | Trigger hover states |\n| `drag` | `fromRef`/`fromSelector` + `toRef`/`toSelector` | Drag and drop |\n| `select` | `ref`/`selector` + `value` | Select dropdown option |\n| `scroll` | optional `ref`/`selector` | Scroll page or element |\n| `upload` | `ref`/`selector` + `value` (path) | File upload |\n\n## Network Intelligence\n\nThree new actions for API reverse-engineering and authenticated requests:\n\n**`network`** — Passive traffic capture with circular buffer (200 entries default):\n- `enable`: Start capturing with optional filter (resourceTypes, urlPattern, excludeUrls)\n- `get`: Retrieve captured requests + responses with timing\n- `clear`: Reset buffer\n- `export-har`: Export as HAR 1.2 format\n\nHeaders are redacted by default (Authorization, Cookie, etc.). Pass `showSensitive: true` to see full headers.\n\n**`console`** — Browser console message capture (1000 entries default):\n- `enable`: Start capturing all console output\n- `get`: Retrieve messages, optionally filtered by `level`\n- `clear`: Reset buffer\n\n**`fetch`** — Execute HTTP from page context:\n- Uses the page's live cookies, session, CSRF tokens\n- Supports GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS\n- Body auto-truncated at 256KB\n- Alternative to extracting cookies then calling `http` tool\n\n**Workflow — Reverse-engineer API:**\n\n~~~text\n1. open target page\n2. network enable (filter: xhr, fetch)\n3. interact with the page (click buttons, submit forms)\n4. network get → see API endpoints, methods, headers\n5. fetch → replay API calls using page session\n~~~\n\n## Session Management\n\n| Action | Purpose |\n|--------|---------|\n| `cookies` | Export page cookies |\n| `set-cookie` | Inject cookies |\n| `delete-cookie` / `clear-cookies` | Remove cookies |\n| `get-storage` / `set-storage` / `clear-storage` | localStorage/sessionStorage |\n| `list` | List open pages |\n| `close` | Close a page |\n\n## Security Model\n\n**Hard gates — NEVER bypass:**\n- Credentials go via terminal input (NEVER through tool params or chat)\n- CAPTCHA/MFA: pause and ask user\n- Never store tokens in conversation\n- Close pages containing sensitive data when done\n- Verify page URL before entering credentials (phishing prevention)\n- Use `headless` mode for automated non-interactive tasks; `ui` for user-supervised auth\n\n## Integration\n\n| Skill | Handoff Pattern |\n|-------|------------------|\n| `repo-access` | Strategy Ladder step 6 → browser-use for SSO/OAuth login |\n| `present` | `present({ format: 'browser' })` returns URL → open with browser tool |\n| `aikit` | `web_fetch` fails → browser-use activates |\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| \"Browser not installed\" | Run `aikit browser install` |\n| Element not found | `read` with `snapshot` mode first, use ref from ARIA tree |\n| Timeout on navigation | Add `waitUntil: 'networkidle'` to open/navigate |\n| SSO redirect loop | Check cookies with `session({ sessionAction: 'cookies' })` |\n| Anti-bot block | Try `mode: 'ui'`, add delays between actions |\n| Network capture empty | Ensure `enable` called BEFORE navigating |\n\n## Decision Flow\n\n~~~text\nNeed browser?\n├─ Can web_fetch/http handle it? → NO browser needed\n├─ Login wall / SSO / CAPTCHA? → browser-use (Script mode for one-off, Recipe for reusable)\n├─ Need to capture API traffic? → network enable → interact → network get\n├─ Need authenticated API calls? → fetch action (uses page session)\n├─ JS-rendered content? → open + read(markdown)\n├─ Form interaction? → Script mode: open → read(snapshot) → act → verify\n└─ Reusable workflow? → Recipe mode (see references/recipes.md)\n~~~\n"},{file:`references/recipes.md`,content:`# Browser Recipes & Domain Skills
+var e=[{file:`SKILL.md`,content:"---\nname: browser-use\ndescription: \"Browser automation for AI agents using AI Kit's owned `browser` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) `web_fetch` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that `web_fetch` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: on-demand\n  inputs: [url, auth-error, browser-task, login-wall]\n  outputs: [page-content, screenshots, extracted-data, authenticated-session, network-captures]\n  requires: []\n  relatedSkills: [repo-access, present, aikit]\nargument-hint: \"URL or browser task description\"\n---\n\n# Browser Automation for AI Agents\n\nUse AI Kit's `browser` MCP tool for authentication barriers, data extraction, form interactions, network capture, and web automation. Single tool, action-based dispatch, owned Chromium runtime.\n\n## Runtime\n\n- Tool: `browser({ action: ... })`\n- 11 actions: `open`, `read`, `act`, `navigate`, `network`, `console`, `fetch`, `eval`, `screenshot`, `dialog`, `session`\n- Modes: `headless` (CI), `ui` (desktop), `panel` (VS Code)\n- Install: `aikit browser install`\n- Auto-idle shutdown after timeout\n\n## When to Activate\n\n- `web_fetch` returns login HTML, SAML redirect, or CAPTCHA\n- `http` returns 401/403 and user confirms browser access works\n- `repo-access` Strategy Ladder exhausted — SSO/OAuth blocks CLI\n- Anti-bot detection (Cloudflare, \"verify you are human\")\n- User asks to browse, scrape, automate, test, or interact with a web app\n- Need screenshots, accessibility snapshots, or JS-rendered content\n- Need to capture network traffic or make authenticated API calls using page session\n\n## When NOT to Activate\n\n- Public pages `web_fetch` handles correctly\n- API endpoints reachable via `http` with auth headers\n- Static downloads via `http`\n- Tasks only needing raw HTML/links/outline\n\n## Two Automation Modes\n\n### Script Mode (Default — Imperative)\n\nDirect sequential `browser()` calls. Best for one-off tasks, testing, API capture.\n\n~~~text\n// Open → Read → Act → Read loop\nbrowser({ action: 'open', url: 'https://app.example.com', mode: 'ui' })\nbrowser({ action: 'read', pageId })\nbrowser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })\nbrowser({ action: 'read', pageId })  // verify state changed\n~~~\n\n**Network Intelligence pattern:**\n\n~~~text\nbrowser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })\n// ... navigate/interact to trigger API calls ...\nbrowser({ action: 'network', pageId, subAction: 'get' })\nbrowser({ action: 'network', pageId, subAction: 'export-har' })\n~~~\n\n**Authenticated API calls (using page cookies/session):**\n\n~~~text\nbrowser({ action: 'fetch', pageId, fetchUrl: 'https://app.example.com/api/data', fetchMethod: 'GET' })\n~~~\n\nExecutes `fetch()` in the page, so cookies, session state, and CSRF tokens are reused automatically.\n\n**Console capture:**\n\n~~~text\nbrowser({ action: 'console', pageId, consoleSubAction: 'enable' })\n// ... trigger page actions ...\nbrowser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })\n~~~\n\n### Recipe Mode (Declarative)\n\nStructured step-by-step format for reusable workflows and domain skills. Each step declares Action, Verify, On Failure, and Extract fields.\n\nLoad [references/recipes.md](references/recipes.md) for full recipe templates and the recipe format specification.\n\nBrief recipe format:\n\n~~~text\nStep N: <description>\n  Action: browser({ ... })\n  Verify: <condition to check after action>\n  On Failure: <recovery strategy>\n  Extract: <data to capture for next steps>\n~~~\n\n## Action Reference\n\n| Action | Purpose | Key Params |\n|--------|---------|------------|\n| `open` | Launch page | `url`, `mode` (ui/headless/panel), `waitUntil` |\n| `read` | Extract content | `pageId`, `readMode` (snapshot/dom/markdown/text), `selector` |\n| `act` | DOM interaction | `pageId`, `kind`, `ref`/`selector`, `text`/`key`/`value` |\n| `navigate` | Page navigation | `pageId`, `url` or `type` (back/forward/reload/waitFor) |\n| `network` | Capture traffic | `pageId`, `subAction` (enable/get/clear/export-har), `filter` |\n| `console` | Capture console | `pageId`, `consoleSubAction` (enable/get/clear), `level` |\n| `fetch` | Page-context HTTP | `pageId`, `fetchUrl`, `fetchMethod`, `fetchHeaders`, `fetchBody` |\n| `eval` | Execute JS | `pageId`, `code` |\n| `screenshot` | Capture image | `pageId`, `selector`, `fullPage`, `clip`, `format` |\n| `dialog` | Pre-register handler for NEXT dialog | `pageId`, `accept`, `promptText` |\n| `session` | Manage sessions | `sessionAction` (list/close/cookies/set-cookie/get-storage/...) |\n\n## Read Modes\n\n| Mode | Output | Use Case |\n|------|--------|----------|\n| `snapshot` | ARIA accessibility tree with refs | Element targeting, form interaction |\n| `dom` | Raw HTML | HTML structure, debugging |\n| `markdown` | Clean readable text | Content extraction, summarization |\n| `text` | Plain text | Simple text extraction |\n\n## Interaction Kinds\n\n| Kind | Required Params | Notes |\n|------|-----------------|-------|\n| `click` | `ref` or `selector` | Left-click element |\n| `type` | `ref`/`selector` + `text` | Type into input/textarea |\n| `press` | `ref`/`selector` + `key` | Send key to element. Requires a target — use `ref` from snapshot or `selector`. |\n| `hover` | `ref`/`selector` | Trigger hover states |\n| `drag` | `fromRef`/`fromSelector` + `toRef`/`toSelector` | Drag and drop |\n| `select` | `ref`/`selector` + `value` | Select dropdown option |\n| `scroll` | optional `ref`/`selector` | Scroll page or element |\n| `upload` | `ref`/`selector` + `value` (path) | File upload |\n\n### Element Targeting Priority\n\n1. **`ref`** (e.g., `@F12`) — From `read(snapshot)` ARIA tree. Most reliable.\n2. **`selector`** (e.g., `input[name='q']`) — Playwright CSS/attribute selector. Precise.\n3. **`element`** (e.g., `'Submit'`) — Text matching via `text=` locator. **Picks first DOM match regardless of visibility.** Fragile for complex widgets (comboboxes, ARIA roles). Last resort.\n\n**Always `read(snapshot)` first** to get refs before interacting.\n\n> **Visibility Warning**: Playwright `act` waits up to 30s for the target to be visible. If a selector or `element` matches a hidden element first, the action times out. The browser tool does NOT expose a `force` or custom `timeout` parameter.\n>\n> **Workarounds:**\n> - Append `:visible` to selectors: `selector: 'button:has-text(\"Submit\"):visible'`\n> - Use specific selectors instead of `element` when labels are ambiguous (e.g., \"Search\" may match 30+ elements)\n> - Use `read(snapshot)` refs (`@F12`) which always target the specific rendered element\n\n## Network Intelligence\n\nThree new actions for API reverse-engineering and authenticated requests:\n\n**`network`** — Passive traffic capture with circular buffer (200 entries default):\n- `enable`: Start capturing with optional filter (resourceTypes, urlPattern, excludeUrls)\n- `get`: Retrieve captured requests + responses with timing\n- `clear`: Reset buffer\n- `export-har`: Export as HAR 1.2 format\n\nHeaders are redacted by default (Authorization, Cookie, etc.). Pass `showSensitive: true` to see full headers.\n\n**`console`** — Browser console message capture (1000 entries default):\n- `enable`: Start capturing all console output\n- `get`: Retrieve messages, optionally filtered by `level`\n- `clear`: Reset buffer\n\n**`fetch`** — Execute HTTP from page context:\n- Uses the page's live cookies, session, CSRF tokens\n- Supports GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS\n- Body auto-truncated at 256KB\n- Alternative to extracting cookies then calling `http` tool\n\n**Workflow — Reverse-engineer API:**\n\n~~~text\n1. open target page\n2. network enable (filter: xhr, fetch)\n3. interact with the page (click buttons, submit forms)\n4. network get → see API endpoints, methods, headers\n5. fetch → replay API calls using page session\n~~~\n\n## Session Management\n\n| Action | Purpose | Note |\n|--------|---------|------|\n| `cookies` | Export page cookies | `confirm: true` required |\n| `set-cookie` | Inject cookies | `confirm: true` required |\n| `delete-cookie` / `clear-cookies` | Remove cookies | `confirm: true` required |\n| `get-storage` / `set-storage` / `clear-storage` | localStorage/sessionStorage | |\n| `list` | List open pages | |\n| `close` | Close a page | |\n\n## Security Model\n\n**Hard gates — NEVER bypass:**\n- Credentials go via terminal input (NEVER through tool params or chat)\n- CAPTCHA/MFA: pause and ask user\n- Never store tokens in conversation\n- Close pages containing sensitive data when done\n- Verify page URL before entering credentials (phishing prevention)\n- Use `headless` mode for automated non-interactive tasks; `ui` for user-supervised auth\n\n**Cookie safety gate:** All cookie read/write session actions (`cookies`, `set-cookie`, `delete-cookie`, `clear-cookies`) require `confirm: true` as an explicit acknowledgment. Without it, the tool returns an error.\n\n## Integration\n\n| Skill | Handoff Pattern |\n|-------|------------------|\n| `repo-access` | Strategy Ladder step 6 → browser-use for SSO/OAuth login |\n| `present` | `present({ format: 'browser' })` returns URL → open with browser tool |\n| `aikit` | `web_fetch` fails → browser-use activates |\n\n## Dialog Handling\n\n`dialog()` registers a **one-shot handler** for the NEXT dialog. It must be called **BEFORE** the action that triggers alert, confirm, or prompt.\n\n**Pattern:**\n~~~text\nbrowser({ action: 'dialog', pageId, accept: true })\nbrowser({ action: 'eval', pageId, code: 'confirm(\"Sure?\")' }) // or browser({ action: 'act', ... }) if interaction triggers it\n~~~\n\nFor `prompt` dialogs, pass `promptText` for the response.\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| \"Browser not installed\" | Run `aikit browser install` |\n| Element not found | `read` with `snapshot` mode first, use ref from ARIA tree |\n| Timeout on navigation | Add `waitUntil: 'networkidle'` to open/navigate |\n| SSO redirect loop | Check cookies with `session({ sessionAction: 'cookies' })` |\n| Anti-bot block | Try `mode: 'ui'`, add delays between actions |\n| Network capture empty | Ensure `enable` called BEFORE navigating |\n\n## Decision Flow\n\n~~~text\nNeed browser?\n├─ Can web_fetch/http handle it? → NO browser needed\n├─ Login wall / SSO / CAPTCHA? → browser-use (Script mode for one-off, Recipe for reusable)\n├─ Need to capture API traffic? → network enable → interact → network get\n├─ Need authenticated API calls? → fetch action (uses page session)\n├─ JS-rendered content? → open + read(markdown)\n├─ Form interaction? → Script mode: open → read(snapshot) → act → verify\n└─ Reusable workflow? → Recipe mode (see references/recipes.md)\n~~~\n"},{file:`references/recipes.md`,content:`# Browser Recipes & Domain Skills
 
 Reference file for reusable browser automation patterns. Load this when building domain-specific browser workflows.
 
@@ -71,7 +71,7 @@ Step 4: Verify return to application
   Extract: session state
 
 Step 5: Export session (optional)
-  Action: browser({ action: 'session', pageId, sessionAction: 'cookies' })
+  Action: browser({ action: 'session', pageId, sessionAction: 'cookies', confirm: true })
   Verify: Got authentication cookies
   Extract: cookies for http tool usage
 ~~~
@@ -255,7 +255,7 @@ Browser-based authentication strategies for different auth mechanisms.
 
 **Steps:**
 1. Complete authentication via Pattern 1 or 2
-2. \`session({ sessionAction: 'cookies' })\` — export all cookies
+2. \`session({ sessionAction: 'cookies', confirm: true })\` — export all cookies
 3. Use cookies in \`http\` tool: \`http({ url, headers: { Cookie: '<exported>' } })\`
 
 **Alternative (Recommended):** Use \`browser({ action: 'fetch', pageId, fetchUrl: '<api-endpoint>' })\` instead of extracting cookies. The \`fetch\` action executes HTTP requests directly in the page context, automatically using the page's cookies, session, and CSRF tokens. No cookie extraction or manual header management needed.