visor/docs/pluggable.md at main · probelabs/visor · GitHub

257 lines (199 loc) · 5.33 KB

Pluggable Architecture

Visor supports multiple provider types. You can also add custom providers.

Built-in Providers: a2a, ai, mcp, utcp, command, script, http, http_input, http_client, log, memory, noop, github, human-input, workflow, git-checkout, claude-code

Custom Provider Skeleton (TypeScript)

class CustomCheckProvider {
  name = 'custom';
  async run(input) {
    // ... implement your logic
    return { issues: [] };
  }
}

Built-in Providers

A2A Provider (`type: a2a`)

Call external A2A-compatible agents and collect their responses. Supports agent card discovery, multi-turn conversations, and JavaScript output transforms.

steps:
  compliance-check:
    type: a2a
    agent_url: "http://compliance-agent:9000"
    message: "Review PR #{{ pr.number }}: {{ pr.title }}"
    blocking: true
    timeout: 60000

AI Provider (`type: ai`)

Execute AI-powered analysis using Google Gemini, Anthropic Claude, OpenAI, or AWS Bedrock.

steps:
  security:
    type: ai
    prompt: "Review for security issues"
    schema: code-review

MCP Provider (`type: mcp`)

Call MCP (Model Context Protocol) tools directly via stdio, SSE, or HTTP transports. Unlike AI provider MCP support, this provider directly invokes MCP tools without an AI model.

steps:
  probe-search:
    type: mcp
    transport: stdio
    command: npx
    args: ["-y", "@probelabs/probe@latest", "mcp"]
    method: search_code
    methodArgs:
      query: "TODO"

UTCP Provider (`type: utcp`)

Call UTCP (Universal Tool Calling Protocol) tools directly via their native protocols. Unlike MCP which requires a running server, UTCP tools publish JSON "manuals" and the client calls them directly over HTTP, CLI, or SSE.

steps:
  api-check:
    type: utcp
    manual: https://api.example.com/utcp
    method: analyze
    methodArgs:
      files: "{{ files | map: 'filename' | join: ',' }}"

UTCP tools can also be exposed to AI agents via ai_mcp_servers:

steps:
  ai-review:
    type: ai
    ai_mcp_servers:
      scanner:
        type: utcp
        manual: https://scanner.example.com/utcp

Command Provider (`type: command`)

Execute shell commands with templating and security controls.

steps:
  lint:
    type: command
    exec: npm run lint

Script Provider (`type: script`)

Execute JavaScript in a secure sandbox with access to PR context, outputs, and memory.

steps:
  analyze:
    type: script
    content: |
      const issues = outputs['lint-check'] || [];
      memory.set('issue_count', issues.length);
      return { total: issues.length };

HTTP Client Provider (`type: http_client`)

Make HTTP requests to external APIs.

steps:
  api-check:
    type: http_client
    url: https://api.example.com/analyze
    method: POST
    body: '{{ pr | json }}'

HTTP Provider (`type: http`)

Send check results to external webhooks.

steps:
  notify:
    type: http
    url: https://webhook.example.com/notify
    method: POST

HTTP Input Provider (`type: http_input`)

Receive and process HTTP webhook input data for use by dependent checks.

steps:
  webhook-data:
    type: http_input
    endpoint: /webhook/incoming

Log Provider (`type: log`)

Log messages for debugging and workflow visibility.

steps:
  debug:
    type: log
    message: "PR #{{ pr.number }}: {{ fileCount }} files changed"

Memory Provider (`type: memory`)

Persistent key-value storage across checks for stateful workflows.

steps:
  init-counter:
    type: memory
    operation: set
    key: retry_count
    value: 0

Noop Provider (`type: noop`)

No-operation provider for command orchestration and dependency triggering.

steps:
  trigger-all:
    type: noop
    depends_on: [check1, check2, check3]

GitHub Provider (`type: github`)

Interact with GitHub API for labels, comments, and status checks.

steps:
  label-pr:
    type: github
    op: labels.add
    values: ["security", "needs-review"]

Human Input Provider (`type: human-input`)

Pause workflow execution to request input from a human user.

steps:
  approval:
    type: human-input
    prompt: "Approve deployment? (yes/no)"

Workflow Provider (`type: workflow`)

Execute reusable workflow definitions as steps.

steps:
  security-scan:
    type: workflow
    workflow: security-scan
    args:
      severity_threshold: high

Git Checkout Provider (`type: git-checkout`)

Checkout code from git repositories using efficient worktree management.

steps:
  checkout:
    type: git-checkout
    ref: "{{ pr.head }}"

Claude Code Provider (`type: claude-code`)

Use Claude Code SDK with MCP tools and advanced agent capabilities.

steps:
  claude-analysis:
    type: claude-code
    prompt: "Analyze code architecture"