ops

Documentation

Overview

Package ops defines the canonical catalog of ghostchrome agent operations.

This is the single source of truth for op names, summaries, argument shapes, and which surfaces expose each op. The three live surfaces are:

• "jsonl" — cmd/agent.go JSONL loop (dispatch switch)
• "mcp" — engine/mcp/tools.go (registerTools)
• "ai" — engine/ai/tools.go (ToolSpecs)

IMPORTANT: this file is additive. The three surface files are NOT modified to consume this registry — that refactor is a separate, future task. The registry is used today for:

• generating contracts/commands.json (go:generate)
• the parity test (internal/ops/parity_test.go)

Index

• type Arg
• type ArgType
• type Op
  • func Catalog() []Op

Types

type Arg

type Arg struct {
	Name     string  `json:"name"`
	Type     ArgType `json:"type"`
	Required bool    `json:"required"`
	// Description is a short human-readable note (optional).
	Description string `json:"description,omitempty"`
}

Arg describes one argument accepted by an op.

type ArgType

type ArgType string

ArgType describes the JSON type of an argument.

const (
	ArgString  ArgType = "string"
	ArgInteger ArgType = "integer"
	ArgNumber  ArgType = "number"
	ArgBoolean ArgType = "boolean"
	ArgArray   ArgType = "array"
	ArgObject  ArgType = "object"
)

type Op

type Op struct {
	Name    string `json:"name"`
	Summary string `json:"summary"`
	Args    []Arg  `json:"args"`
	// Surfaces lists which protocol surfaces expose this op.
	// Known values: "jsonl", "mcp", "ai".
	Surfaces []string `json:"surfaces"`
}

Op is one entry in the canonical operation catalog.

func Catalog

func Catalog() []Op

Catalog returns the full canonical list of ghostchrome agent operations, sorted alphabetically by name.

Surface coverage notes (divergences are intentional, not bugs):

• "snapshot" is MCP-only: it bundles navigate+extract+errors into one call to amortize the per-tool token cost in MCP's tools/list. JSONL has dedicated ops for each concern.
• "done" is AI-only: it is a meta-tool that signals goal completion to the Anthropic tool-use loop. It has no CDP side-effect and no JSONL/MCP equivalent.
• "wait_for" is MCP-only: it extends the basic "wait" op with text-match and a timeout_ms parameter. The JSONL surface uses "wait" with selector/ms.
• "fill" and "init" and "close" are JSONL-only: fill is a convenience multi-field wrapper; init/close manage session lifecycle that MCP/AI handle implicitly.
• "extract" and "hover" and "scroll_by"/"scroll_to" appear in JSONL and AI but not MCP (snapshot replaces extract in MCP; hover/scroll are available via eval in MCP).
• "errors" and "url" appear in JSONL and AI but not MCP (covered by snapshot).
• "screenshot" appears in JSONL and MCP but not AI.