typeclaw 0.1.0

package/src/bundled-plugins/agent-browser/index.ts

@@ -0,0 +1,179 @@
+import { join } from 'node:path'
+
+import { definePlugin } from '@/plugin'
+import { bindWithForward } from '@/portbroker'
+
+import { AGENT_BROWSER_DASHBOARD_PROXY_PORT, startDashboardProxy, type DashboardProxy } from './dashboard-proxy'
+import { installShim, KNOWN_BIN_PATHS, type InstallShimResult } from './shim-install'
+
+type SafeResult = InstallShimResult | { kind: 'error'; binPath: string; error: unknown }
+
+// Documented in skills/agent-browser/SKILL.md so the agent can discover which
+// port the proxy actually bound to (4848 + a 10-port fallback range). Moving
+// or renaming this path requires updating the skill in lockstep.
+const PROXY_PORT_HINT_PATH = '/tmp/typeclaw-agent-browser-proxy-port'
+const PORT_CANDIDATE_RANGE = 10
+const BROKER_HANDSHAKE_DELAY_MS = 1_000
+const FORWARD_RESULT_TIMEOUT_MS = 10_000
+
+let activeProxy: DashboardProxy | null = null
+let bindingInFlight: Promise<void> | null = null
+
+export default definePlugin({
+  plugin: async (ctx) => {
+    for (const binPath of Object.values(KNOWN_BIN_PATHS)) {
+      logInstallResult(ctx.logger, safeInstallShim(binPath))
+    }
+
+    // Kick off the proxy bind in the background and let the plugin factory
+    // return immediately. Two reasons:
+    //   1. The container-side broker is created AFTER pluginsLoaded.markBooted()
+    //      runs (see src/run/index.ts). If we awaited bindWithForward here, we
+    //      would block the boot sequence past 20s of timeouts before the broker
+    //      even existed to send forward-result events.
+    //   2. The dashboard isn't typically used at boot — the user runs
+    //      `agent-browser dashboard start` later. The proxy has plenty of time
+    //      to settle before its first request.
+    if (activeProxy === null && bindingInFlight === null) {
+      bindingInFlight = bindProxyAfterBrokerSettles(ctx.logger).finally(() => {
+        bindingInFlight = null
+      })
+    }
+
+    return {
+      skillsDirs: [join(import.meta.dir, 'skills')],
+    }
+  },
+})
+
+export function __resetProxyForTesting(): void {
+  activeProxy?.stop()
+  activeProxy = null
+  bindingInFlight = null
+}
+
+export function __waitForProxyBindForTesting(): Promise<void> {
+  return bindingInFlight ?? Promise.resolve()
+}
+
+async function bindProxyAfterBrokerSettles(logger: {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+}): Promise<void> {
+  // Give the run-loop time to construct the container broker and let it
+  // complete its WS handshake with hostd. Without this the first candidate
+  // bind fires before the broker is ready, the bus never delivers a result,
+  // and we waste the full timeout × candidate-count budget tearing down
+  // every port in the range. The exact delay isn't load-bearing — anything
+  // longer than the broker's connect+hello round-trip works.
+  if (defaultBrokerEnabled()) {
+    await Bun.sleep(BROKER_HANDSHAKE_DELAY_MS)
+  }
+
+  const config = readPortConfig()
+  const candidates = buildCandidatePorts(config.listenPort)
+  const upstreamOverride = config.upstreamPort
+
+  const result = await bindWithForward<DashboardProxy>({
+    candidates,
+    timeoutMs: FORWARD_RESULT_TIMEOUT_MS,
+    factory: (port) => {
+      try {
+        const proxy = startDashboardProxy({ listenPort: port, upstreamPort: upstreamOverride })
+        return Promise.resolve({ resource: proxy, close: () => proxy.stop() })
+      } catch (error) {
+        logger.warn(`bind ${port} failed: ${String(error)}`)
+        return Promise.resolve(null)
+      }
+    },
+    onLog: (msg) => logger.info(`[bind-with-forward] ${msg}`),
+  })
+
+  if (result === null) {
+    logger.warn(
+      `could not allocate a host-forwardable dashboard proxy port from ${candidates[0]}-${candidates[candidates.length - 1]}; ` +
+        `remote dashboard access will not work until another container releases its port`,
+    )
+    return
+  }
+
+  activeProxy = result.resource
+  recordProxyPort(result.port, logger)
+  logger.info(
+    `dashboard proxy listening on port ${result.port}` +
+      (result.hostPort !== null ? ` (forwarded to host:${result.hostPort})` : ''),
+  )
+}
+
+function defaultBrokerEnabled(): boolean {
+  const token = process.env['TYPECLAW_HOSTD_BROKER_TOKEN']
+  return token !== undefined && token.length > 0
+}
+
+function buildCandidatePorts(start: number): number[] {
+  const out: number[] = []
+  for (let i = 0; i < PORT_CANDIDATE_RANGE; i += 1) out.push(start + i)
+  return out
+}
+
+function recordProxyPort(port: number, logger: { warn: (msg: string) => void }): void {
+  try {
+    Bun.write(PROXY_PORT_HINT_PATH, String(port))
+  } catch (error) {
+    // Hint is informational (lets a future `typeclaw status` or a human shell
+    // session report which port to open). Failure is non-fatal.
+    logger.warn(`failed to write ${PROXY_PORT_HINT_PATH}: ${String(error)}`)
+  }
+}
+
+type PortConfig = { listenPort: number; upstreamPort: number | undefined }
+
+function readPortConfig(): PortConfig {
+  const overrideUpstream = process.env['TYPECLAW_DASHBOARD_UPSTREAM_PORT']
+  return {
+    listenPort: numberFromEnv('TYPECLAW_DASHBOARD_PROXY_PORT', AGENT_BROWSER_DASHBOARD_PROXY_PORT),
+    upstreamPort:
+      overrideUpstream === undefined || overrideUpstream === '' ? undefined : numberOrUndefined(overrideUpstream),
+  }
+}
+
+function numberOrUndefined(raw: string): number | undefined {
+  const parsed = Number(raw)
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65_535) return undefined
+  return parsed
+}
+
+function numberFromEnv(name: string, fallback: number): number {
+  const raw = process.env[name]
+  if (raw === undefined || raw === '') return fallback
+  const parsed = Number(raw)
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65_535) return fallback
+  return parsed
+}
+
+function safeInstallShim(binPath: string): SafeResult {
+  try {
+    return installShim({ binPath })
+  } catch (error) {
+    return { kind: 'error', binPath, error }
+  }
+}
+
+function logInstallResult(
+  logger: { info: (msg: string) => void; warn: (msg: string) => void },
+  result: SafeResult,
+): void {
+  if (result.kind === 'installed') {
+    logger.info(`installed agent-browser shim at ${result.binPath} (real bin: ${result.realBin})`)
+    return
+  }
+  if (result.kind === 'already-installed') {
+    logger.info(`agent-browser shim already installed at ${result.binPath}`)
+    return
+  }
+  if (result.kind === 'no-upstream') {
+    logger.info(`no agent-browser binary at ${result.binPath}; skipping`)
+    return
+  }
+  logger.warn(`failed to install agent-browser shim at ${result.binPath}: ${String(result.error)}`)
+}

