ops

type CallerRule ¶

type CallerRule string

CallerRule says which callers an operation with a caller input accepts. A chat caller passes both rules on a desktop-owned operation, because the desktop resolves chats.

ENUM(none, session, session-or-global)

const (
	// CallerRuleNone is a CallerRule of type none.
	CallerRuleNone CallerRule = "none"
	// CallerRuleSession is a CallerRule of type session.
	CallerRuleSession CallerRule = "session"
	// CallerRuleSessionOrGlobal is a CallerRule of type session-or-global.
	CallerRuleSessionOrGlobal CallerRule = "session-or-global"
)

func ParseCallerRule(name string) (CallerRule, error)

func (x CallerRule) AppendText(b []byte) ([]byte, error)

func (x CallerRule) IsValid() bool

func (x CallerRule) MarshalText() ([]byte, error)

func (x CallerRule) String() string

func (x *CallerRule) UnmarshalText(text []byte) error

type Constraint ¶

type Constraint struct {
	Enum     []string
	Min, Max *float64
	// Default is the value an omitted field takes. It is documentation: the
	// handler must treat the zero value the same way.
	Default any
}

Constraint narrows one input field beyond what its Go type says. The MCP schema states it, and the CLI checks it before it calls.

func Range(lo, hi float64) Constraint

type Constraints ¶

type Constraints map[string]Constraint

Constraints is keyed by json field name.

type Effect ¶

type Effect string

Effect classifies what a call changes.

const (
	EffectRead  Effect = "read"
	EffectWrite Effect = "write"
	// EffectExec runs a command the caller supplies.
	EffectExec Effect = "exec"
)

type Error ¶

type Error struct {
	Kind Kind
	Msg  string
}

Error is an error with a Kind.

func Errorf(kind Kind, format string, args ...any) *Error

func (e *Error) Error() string

type Field ¶

type Field struct {
	Name string
	// Type is the field's Go type with any pointer removed. Pointer says
	// whether there was one: an omitted pointer field keeps a stored value.
	Type        reflect.Type
	Pointer     bool
	Description string
	Required    bool
	Constraint
}

Field is one input field with its constraint applied.

func Fields(op Op) ([]Field, error)

func (f Field) Check(v any) error

func (f Field) Kind() reflect.Kind

type Info ¶

type Info struct {
	Name     string
	Resource string
	Verb     string
	// ToolName is the MCP tool name: "<resource>_<verb>".
	ToolName string
	Owner    Owner
	Effect   Effect
	Toolset  Toolset
	Summary  string
	Guidance string
	Args     []string
	Fields   Constraints
	Caller   CallerRule
}

Info is a Spec with its type parameter erased.

func (i Info) Description() string

type Kind ¶

type Kind string

Kind is the error vocabulary every surface maps once. A tool error crosses MCP as text that starts with "<kind>: ".

const (
	KindInvalid         Kind = "invalid"
	KindNotFound        Kind = "not_found"
	KindConflict        Kind = "conflict"
	KindUnavailable     Kind = "unavailable"
	KindUnauthenticated Kind = "unauthenticated"
	KindInternal        Kind = "internal"
)

func ParseKind(msg string) (Kind, bool)

type NoInput ¶

type NoInput struct{}

NoInput is the input of an operation that takes no arguments.

type Op ¶

type Op interface {
	Info() Info
	InputType() reflect.Type
	// InputSchema is the inferred schema of In with Fields applied. A Fields
	// key that names no input field is an error.
	InputSchema() (*jsonschema.Schema, error)
}

Op is a Spec seen without its type parameter, so a catalog can hold operations of different input types.

type Owner ¶

type Owner string

Owner says where an operation runs.

const (
	// OwnerEngine operations run on hive.Engine.
	OwnerEngine Owner = "engine"
	// OwnerDesktop operations need the running desktop; the CLI reaches them
	// over its MCP servers.
	OwnerDesktop Owner = "desktop"
)

type Spec ¶

type Spec[In any] struct {
	// Name is "<resource>.<verb>". The resource may contain "_", which the
	// CLI spells as "-".
	Name    string
	Owner   Owner
	Effect  Effect
	Toolset Toolset
	// Summary is one line with no final period: the MCP title and the CLI
	// usage.
	Summary string
	// Guidance is the behavior an agent or a person must know: the rest of
	// the MCP description and the CLI long help.
	Guidance string
	// Args are the json names of the fields the CLI takes as positional
	// arguments, in order.
	Args []string
	// Fields adds constraints to input fields, keyed by json name.
	Fields Constraints
	// Caller is the rule for the input's caller field. Leave it unset for an
	// operation with no caller field.
	Caller CallerRule
}

Spec declares one operation with input type In. The output type is not part of the Spec: it belongs to the side that binds the handler.

An In may implement Validator for rules a JSON schema cannot state.

func (s Spec[In]) Info() Info

func (s Spec[In]) InputSchema() (*jsonschema.Schema, error)

func (Spec[In]) InputType() reflect.Type

type Toolset ¶

type Toolset struct {
	Name    string
	MCPPath string
}

Toolset groups operations. MCPPath is the loopback path of the desktop MCP server that serves them. A toolset is metadata: workspace grants stay per server (ADR a-workspace-declares-its-own-authority).

type Validator ¶

type Validator interface{ Validate() error }

Validator is implemented by an In that has cross-field rules. Mount calls it before the handler, and the CLI calls it before it dials the desktop.