inspector

type AppPreview struct {
	// URI is the App's ui:// resource URI.
	URI string `json:"uri"`
	// Name is the App's display name (the resource Name, falling back to URI).
	Name string `json:"name"`
	// HTML is the App's HTML document, read from the server's ui:// resource.
	HTML string `json:"html"`
}

type AppSource func(ctx context.Context) ([]AppPreview, error)

type ContractsSource func() json.RawMessage

type ElicitationRequest struct {
	// TaskID is the id of the task the elicitation answers. Required.
	TaskID string `json:"taskId"`
	// Data is the user's reply, opaque to the inspector — the receiving
	// handler decodes it against its own contract. May be absent when
	// Declined is true.
	Data json.RawMessage `json:"data,omitempty"`
	// Declined is the explicit "user declined to answer" signal. The
	// MCP Tasks experimental spec carries this through as the
	// elicited-input's declined flag.
	Declined bool `json:"declined,omitempty"`
}

type ElicitationResponse struct {
	// TaskID echoes the id of the task the elicitation was delivered to.
	TaskID string `json:"taskId"`
	// Delivered is true when the attached server accepted the
	// elicitation; false (with a non-empty Error) when the server
	// refused.
	Delivered bool `json:"delivered"`
	// Error is the server's typed error message when Delivered is
	// false. Absent on a successful delivery.
	Error string `json:"error,omitempty"`
}

type Elicitor func(ctx context.Context, req ElicitationRequest) (*ElicitationResponse, error)

type FixtureKind string

type FixtureSource func() ([]ProjectFixture, error)

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

type InvokeRequest struct {
	// Tool is the registered tool name to call. Required.
	Tool string `json:"tool"`
	// Arguments is the typed input the handler receives. The wire shape is
	// json.RawMessage so the inspector never decodes user input into a runtime
	// struct (P3 — no raw protocol struct leaks; the runtime/server schema
	// validates the payload at the catalog edge before the handler runs).
	Arguments json.RawMessage `json:"arguments"`
}

type InvokeResponse struct {
	// Content is the MCP CallToolResult content[]: text and any non-structured
	// content parts the tool emitted. Marshalled as JSON so the inspector can
	// surface a faithful view in its result viewer.
	Content json.RawMessage `json:"content,omitempty"`
	// StructuredContent is the tool's typed structured payload — the value the
	// App-frame's pushToolResult path consumes. May be omitted (a tool that
	// emits only text content).
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	// IsError is the MCP CallToolResult.isError flag: a tool-level error
	// reported to the host rather than a protocol-level error.
	IsError bool `json:"isError,omitempty"`
}