package/src/bundled-plugins/agent-browser/shim-install.ts

@@ -0,0 +1,158 @@
+import {
+  lstatSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join, resolve as resolvePath } from 'node:path'
+
+import { REAL_BIN_ENV } from './shim'
+
+const DEFAULT_GLOBAL_BIN_PATH = '/usr/local/bin/agent-browser'
+const DEFAULT_LOCAL_BIN_PATH = '/agent/node_modules/.bin/agent-browser'
+const STASH_ROOT = '/usr/local/lib/typeclaw-agent-browser'
+const SHIM_MARKER = '# typeclaw-agent-browser-shim'
+
+export type InstallShimOptions = {
+  binPath?: string
+  stashDir?: string
+  shimEntry?: string
+  fs?: ShimFs
+}
+
+export type ShimFs = {
+  lstat: (path: string) => { isSymbolicLink: () => boolean } | null
+  // statExists follows symlinks: a broken symlink (link entry exists, target
+  // does not) returns false. This is the discriminator we need to skip
+  // installation when the host bind-mount surfaces dangling node_modules/.bin
+  // entries inside the container — see installShim's upstream guard.
+  statExists: (path: string) => boolean
+  readlink: (path: string) => string
+  readFile: (path: string) => string
+  rename: (from: string, to: string) => void
+  symlink: (target: string, path: string) => void
+  writeFile: (path: string, data: string, mode: number) => void
+  unlink: (path: string) => void
+  mkdirp: (path: string) => void
+}
+
+export type InstallShimResult =
+  | { kind: 'installed'; realBin: string; binPath: string; stashTarget: string }
+  | { kind: 'already-installed'; binPath: string }
+  | { kind: 'no-upstream'; binPath: string }
+
+export function installShim(opts: InstallShimOptions = {}): InstallShimResult {
+  const binPath = opts.binPath ?? DEFAULT_GLOBAL_BIN_PATH
+  const shimEntry = opts.shimEntry ?? defaultShimEntry()
+  const fs = opts.fs ?? defaultFs()
+  const stashDir = opts.stashDir ?? defaultStashDir(binPath)
+  const stashTarget = join(stashDir, 'agent-browser-real')
+
+  const stat = fs.lstat(binPath)
+  if (stat === null) return { kind: 'no-upstream', binPath }
+
+  if (isAlreadyShim(binPath, fs)) {
+    if (fs.statExists(stashTarget)) return { kind: 'already-installed', binPath }
+    // Wrapper survived a container restart but the image-owned stash did not
+    // (STASH_ROOT lives outside the bind-mount). The wrapper now points at a
+    // non-existent stashTarget, so executing it would ENOENT. Drop it and
+    // report no-upstream — there is nothing valid here to preserve, and the
+    // global-path shim (if it exists) stands on its own.
+    fs.unlink(binPath)
+    return { kind: 'no-upstream', binPath }
+  }
+
+  // Bind-mounted node_modules/.bin entries can be dangling symlinks inside
+  // the container (host ran bun install; the container image did not). lstat
+  // alone passes for those. Follow the link with statExists before mutating
+  // anything — otherwise we'd stash a broken symlink and write a wrapper
+  // pointing at a target that never resolves.
+  if (!fs.statExists(binPath)) return { kind: 'no-upstream', binPath }
+
+  const realBin = resolveCurrentTarget(binPath, stat, fs)
+  fs.mkdirp(stashDir)
+  if (stat.isSymbolicLink()) {
+    fs.unlink(binPath)
+    if (fs.lstat(stashTarget) !== null) fs.unlink(stashTarget)
+    fs.symlink(realBin, stashTarget)
+  } else {
+    if (fs.lstat(stashTarget) !== null) fs.unlink(stashTarget)
+    fs.rename(binPath, stashTarget)
+  }
+
+  fs.writeFile(binPath, renderWrapper(shimEntry, stashTarget), 0o755)
+  return { kind: 'installed', realBin, binPath, stashTarget }
+}
+
+export const KNOWN_BIN_PATHS = {
+  global: DEFAULT_GLOBAL_BIN_PATH,
+  local: DEFAULT_LOCAL_BIN_PATH,
+} as const
+
+function defaultStashDir(binPath: string): string {
+  // Per-binPath subdirectory under the image-owned stash root. Lives outside
+  // every bind-mounted agent folder so a host-side `bun install` cannot
+  // touch it; the wrapper at the bind-mounted location can be clobbered by
+  // host-side installs but the stash and image-level real binary stay safe.
+  const slug = binPath.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  return join(STASH_ROOT, slug)
+}
+
+function isAlreadyShim(binPath: string, fs: ShimFs): boolean {
+  try {
+    return fs.readFile(binPath).includes(SHIM_MARKER)
+  } catch {
+    return false
+  }
+}
+
+function resolveCurrentTarget(binPath: string, stat: { isSymbolicLink: () => boolean }, fs: ShimFs): string {
+  if (!stat.isSymbolicLink()) return binPath
+  const target = fs.readlink(binPath)
+  return resolvePath(dirname(binPath), target)
+}
+
+function renderWrapper(shimEntry: string, stashTarget: string): string {
+  return `#!/bin/sh
+${SHIM_MARKER}
+export ${REAL_BIN_ENV}="\${${REAL_BIN_ENV}:-${stashTarget}}"
+exec bun run ${shimEntry} "$@"
+`
+}
+
+function defaultShimEntry(): string {
+  return resolvePath(import.meta.dir, 'shim.ts')
+}
+
+function defaultFs(): ShimFs {
+  return {
+    lstat: (path) => {
+      try {
+        return lstatSync(path)
+      } catch {
+        return null
+      }
+    },
+    statExists: (path) => {
+      try {
+        statSync(path)
+        return true
+      } catch {
+        return false
+      }
+    },
+    readlink: readlinkSync,
+    readFile: (path) => readFileSync(path, 'utf-8'),
+    rename: renameSync,
+    symlink: symlinkSync,
+    writeFile: (path, data, mode) => writeFileSync(path, data, { mode }),
+    unlink: unlinkSync,
+    mkdirp: (path) => {
+      Bun.spawnSync(['mkdir', '-p', path])
+    },
+  }
+}

