contract

package
v0.1.0-beta.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 3, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package contract defines Ozy's agent-facing response and error models.

These types are the wire shapes for the findTool, describeTool, and callTool contracts described in SPEC.md §9. They are shared by the broker, the CLI, and the MCP adapter so that every adapter emits the same instructional responses.

Index

Constants

View Source 
const (
	ErrTypeToolNotFound             = "TOOL_NOT_FOUND"
	ErrTypeDownstreamServerOffline  = "DOWNSTREAM_SERVER_OFFLINE"
	ErrTypeArgumentValidationFailed = "ARGUMENT_VALIDATION_FAILED"
	// ErrTypeToolSchemaChanged is reserved: the live broker does not emit it
	// yet. It names the planned schema-drift failure (cataloged schema no
	// longer matching the live tool) that the eval corpus already exercises.
	ErrTypeToolSchemaChanged         = "TOOL_SCHEMA_CHANGED"
	ErrTypeDownstreamCallFailed      = "DOWNSTREAM_CALL_FAILED"
	ErrTypeAuthUnavailable           = "AUTH_UNAVAILABLE"
	ErrTypeSemanticSearchUnavailable = "SEMANTIC_SEARCH_UNAVAILABLE"
	ErrTypeConfigError               = "CONFIG_ERROR"

	// ErrTypeNotImplemented is a skeleton-only marker for operations whose broker
	// behavior is deferred to a later change. It is not part of the durable §9.3
	// error set and is expected to disappear as behavior is implemented.
	ErrTypeNotImplemented = "NOT_IMPLEMENTED"
)

Error type values returned in structured failures (SPEC.md §9.3).

View Source 
const (
	FormatHuman   = "human"
	FormatJSON    = "json"
	FormatConcise = "concise"
)

Output format identifiers shared by every adapter (SPEC.md §15). Human is the default; JSON is a single machine-readable document for agents and evals; concise is a terse mode for token-sensitive use.

View Source 
const (
	DecisionUse          = "use"
	DecisionNoGoodMatch  = "no_good_match"
	DecisionAmbiguous    = "ambiguous"
	DecisionCatalogEmpty = "catalog_empty"
)

Decision values for findTool (SPEC.md §9.1). They are explicit so an agent can branch on intent rather than parsing prose. Every value listed here is emittable by the live broker — advertised-but-unreachable states are the lying-interface failure this contract exists to prevent.

View Source 
const (
	CheckOK    = "ok"
	CheckWarn  = "warn"
	CheckError = "error"
)

Doctor check status values.

Variables

This section is empty.

Functions

This section is empty.

Types

type Alternative 

type Alternative struct {
	ToolRef string `json:"toolRef"`
	Reason  string `json:"reason,omitempty"`
}

Alternative is a secondary candidate tool, included only when useful.

type CallNextAction 

type CallNextAction struct {
	Recommended bool             `json:"recommended,omitempty"`
	ToolRef     string           `json:"toolRef,omitempty"`
	Reason      string           `json:"reason,omitempty"`
	ExampleCall *RecommendedCall `json:"exampleCall,omitempty"`
}

CallNextAction is a recommended follow-up after a successful call.

type CallResult 

type CallResult struct {
	OK            bool             `json:"ok"`
	ToolRef       string           `json:"toolRef"`
	Result        any              `json:"result,omitempty"`
	ResultSummary string           `json:"resultSummary,omitempty"`
	NextActions   []CallNextAction `json:"nextActions,omitempty"`
	// Notices are actionable, in-band messages the agent must see alongside the
	// result (truncation recovery, staleness). Adapters render them inside the
	// response content — never only in out-of-band metadata.
	Notices []string `json:"notices,omitempty"`
	// CachedAgeSeconds is set when this result was served from the result cache:
	// the age of the cached entry at serve time. readOnlyHint asserts absence of
	// side effects, not temporal validity, so a cached observation must be
	// distinguishable from a live one. Nil means the call was invoked live.
	CachedAgeSeconds *int64 `json:"cachedAgeSeconds,omitempty"`
}

CallResult is the callTool success response (SPEC.md §9.3).

func (*CallResult) AllNotices 

func (r *CallResult) AllNotices() []string

AllNotices returns the notices to surface in-band, including the cache-hit stamp derived from CachedAgeSeconds, so every renderer shows the same set.

func (*CallResult) Render 

func (r *CallResult) Render(format string) string

Render produces the human/concise form of a callTool success result.