type Options struct {
	// Addr is the loopback listen address. Empty selects [defaultAddr] (an
	// OS-assigned loopback port). A non-loopback or wildcard address is rejected
	// by [New] with [ErrNonLoopbackBind].
	Addr string

	// ServerInfo is the identity of the attached MCP server, surfaced read-only
	// in the inspector UI. The zero value is tolerated (an unknown server).
	ServerInfo ServerInfo

	// Relay sources the obs/v1 SSE stream and the JSON-RPC log the inspector
	// relays to its UI. When nil, the relay endpoints report an empty stream —
	// the inspector still serves its UI (the four-state empty state).
	Relay *Relay

	// Assets is the embedded web/inspector frontend (its built dist/ tree). When
	// nil, the inspector serves a minimal built-in placeholder so the backend is
	// usable before `vite build` has run — the Go build never depends on the
	// frontend being built.
	Assets fs.FS

	// Verdicts is the read-only source for the inspector's Verdicts panel —
	// contract-drift, schema-validation, and spec-compliance results (RFC §12).
	// When nil, `GET /api/verdicts` returns an empty array and the UI renders
	// its four-state empty state. Use [VerdictsFromValidate] to source it from
	// the `dockyard validate` engine.
	Verdicts VerdictSource

	// Contracts is the read-only source for the inspector's generated tool
	// contracts — the JSON array the fixture switcher derives its fixtures
	// from (RFC §12, §6 — P1, contract-first). When nil, `GET /api/contracts`
	// returns an empty array and the Fixtures/Tools panels render their
	// four-state empty state. The source returns the contracts as a JSON
	// array of `{name, description, inputSchema, outputSchema}` objects.
	Contracts ContractsSource

	// Apps is the read-only source for the inspector's App-preview frame — the
	// attached server's ui:// App resources, read via a read-only resources/read
	// (RFC §12 line 711 — the inspector renders the server's Apps; D-103). When
	// nil, `GET /api/apps` answers with an empty array and the App-frame renders
	// its "No App attached" empty state. Use [AppsFromServer] to source it from
	// a running MCP server's ui:// resources.
	Apps AppSource

	// Fixtures is the read-only source for the inspector's on-disk fixture
	// loader (RFC §12, Phase 24 / D-126). When nil, `GET /api/fixtures` answers
	// with an empty array and the Fixtures switcher falls back to its
	// schema-derived synthetic fixtures (the Phase 23 default). Use
	// [FixturesFromDir] to source it from the developer's project directory.
	Fixtures FixtureSource

	// Invoker performs one operator-initiated tools/call against the attached
	// MCP server (RFC §12, P4; D-131). When nil, `POST /api/tools/invoke`
	// answers 503 — the inspector is detached. Use [ToolsFromServer] to source
	// it from a running MCP server. D-131 extends D-099 + D-103: the inspector
	// additionally issues real tools/call to the attached server when an
	// operator initiates it through the UI; still within P4 (the inspector is
	// the lone client-shaped component, dev-mode-gated, localhost-bound; the
	// operator is the one driving the write — not arbitrary off-localhost
	// execution).
	Invoker ToolInvoker

	// Elicitor delivers one operator-initiated elicitation-response to the
	// attached MCP server (Phase 25 / D-134). When nil,
	// `POST /api/tasks/elicitation` answers 503 — the inspector is detached or
	// the operator has not wired an elicitor. Use [ElicitationFromServer] to
	// source it from a running MCP server. D-134 extends D-131: the inspector
	// additionally forwards an App's elicitation-response notification to the
	// attached server's `tasks/result` endpoint, on the operator's
	// deliberate "Approve" / "Reject" click in the App preview. Still within
	// P4 (localhost-bound, operator-driven, no long-lived client).
	Elicitor Elicitor

	// Logger is the structured logger. When nil, a no-op logger is used.
	Logger *slog.Logger
}

type ProjectFixture struct {
	// Tool is the tool name this fixture belongs to (e.g. "create_chart").
	Tool string `json:"tool"`
	// Kind is one of the six FixtureKind values.
	Kind FixtureKind `json:"kind"`
	// Description is the human-readable summary from the JSON.
	Description string `json:"description,omitempty"`
	// State is the UI state the fixture stands for ("ready"/"empty"/...).
	State string `json:"state"`
	// Input is the model-side input — surfaced for the inspector's RPC log
	// and the integration test, never used by the App's renderer.
	Input map[string]any `json:"input,omitempty"`
	// StructuredContent is the payload the App's dispatcher receives. When
	// the on-disk fixture carries `output_override`, it is used verbatim;
	// otherwise the loader derives it from `input` by pinning `kind` and
	// `state` so the App's discriminator routes correctly.
	StructuredContent map[string]any `json:"structuredContent"`
}

type RPCDirection string

type RPCEntry struct {
	// Seq is a monotonic sequence number, assigned by the relay on append.
	Seq int64 `json:"seq"`
	// Timestamp is when the entry was logged, in UTC.
	Timestamp time.Time `json:"timestamp"`
	// Direction is inbound (toward the server) or outbound (from it).
	Direction RPCDirection `json:"direction"`
	// Method is the JSON-RPC method (e.g. "tools/call", "ui/initialize"). It is
	// empty for a response entry.
	Method string `json:"method,omitempty"`
	// Payload is the JSON-RPC message payload, JSON-encoded.
	Payload json.RawMessage `json:"payload,omitempty"`
}

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

type ServerInfo struct {
	// Name is the connected server's name.
	Name string `json:"name"`
	// Version is the connected server's version.
	Version string `json:"version"`
	// Transport is the MCP transport in use: stdio | http | inmem.
	Transport string `json:"transport"`
}

type ToolInvoker func(ctx context.Context, req InvokeRequest) (*InvokeResponse, error)

type Verdict struct {
	// Check is the verdict's check class: "manifest", "schema",
	// "spec-compliance", "stale-codegen", … — the validate Check taxonomy.
	Check string `json:"check"`
	// Severity is the rendered tone: "ok" | "warn" | "error".
	Severity string `json:"severity"`
	// Message is the human-facing, actionable description.
	Message string `json:"message"`
}

type VerdictSource func() []Verdict