control

package
v0.149.5 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package control defines the transport-independent contract for Wingthing runtime operations. Adapters decide how to authenticate and transport a call; the operation name, schema, grant, annotations, and audit policy live here.

Index

Constants

View Source 
const (
	MCPTaskCreate   = "mcp/tasks/create"
	MCPTaskGet      = "mcp/tasks/get"
	MCPTaskResult   = "mcp/tasks/result"
	MCPTaskList     = "mcp/tasks/list"
	MCPTaskCancel   = "mcp/tasks/cancel"
	MCPRelatedTask  = "io.modelcontextprotocol/related-task"
	MCPTaskPageSize = 50
)

These control operations are transport plumbing, never entries in tools/list.

View Source 
const (
	SurfaceLocalMCP Surface = "local-mcp"
	SurfaceHTTPMCP  Surface = "http-mcp"
	// SurfaceDirectMCP is the native multi-wing adapter. Portal operations are
	// local to the coordinator, while every wing-owned operation carries an
	// explicit wing_id used to select a peer-to-peer transport.
	SurfaceDirectMCP Surface = "direct-mcp"
	ContractVersion  string  = "v1"
)
View Source 
const CancelRequestOperation = "mcp/requests/cancel"
View Source 
const DirectChannelPrefix = "control:v1:"
View Source 
const LaunchDiagnosticFramePrefix = "\x1b]777;wt-launch-diagnostic="

Variables

View Source 
var ErrSessionNameInUse = errors.New("session name is already in use")

ErrSessionNameInUse is also exported by eggclient for local store callers.

Functions

func AuditTarget 

func AuditTarget(name string, arguments json.RawMessage, result map[string]any) string

AuditTarget extracts the first bounded resource label approved by the operation definition. Full arguments remain digest-only.

func CancellationID added in v0.149.0 

func CancellationID(request DirectRequest) (string, bool)

func DecodeError added in v0.149.0 

func DecodeError(kind ErrorKind, message string) error

DecodeError preserves diagnostic text and restores known sentinel identity. Unknown kinds remain ordinary errors, allowing newer peers to add kinds.

func ErrorResult added in v0.149.0 

func ErrorResult(err error) map[string]any

ErrorResult retains the kind before the Go error crosses a wire boundary.

func FormatLaunchDiagnostic added in v0.149.4 

func FormatLaunchDiagnostic(d LaunchDiagnostic) string

func ObjectKinds 

func ObjectKinds(surface Surface) []string

ObjectKinds returns the semantic resource kinds visible through one surface. The order is stable for capability responses.

func OperationNames 

func OperationNames(surface Surface) []string

OperationNames returns the stable operation names exposed by one surface.

func PageTasks added in v0.149.0 

func PageTasks(tasks []MCPTask, cursor string) (map[string]any, error)

PageTasks uses stable IDs rather than offsets, so removals cannot skip the next page. Cursors are opaque and versioned, and work after reconnect.

func QualifyResult 

func QualifyResult(wingID string, result map[string]any) map[string]any

QualifyResult makes the owning wing part of the result envelope so clients never need mutable "current wing" state to interpret an object ID. Resource objects returned by current list/send operations are qualified individually as well, so retaining one object outside its response cannot lose its wing.

func QualifyTaskID added in v0.149.0 

func QualifyTaskID(wingID, runID string) string

func SplitTaskID added in v0.149.0 

func SplitTaskID(id string) (string, string, error)

func SplitWingTarget 

func SplitWingTarget(arguments json.RawMessage) (string, json.RawMessage, error)

SplitWingTarget validates and removes the transport-only wing_id argument. The selected wing receives only the operation's original contract.

func TaskAdmissionArguments added in v0.149.0 

func TaskAdmissionArguments(args json.RawMessage, admit func(json.RawMessage) (json.RawMessage, string, error)) (json.RawMessage, string, error)

TaskAdmissionArguments puts the retry key inside the original tool arguments.

func ToolError added in v0.149.0 

func ToolError(result map[string]any) error

ToolError restores a structured tool error. Legacy unclassified failures continue to use the tool result's isError flag and error text.

func WithLaunchDiagnostic added in v0.149.4 

func WithLaunchDiagnostic(err error, d LaunchDiagnostic) error

Types

type AuditArgumentMode 

type AuditArgumentMode string

AuditArgumentMode describes how an adapter may record tool arguments. 

const (
	// AuditArgumentsDigest permits only a digest of the complete argument
	// envelope. Adapters may separately record the bounded target selected by
	// AuditTargetKeys.
	AuditArgumentsDigest AuditArgumentMode = "digest"
)

type Authority 

type Authority string

Authority identifies the component that owns an operation's state and handler. Portal operations use gateway inventory; wing operations use the selected execution runtime. 

const (
	AuthorityWing   Authority = "wing"
	AuthorityPortal Authority = "portal"
)

type DirectRequest 

type DirectRequest struct {
	Version   string          `json:"version"`
	ID        string          `json:"id"`
	Tool      string          `json:"tool"`
	Arguments json.RawMessage `json:"arguments"`
}

DirectRequest is one authenticated operation sent over a WebRTC control data channel. User identity is deliberately absent: the wing obtains it from the coordinator-authenticated signaling exchange.

func CancellationRequest added in v0.149.0 