type Candidate 

type Candidate struct {
	ToolRef            string         `json:"toolRef"`
	ServerID           string         `json:"serverId"`
	DownstreamToolName string         `json:"name"`
	Title              string         `json:"title,omitempty"`
	Description        string         `json:"description,omitempty"`
	InputSchema        map[string]any `json:"inputSchema,omitempty"`
}

Candidate is a close-match tool surfaced in a findTool ambiguous response. Each candidate carries enough metadata — including its full input schema — for the agent to compare the candidates and invoke the chosen one directly.

type CatalogStats 

type CatalogStats struct {
	ConfiguredServers int `json:"configuredServers"`
	IndexedTools      int `json:"indexedTools"`
	FreshTools        int `json:"freshTools"`
	StaleTools        int `json:"staleTools"`
	// CatalogAgeSeconds is the time since the last successful index run, so an
	// agent can weigh how current the reported tool set and statuses are. Nil
	// (omitted) means the catalog has never been indexed — distinct from a
	// just-indexed age of 0.
	CatalogAgeSeconds *int64 `json:"catalogAgeSeconds,omitempty"`
}

CatalogStats is lightweight catalog health surfaced when it affects confidence.

type DescribeResult 

type DescribeResult struct {
	ToolRef         string           `json:"toolRef"`
	Title           string           `json:"title,omitempty"`
	Description     string           `json:"description,omitempty"`
	InputSchema     map[string]any   `json:"inputSchema,omitempty"`
	UsageHints      []string         `json:"usageHints,omitempty"`
	Examples        []Example        `json:"examples,omitempty"`
	RecommendedCall *RecommendedCall `json:"recommendedCall,omitempty"`
	RelatedTools    []RelatedTool    `json:"relatedTools,omitempty"`
	Status          *ToolStatus      `json:"status,omitempty"`
}

DescribeResult is the describeTool response (SPEC.md §9.2): one tool's exact schema, usage guidance, examples, and recommended call shape.

func (*DescribeResult) Render 

func (r *DescribeResult) Render(format string) string

Render produces the human/concise form of a describeTool result.

type DoctorCheck 

type DoctorCheck struct {
	Name   string `json:"name"`
	Status string `json:"status"` // ok | warn | error
	Detail string `json:"detail,omitempty"`
}

DoctorCheck is a single diagnostic result.

type DoctorResult 

type DoctorResult struct {
	OK               bool          `json:"ok"`
	Checks           []DoctorCheck `json:"checks"`
	AgentInstruction string        `json:"agentInstruction,omitempty"`
}

DoctorResult is the aggregate diagnostics report (SPEC.md §17).

func (*DoctorResult) Render 

func (r *DoctorResult) Render(format string) string

Render produces the human/concise form of a doctor report.

type Error 

type Error struct {
	Type             string `json:"type"`
	ToolRef          string `json:"toolRef,omitempty"`
	ServerID         string `json:"serverId,omitempty"`
	Retryable        bool   `json:"retryable"`
	Message          string `json:"message"`
	AgentInstruction string `json:"agentInstruction"`
}

Error is a structured, repair-oriented failure (SPEC.md §9.3). AgentInstruction must state, in grounded terms, whether the agent should retry, choose an alternative, ask the user, refresh, or report the failure.

func NotImplemented 

func NotImplemented(operation string) *Error

NotImplemented builds a skeleton-only structured error for an operation that is not yet wired to real behavior.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface so structured failures can flow through ordinary Go error returns.

type ErrorEnvelope 

type ErrorEnvelope struct {
	OK    bool   `json:"ok"`
	Error *Error `json:"error"`
}

ErrorEnvelope is the {ok:false,error} failure response shape (SPEC.md §9.3).

func NewErrorEnvelope 

func NewErrorEnvelope(e *Error) *ErrorEnvelope

NewErrorEnvelope wraps a structured error in its failure envelope.

func (*ErrorEnvelope) Render 

func (env *ErrorEnvelope) Render(format string) string

Render produces the human/concise text form of a failure envelope.

type Example 

