plugin

type CachedSchema struct {
	Version       int             `json:"version"`
	SpecHash      string          `json:"spec_hash"`
	Capabilities  map[string]bool `json:"capabilities"`
	Tools         []CachedTool    `json:"tools"`
	LastValidated time.Time       `json:"last_validated"`
}

type CachedTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Schema      json.RawMessage `json:"schema"`
	ReadOnly    bool            `json:"read_only"`
}

type Client struct {
	// contains filtered or unexported fields
}

type Failure struct {
	Name      string
	Transport string
	Error     string
}

type Host struct {
	// contains filtered or unexported fields
}

type Prompt struct {
	Name        string      // "mcp__<server>__<prompt>" — the slash-command body
	Server      string      // owning server name
	Raw         string      // original prompt name for prompts/get
	Description string      // human-readable summary
	Args        []PromptArg // declared arguments, in order
	// contains filtered or unexported fields
}

type PromptArg struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
}

type Recommendation struct {
	Demote bool
	P99    time.Duration
	Reason string
}

type Resource struct {
	Server      string // owning server name
	URI         string // canonical resource uri
	Name        string // human-readable label
	Description string
	MimeType    string
}

type ServerStatus struct {
	Name      string
	Transport string
	Tools     int
	Prompts   int
	Resources int
	ToolList  []ToolInfo
}

type SessionExpiredError struct {
	Server string
	Err    error
}

type Spec struct {
	Name    string
	Type    string
	Command string
	Args    []string
	Env     map[string]string
	URL     string
	Headers map[string]string
	// Dir, when set, is the working directory of a stdio subprocess. Empty means
	// inherit fairpeer's cwd (the default for user-configured plugins). It exists
	// for cwd-aware servers like CodeGraph, which detect the project from the
	// directory they are launched in — they must be pinned to the project root.
	Dir string
	// Stderr optionally mirrors plugin subprocess stderr output. Stderr is always
	// captured in a bounded buffer for failure diagnostics; nil keeps it out of
	// the terminal so child logs cannot corrupt interactive UIs.
	Stderr io.Writer
	// ReadOnlyToolNames marks trusted raw MCP tool names as read-only even when
	// the server omits annotations.readOnlyHint. It is for first-party adapters
	// with known semantics; user-configured plugins should rely on MCP metadata.
	ReadOnlyToolNames map[string]bool
	// ExposeToolNames, when non-empty, is a whitelist of model-visible tool names
	// (post-namespacing, e.g. "mcp__codegraph__context") that the main loop's
	// schema advertises; every other tool from this server is hidden (still
	// callable by name via run_skill/subagents, but kept out of the system prompt
	// to save tokens). Empty (the default) exposes all tools — the legacy
	// behavior. Used by first-party adapters like CodeGraph to surface a compact
	// 2–3 tool surface while keeping the rest reachable on demand.
	ExposeToolNames map[string]bool
	// StripRawPrefix, when non-empty, removes this prefix from each MCP tool's
	// raw name before namespacing. For example, StripRawPrefix="codegraph_" turns
	// "codegraph_context" into "context", yielding "mcp__codegraph__context"
	// instead of the redundant "mcp__codegraph__codegraph_context". The original
	// raw name is preserved for MCP protocol calls.
	StripRawPrefix string
	// LowPriority runs a stdio subprocess below normal scheduling priority, for
	// background indexers (CodeGraph) that must not starve the user's machine.
	LowPriority bool
	// CallTimeout caps how long a single MCP JSON-RPC call may take when the
	// caller's context has no deadline. Zero uses the default (60s). Prevents a
	// slow or hung MCP server from blocking the agent indefinitely.
	CallTimeout time.Duration
	// ServerRisk is the config-declared risk class for ALL tools on this server
	// (SPEC v2 §3.2A). Raw string ("read"/"write_local"/"exec"/"external"); the
	// boot layer translates it into per-tool RiskOverrides on the permission Gate.
	// Empty = "external" (safe default: MCP tools prompt). Kept as a string here
	// so this package need not depend on internal/permission.
	ServerRisk string
}

type StartPolicy struct {
	// PerPluginTimeout caps how long a single plugin's handshake (start +
	// initialize + listTools + listPrompts/Resources) may take. Zero disables.
	// Exceeded plugins are recorded as failures and, when AbortOnError is set,
	// tear down the whole batch with the timeout as the cause.
	PerPluginTimeout time.Duration

	// Concurrency caps how many handshakes run at once. Zero or negative means
	// no cap (every plugin gets a goroutine immediately). A small cap prevents
	// process storms / FD exhaustion when many MCP servers are configured.
	Concurrency int

	// AbortOnError makes any single failure tear down the partial batch and
	// return an error (StartAll semantics). When false, failures are recorded
	// on the host and other plugins keep going (StartAvailable semantics).
	AbortOnError bool
}

type StartupStats struct {
	Version   int       `json:"version"`
	SamplesMs []int64   `json:"samples_ms"`
	LastSeen  time.Time `json:"last_seen"`
}

type ToolInfo struct {
	Name        string
	Description string
}