# src/tools/ - Agent Guidelines

Tool development patterns. Extends `src/AGENTS.md`.

## Overview

70 `opendevbrowser_*` tools. All thin wrappers: validate -> delegate -> respond.
Hub mode is enforced via `ensureHub` in `src/tools/index.ts` to rebind remote managers and avoid local relay fallback.

## Tool Structure

```typescript
// Pattern: every tool follows this
export function createFooTool(deps: ToolDeps): ToolDefinition {
  return {
    name: 'opendevbrowser_foo',
    description: 'One-line description',
    args: { ... },  // Zod schema fields
    execute: async (params, context) => {
      // 1. Validate (already done by Zod)
      // 2. Delegate to manager
      const result = await deps.manager.foo(params);
      // 3. Shape response
      return { success: true, data: result };
    }
  };
}
```

## File Organization

| Category | Tools |
|------|-------|
| Session | launch, connect, disconnect, status, cookie_import, cookie_list |
| Navigation | goto, wait, snapshot |
| Interaction | click, hover, press, check, uncheck, type, select, scroll, scroll_into_view, upload |
| Targets | targets_list, target_use, target_new, target_close |
| Pages | page, list, close |
| DOM | dom_get_html, dom_get_text, get_attr, get_value, is_visible, is_enabled, is_checked |
| Browser capture | screenshot, screencast_start, screencast_stop |
| Desktop observation | desktop_status, desktop_windows, desktop_active_window, desktop_capture_desktop, desktop_capture_window, desktop_accessibility_snapshot |
| Devtools | session_inspector, console_poll, network_poll, perf, dialog |
| Annotation | annotate |
| Canvas | canvas |
| Export | clone_page, clone_component |
| Skills | skill_list, skill_load |
| Run | run (multi-action) |
| Provider workflows | research_run, shopping_run, product_video_run, inspiredesign_run |
| Prompting | prompting_guide |

## Where Logic Lives

| Layer | Responsibility |
|-------|----------------|
| `tools/` | Input validation, response shaping |
| `browser/` | Session lifecycle, CDP orchestration |
| `canvas/` | Document store, repo persistence, framework-adapter-backed code-sync helpers |
| `providers/` | Workflow runtime, blocker handling, browser fallback |
| `snapshot/` | AX-tree capture, ref resolution |
| `relay/` | Extension communication |

**Tools NEVER own business logic.** They delegate.

Keep tool names and counts in sync with `src/tools/index.ts`, `docs/CLI.md`, and `docs/SURFACE_REFERENCE.md`.
Workflow tool examples and notes in generated public surface are owned by `src/public-surface/source.ts`; regenerate manifests instead of editing generated files. Prefer omitted workflow output roots, or `--output-dir .opendevbrowser` when an explicit workflow root is required.
Inspiredesign tool notes that mention FFmpeg/FFprobe must preserve the same contract in `src/public-surface/source.ts`: optional host tools, no bundled static binaries or default downloads, env then config then `PATH` resolution, `status-capabilities.host.mediaAnalysis` as diagnostic/preflight only, missing binaries degrading `media-analysis.json` only, and `pin-media-index.json` plus `motion-evidence.json` as authority surfaces; generated manifests are regenerated only.
When inventory-affecting tools change, re-run `node scripts/docs-drift-check.mjs` and update release evidence docs.
When `opendevbrowser_canvas` subcommands change, also sync `docs/CLI.md`, `docs/SURFACE_REFERENCE.md`, `docs/ARCHITECTURE.md`, `docs/DESIGN_CANVAS_TECHNICAL_SPEC.md`, `docs/CANVAS_BIDIRECTIONAL_CODE_SYNC_TECHNICAL_SPEC.md`, `docs/CANVAS_ADAPTER_PLUGIN_CONTRACT.md`, and the relevant `AGENTS.md` files such as `src/browser/AGENTS.md` and `src/canvas/AGENTS.md`. If validator behavior changes, keep `scripts/canvas-competitive-validation.mjs` aligned in the same pass.

## Response Pattern

```typescript
// Success
{ success: true, sessionId: '...', warnings?: [...] }

// Error
{ error: 'message', code: 'ERROR_CODE' }
```

## Adding a Tool

1. Create function in appropriate file (by category)
2. Define Zod schema for parameters
3. Delegate to existing manager method
4. Add to `createTools()` in `index.ts`
5. Add tests in `tests/`

## Anti-Patterns

| Never | Do Instead |
|-------|------------|
| Business logic in tool | Delegate to manager |
| `any` in parameters | Define Zod schema |
| Direct CDP calls | Use BrowserManager/ScriptRunner |
| Inline error strings | Use consistent error codes |