type Example struct {
	Request   string         `json:"request,omitempty"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

Example is a worked invocation example for describeTool.

type FindResult 

type FindResult struct {
	Query               string         `json:"query"`
	Decision            string         `json:"decision"`
	SelectedToolRef     string         `json:"selectedToolRef,omitempty"`
	Confidence          string         `json:"confidence,omitempty"`
	Reason              string         `json:"reason,omitempty"`
	Selected            *SelectedTool  `json:"selected,omitempty"`
	Candidates          []Candidate    `json:"candidates,omitempty"`
	Errors              []Error        `json:"errors,omitempty"`
	CatalogStats        *CatalogStats  `json:"catalogStats,omitempty"`
	NextAction          *NextAction    `json:"nextAction,omitempty"`
	LikelyFollowupTools []FollowupTool `json:"likelyFollowupTools,omitempty"`
	Alternatives        []Alternative  `json:"alternatives,omitempty"`
	Avoid               []string       `json:"avoid,omitempty"`
	AgentInstruction    string         `json:"agentInstruction,omitempty"`
}

FindResult is the findTool response (SPEC.md §9.1). It is a decision, not just a list, and is always instructional.

func (*FindResult) Render 

func (r *FindResult) Render(format string) string

Render produces the human/concise form of a findTool result.

type FollowupTool 

type FollowupTool struct {
	ToolRef string `json:"toolRef"`
	When    string `json:"when,omitempty"`
}

FollowupTool is an obvious follow-up suggestion (e.g. read after search).

type ListResult 

type ListResult struct {
	Tools            []ListedTool  `json:"tools"`
	CatalogStats     *CatalogStats `json:"catalogStats,omitempty"`
	AgentInstruction string        `json:"agentInstruction,omitempty"`
}

ListResult is the catalog listing returned by `ozy list`.

func (*ListResult) Render 

func (r *ListResult) Render(format string) string

Render produces the human/concise form of a catalog listing.

type ListedTool 

type ListedTool struct {
	ToolRef     string `json:"toolRef"`
	Title       string `json:"title,omitempty"`
	ServerID    string `json:"serverId"`
	Freshness   string `json:"freshness,omitempty"`
	CallableNow bool   `json:"callableNow"`
}

ListedTool is one row of the catalog listing.

type Message 

type Message struct {
	OK      bool   `json:"ok"`
	Message string `json:"message"`
}

Message is a simple ok/message result for commands like init and version.

func (*Message) Render 

func (r *Message) Render(string) string

Render produces the human/concise form of a simple message.

type NextAction 

type NextAction struct {
	Tool      string         `json:"tool,omitempty"`
	ToolRef   string         `json:"toolRef,omitempty"`
	Arguments map[string]any `json:"arguments,omitempty"`
	Reason    string         `json:"reason,omitempty"`
}

NextAction tells the agent the next concrete Ozy call to make.

type RecommendedCall 

type RecommendedCall struct {
	Tool      string         `json:"tool"`
	Arguments map[string]any `json:"arguments"`
}

RecommendedCall is the suggested callTool shape for a tool.

type RelatedTool 

type RelatedTool struct {
	ToolRef      string `json:"toolRef"`
	Relationship string `json:"relationship,omitempty"`
}

RelatedTool links a tool to one commonly used alongside it.

type Renderable 

type Renderable interface {
	Render(format string) string
}

Renderable is implemented by every contract result so the render layer can produce human and concise text. JSON output is handled by marshaling the value directly and does not go through Render.

type SchemaPreview 

type SchemaPreview struct {
	Required   []string `json:"required,omitempty"`
	Properties []string `json:"properties,omitempty"`
}

SchemaPreview is the field-name preview returned by findTool instead of a full schema, to keep response size bounded (SPEC.md §13).

type SelectedTool 

type SelectedTool struct {
	ToolRef         string           `json:"toolRef"`
	Title           string           `json:"title,omitempty"`
	CallableNow     bool             `json:"callableNow"`
	ServerStatus    string           `json:"serverStatus,omitempty"`
	SchemaPreview   *SchemaPreview   `json:"schemaPreview,omitempty"`
	InputSchema     map[string]any   `json:"inputSchema,omitempty"`
	RecommendedCall *RecommendedCall `json:"recommendedCall,omitempty"`
}

SelectedTool is the best-match summary embedded in a findTool response. Small schemas ride inline (fast path): when InputSchema is set the agent can go straight to callTool using RecommendedCall, skipping the describeTool hop; SchemaPreview is the bounded fallback for schemas too large to inline.

type ToolStatus 

type ToolStatus struct {
	CallableNow      bool   `json:"callableNow"`
	ServerStatus     string `json:"serverStatus,omitempty"`
	CatalogFreshness string `json:"catalogFreshness,omitempty"`
}

ToolStatus reports live/freshness state for a described tool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.