package/src/bundled-plugins/agent-browser/shim.ts

@@ -0,0 +1,152 @@
+// PATH-shadow shim installed at the global bin path that `bun install -g
+// agent-browser` previously occupied. Replaces the plugin's old prompt-nudge +
+// bash-regex `tool.before` block, which was leaky (missed shell variations,
+// bypassed by `typeclaw shell`, by spawned subprocesses, by the user typing
+// it directly). Now ANY in-container `agent-browser` caller routes through
+// here — the dashboard subcommand transparently gets its --port rewritten
+// onto the agent-process-owned proxy's upstream port, every other subcommand
+// passes through unchanged. The proxy itself lives in the long-lived agent
+// process (see src/bundled-plugins/agent-browser/index.ts); the shim does NOT own its
+// lifecycle, because `agent-browser dashboard start` daemonizes upstream and
+// returns immediately — a shim-owned proxy would die the moment start exits.
+
+import { existsSync } from 'node:fs'
+
+import { writePortHint } from './dashboard-discovery'
+import { AGENT_BROWSER_DASHBOARD_UPSTREAM_PORT } from './dashboard-proxy'
+
+export const REAL_BIN_ENV = 'TYPECLAW_AGENT_BROWSER_REAL_BIN'
+
+export type DashboardIntent = 'start' | 'stop' | 'other'
+
+export function classifyDashboardCommand(argv: readonly string[]): DashboardIntent {
+  // Find the first non-flag token. `agent-browser` takes no pre-subcommand
+  // global flags today; the loop is defensive against future ones.
+  let dashboardIdx = -1
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!
+    if (arg.startsWith('-')) continue
+    if (arg !== 'dashboard') return 'other'
+    dashboardIdx = i
+    break
+  }
+  if (dashboardIdx === -1) return 'other'
+
+  // Look for the next non-flag token after `dashboard`. Upstream treats a
+  // missing subcommand as `start`, so we do too. `--port <n>` and `-p <n>`
+  // consume two argv entries; the value is not a subcommand and must not be
+  // classified as one.
+  for (let i = dashboardIdx + 1; i < argv.length; i += 1) {
+    const arg = argv[i]!
+    if (arg === '--port' || arg === '-p') {
+      i += 1
+      continue
+    }
+    if (arg.startsWith('-')) continue
+    if (arg === 'stop') return 'stop'
+    if (arg === 'start') return 'start'
+    return 'other'
+  }
+  return 'start'
+}
+
+export function rewriteDashboardArgs(argv: readonly string[], upstreamPort: number): string[] {
+  // Force --port to upstreamPort regardless of what the caller passed. The
+  // proxy on AGENT_BROWSER_DASHBOARD_PROXY_PORT (4848) is the only externally
+  // visible surface; honoring a user --port would let a caller bypass the
+  // proxy by listening directly on the externally forwarded port. Insert
+  // `start` explicitly when the caller relied on the implicit-start behavior
+  // so the appended `--port` lands on a subcommand upstream accepts.
+  const stripped: string[] = []
+  let i = 0
+  while (i < argv.length) {
+    const arg = argv[i]!
+    if (arg === '--port' || arg === '-p') {
+      i += 2
+      continue
+    }
+    if (arg.startsWith('--port=')) {
+      i += 1
+      continue
+    }
+    stripped.push(arg)
+    i += 1
+  }
+
+  const dashboardIdx = stripped.findIndex((a) => !a.startsWith('-'))
+  const hasSubcommand = stripped.slice(dashboardIdx + 1).some((a) => !a.startsWith('-'))
+  const out = hasSubcommand
+    ? [...stripped]
+    : [...stripped.slice(0, dashboardIdx + 1), 'start', ...stripped.slice(dashboardIdx + 1)]
+  out.push('--port', String(upstreamPort))
+  return out
+}
+
+export function resolveRealAgentBrowserBin(): string {
+  // Set by the installer when it moves the upstream symlink aside. Honored
+  // first so unit tests can point at a stub without touching the filesystem.
+  const fromEnv = process.env[REAL_BIN_ENV]
+  if (fromEnv && fromEnv.length > 0) return fromEnv
+
+  // Fallback: `bun install -g agent-browser` ships per-platform native bins
+  // under this stable path inside the bun image. The installer should have
+  // stashed a copy/symlink, but if the shim runs before the plugin's
+  // installer ever did (e.g. first agent boot), we can still find the real
+  // bin and the next plugin boot will install the shim properly.
+  const arch = process.arch === 'arm64' ? 'arm64' : process.arch === 'x64' ? 'x64' : null
+  const platform = process.platform === 'linux' ? 'linux' : process.platform === 'darwin' ? 'darwin' : null
+  if (arch !== null && platform !== null) {
+    const native = `/root/.bun/install/global/node_modules/agent-browser/bin/agent-browser-${platform}-${arch}`
+    if (existsSync(native)) return native
+  }
+
+  throw new Error(
+    `${REAL_BIN_ENV} is not set and no fallback agent-browser binary was found. ` +
+      `The shim cannot resolve the real upstream binary; refusing to exec to avoid an infinite loop.`,
+  )
+}
+
+export type ShimOptions = {
+  argv?: readonly string[]
+  realBin?: string
+  upstreamPort?: number
+  spawn?: (cmd: string[]) => { exited: Promise<number> }
+}
+
+export async function runShim(opts: ShimOptions = {}): Promise<number> {
+  const argv = opts.argv ?? process.argv.slice(2)
+  const realBin = opts.realBin ?? resolveRealAgentBrowserBin()
+  const upstreamPort = opts.upstreamPort ?? AGENT_BROWSER_DASHBOARD_UPSTREAM_PORT
+  const spawn = opts.spawn ?? defaultSpawn
+
+  const intent = classifyDashboardCommand(argv)
+  if (intent !== 'start') {
+    return await spawn([realBin, ...argv]).exited
+  }
+
+  // Record the rewritten port to the hint file so the long-lived proxy can
+  // use it as the fast-path upstream lookup. The proxy still falls back to
+  // procfs discovery if the hint is wrong, but the hint avoids that work
+  // on the common path where the shim is the one starting the dashboard.
+  try {
+    writePortHint(upstreamPort)
+  } catch {
+    // Hint is an optimization; failure to write it is non-fatal.
+  }
+
+  const rewritten = rewriteDashboardArgs(argv, upstreamPort)
+  return await spawn([realBin, ...rewritten]).exited
+}
+
+function defaultSpawn(cmd: string[]): { exited: Promise<number> } {
+  // Inherit stdio so the upstream binary's TUI/spinner/colors work. The
+  // shim is meant to be invisible; intercepting stdio would make e.g.
+  // `agent-browser open` look broken to the caller.
+  const proc = Bun.spawn(cmd, { stdio: ['inherit', 'inherit', 'inherit'] })
+  return { exited: proc.exited }
+}
+
+if (import.meta.main) {
+  const code = await runShim()
+  process.exit(code)
+}