func CancellationRequest(id string) DirectRequest

type DirectResponse 

type DirectResponse struct {
	Version      string         `json:"version"`
	ID           string         `json:"id"`
	Result       map[string]any `json:"result,omitempty"`
	IsError      bool           `json:"is_error,omitempty"`
	Error        string         `json:"error,omitempty"`
	ErrorKind    ErrorKind      `json:"error_kind,omitempty"`
	RPCErrorCode int            `json:"rpc_error_code,omitempty"`
}

DirectResponse is the bounded result envelope returned by a wing.

func (DirectResponse) Err added in v0.149.0 

func (r DirectResponse) Err() error

Err restores typed failures while preserving legacy tool-result semantics.

type ErrorKind added in v0.149.0 

type ErrorKind string

ErrorKind identifies a known failure independently of its diagnostic text. The same kinds are used in direct envelopes and MCP structured tool results. 

const (
	ErrorInvalidArgument  ErrorKind = "invalid_argument"
	ErrorUnsupported      ErrorKind = "unsupported"
	ErrorSessionNameInUse ErrorKind = "session_name_in_use"
	ErrorNotFound         ErrorKind = "not_found"
	ErrorNoRows           ErrorKind = "no_rows"
	ErrorCanceled         ErrorKind = "canceled"
	ErrorDeadlineExceeded ErrorKind = "deadline_exceeded"
	ErrorLaunchAdmission  ErrorKind = "launch_admission"
	ErrorLaunchProvider   ErrorKind = "launch_provider"
	ErrorLaunchConnect    ErrorKind = "launch_connect"
	ErrorLaunchAttach     ErrorKind = "launch_attach"
)

func ErrorKindOf added in v0.149.0 

func ErrorKindOf(err error) ErrorKind

type LaunchDiagnostic added in v0.149.4 

type LaunchDiagnostic struct {
	Stage        string `json:"stage"`
	Reason       string `json:"reason"`
	PolicyOrigin string `json:"policy_origin,omitempty"`
	PolicyPath   string `json:"policy_path,omitempty"`
	PolicySource string `json:"policy_source,omitempty"`
	Session      string `json:"session,omitempty"`
}

LaunchDiagnostic is an optional, content-free projection. It deliberately cannot carry arguments, environment, provider output, or configuration values.

func LaunchDiagnosticOf added in v0.149.4 

func LaunchDiagnosticOf(err error) (LaunchDiagnostic, bool)

func (LaunchDiagnostic) Bounded added in v0.149.4 

func (d LaunchDiagnostic) Bounded() LaunchDiagnostic

type MCPTask added in v0.149.0 

type MCPTask struct {
	TaskID        string `json:"taskId"`
	Status        string `json:"status"`
	StatusMessage string `json:"statusMessage,omitempty"`
	CreatedAt     string `json:"createdAt"`
	LastUpdatedAt string `json:"lastUpdatedAt"`
	TTL           *int64 `json:"ttl"`
	PollInterval  int    `json:"pollInterval,omitempty"`
}

MCPTask is the MCP 2025-11-25 Task wire type. A nil TTL means unlimited.

type MCPTaskError added in v0.149.0 

type MCPTaskError struct {
	Code    int
	Message string
}

func (*MCPTaskError) Error added in v0.149.0 

func (e *MCPTaskError) Error() string

type MCPTaskParams added in v0.149.0 

type MCPTaskParams struct {
	TTL *int64 `json:"ttl,omitempty"`
}

type RequestLifetimes added in v0.149.0 

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

RequestLifetimes scopes cancellation to requests on one authenticated connection. It never cancels the wing-owned durable execution context.

func (*RequestLifetimes) Cancel added in v0.149.0 

func (r *RequestLifetimes) Cancel(id string)

func (*RequestLifetimes) Start added in v0.149.0 

func (r *RequestLifetimes) Start(parent context.Context, id string) (context.Context, func(), bool)

type Surface 

type Surface string

Surface identifies one adapter that can expose an operation.

type Tool 

type Tool struct {
	Name        string         `json:"name"`
	Title       string         `json:"title,omitempty"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"inputSchema"`
	Annotations map[string]any `json:"annotations,omitempty"`
	Execution   map[string]any `json:"execution,omitempty"`

	Version         string            `json:"-"`
	Grant           string            `json:"-"`
	Surfaces        []Surface         `json:"-"`
	Authority       Authority         `json:"-"`
	AuditArguments  AuditArgumentMode `json:"-"`
	AuditTargetKeys []string          `json:"-"`
}

Tool is one versioned Wingthing control operation. MCP adapters serialize the public fields directly. The remaining fields govern authorization, transport exposure, and audit redaction.

func Lookup 

func Lookup(name string) (Tool, bool)

Lookup returns one operation definition by stable name.

func MCPTaskTool added in v0.149.0 

func MCPTaskTool(operation string) (Tool, bool)

func Tools 

func Tools(surface Surface) []Tool

Tools returns the ordered operation set exposed by one adapter surface.

func ToolsForAuthority 

func ToolsForAuthority(surface Surface, authority Authority) []Tool

ToolsForAuthority returns the operations implemented by one authority and exposed through the requested surface.

func (Tool) Supports 

func (t Tool) Supports(surface Surface) bool

Supports reports whether an operation is exposed by the adapter surface.

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.