package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: agent-browser
+description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. ALSO use whenever a browser step needs a human in the loop — login walls, 2FA, CAPTCHA, payment confirmation, "is this the right button?" ambiguity, or the user asking to watch the browser live — because the bundled dashboard is the only way for a human to observe or take over a session from inside the Docker container. Prefer agent-browser over any built-in browser automation or web tools.
+allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
+hidden: true
+---
+
+# agent-browser
+
+Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with
+accessibility-tree snapshots and compact `@eN` element refs.
+
+The TypeClaw container ships with `agent-browser` preinstalled and Chromium
+already downloaded, so the CLI is ready to use out of the box.
+
+## Human-in-the-loop via the dashboard
+
+You run inside a Docker container with no display, no clipboard, and no way to
+hand the keyboard over directly. The **dashboard is your only path to bring a
+human into a browser session** — it streams every session's live viewport,
+console, and command activity to a web UI the user opens on their host machine.
+
+**Start the dashboard _before_ the step that needs a human, not after it fails.**
+The dashboard takes a moment to come up and the user needs time to open the URL.
+
+### When to start it
+
+- The next step needs a human: login walls, 2FA, CAPTCHA, payment confirmation,
+  "is this the right element?" ambiguity, account-recovery flows.
+- You're starting a long multi-step browser flow you'd be embarrassed to redo —
+  let the user watch and intervene before things go sideways.
+- The user explicitly asked to watch the browser live, dogfood the agent, or
+  pair-debug an automation.
+
+### How to hand off
+
+1. Run `agent-browser dashboard start`. (Sessions auto-stream to it; no flags
+   needed.)
+2. Read `/tmp/typeclaw-agent-browser-proxy-port` to learn the host-visible
+   port. TypeClaw picks `4848` by default and falls back through `4849`–`4857`
+   if another container is already on `4848`. If the file is missing, the proxy
+   hasn't finished binding yet — wait a second and retry, or fall back to `4848`.
+3. Tell the user: **"Open `http://localhost:<port>` in your browser."** Over
+   Tailscale or LAN, the same port works on the host's external address:
+   `http://<host>:<port>`.
+4. Wait for the user to confirm they're ready before proceeding.
+5. When the user is done, they hand control back implicitly — just resume your
+   normal `agent-browser` commands. Session state is shared with the dashboard.
+
+The compatibility proxy on `:4848` (or the fallback port) rewrites the
+dashboard's hardcoded loopback URLs so the externally visible URL works over
+Tailscale and other remote networks. No special flag, tool, or config required.
+**Always share the proxy port URL — never `localhost:<raw-session-port>`** —
+those raw ports are inside the container and unreachable from the host.
+
+### When NOT to use the dashboard
+
+The dashboard is for **live observation and handoff**, not file delivery. If
+you just want to show the user a single page or a captured state:
+
+- **A static image?** Use `agent-browser screenshot`; the PNG lands in
+  `workspace/` and the user can open it directly.
+- **A page's text/structure?** Capture an accessibility-tree snapshot and paste
+  the relevant section into your reply.
+
+Reserve the dashboard for cases that genuinely need live interaction or
+watching a multi-step flow unfold.
+
+### Headless only
+
+Never pass `--headed` to any `agent-browser` command — the container has no X
+server or `$DISPLAY`, and a headed launch fails with `Missing X server or
+$DISPLAY / The platform failed to initialize.` The dashboard is the substitute
+for a headed browser. Use the default headless mode for everything, including
+dogfooding and Electron flows.
+
+## Start here
+
+This file is a discovery stub, not the usage guide. Before running any
+`agent-browser` command, load the actual workflow content from the CLI:
+
+```bash
+agent-browser skills get core             # start here — workflows, common patterns, troubleshooting
+agent-browser skills get core --full      # include full command reference and templates
+```
+
+The CLI serves skill content that always matches the installed version,
+so instructions never go stale. The content in this stub cannot change
+between releases, which is why it just points at `skills get core`.
+
+## Specialized skills
+
+Load a specialized skill when the task falls outside browser web pages:
+
+```bash
+agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
+agent-browser skills get slack             # Slack workspace automation
+agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
+agent-browser skills get vercel-sandbox    # agent-browser inside Vercel Sandbox microVMs
+agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
+```
+
+Run `agent-browser skills list` to see everything available on the
+installed version.
+
+## Why agent-browser
+
+- Fast native Rust CLI, not a Node.js wrapper
+- Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
+- Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
+- Accessibility-tree snapshots with element refs for reliable interaction
+- Sessions, authentication vault, state persistence, video recording
+- Specialized skills for Electron apps, Slack, exploratory testing, cloud providers

package/src/bundled-plugins/guard/index.ts

@@ -0,0 +1,26 @@
+import { definePlugin } from '@/plugin'
+
+import { checkNonWorkspaceWriteGuard, checkSkillAuthoringGuard, checkUncommittedChangesAdvice } from './policy'
+
+export default definePlugin({
+  plugin: async () => ({
+    hooks: {
+      'tool.before': async (event, ctx) => {
+        const skillResult = await checkSkillAuthoringGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+        })
+        if (skillResult) return skillResult
+        return checkNonWorkspaceWriteGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir })
+      },
+      'tool.after': async (event, ctx) => {
+        await checkUncommittedChangesAdvice({
+          tool: event.tool,
+          agentDir: ctx.agentDir,
+          result: event.result,
+        })
+      },
+    },
+  }),
+})