runtime

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package runtime owns the shared MCP protocol, tools and task lifetimes. Application configuration, credential stores and UI belong to host adapters.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatMCPError

func FormatMCPError(err error) error

Types

type ClientIdentity

type ClientIdentity struct{ ClientID, TokenID string }

ClientIdentity is the verified client and credential attached to an HTTP tool invocation. IDs contain no bearer secret and survive detached SDK calls.

func ClientIdentityFromContext

func ClientIdentityFromContext(ctx context.Context) (ClientIdentity, bool)

type CreateTunnelInput

type CreateTunnelInput struct {
	Action     string `json:"action,omitempty"`
	RequestID  string `json:"requestID"`
	NodeID     string `json:"nodeID"`
	Mode       string `json:"mode"`
	ListenHost string `json:"listenHost,omitempty"`
	ListenPort int    `json:"listenPort"`
	TargetHost string `json:"targetHost"`
	TargetPort int    `json:"targetPort"`
	TTLSeconds int    `json:"ttlSeconds,omitempty"`
}

type FileInput added in v0.16.0

type FileInput struct {
	NodeID  string `json:"nodeID" jsonschema:"Target SSH node ID or alias (call 'nodes' first if unknown)"`
	Action  string `json:"action" jsonschema:"File operation: read, write, patch, or stat"`
	Path    string `json:"path" jsonschema:"Absolute path to the remote file or directory"`
	Content string `json:"content,omitempty" jsonschema:"Full file content for write, or <<<< ==== >>>> search/replace blocks for patch"`
	Range   []int  `json:"range,omitempty" jsonschema:"Optional [start_line, end_line] (1-based, inclusive) for read"`
}

type FileOutput added in v0.16.0

type FileOutput struct {
	Content       string `json:"content,omitempty" jsonschema:"Line-numbered file content (read) or metadata/directory tree (stat)"`
	TotalLines    int    `json:"totalLines,omitempty" jsonschema:"Total number of lines read (only the first 512 KiB when truncated)"`
	Size          int64  `json:"size,omitempty" jsonschema:"File size in bytes"`
	Mode          string `json:"mode,omitempty" jsonschema:"File mode/permissions"`
	IsDir         bool   `json:"isDir,omitempty" jsonschema:"True if the path is a directory"`
	Truncated     bool   `json:"truncated,omitempty" jsonschema:"True if read stopped at the 512 KiB limit"`
	BytesWritten  int    `json:"bytesWritten,omitempty" jsonschema:"Number of bytes written"`
	BlocksApplied int    `json:"blocksApplied,omitempty" jsonschema:"Number of search/replace blocks applied by patch"`
	FuzzyBlocks   int    `` /* 149-byte string literal not displayed */
	InPlace       bool   `` /* 185-byte string literal not displayed */
	LintWarning   string `json:"lintWarning,omitempty" jsonschema:"Syntax check warning if detected after write or patch"`
	Status        string `json:"status" jsonschema:"Operation status"`
}

type GUIInput added in v0.16.0

type GUIInput struct {
	NodeID  string `json:"nodeID" jsonschema:"Target SSH node ID or alias (call 'nodes' first if unknown)"`
	Action  string `json:"action" jsonschema:"GUI action: shot, click, double_click, right_click, move, type, key, scroll, or drag"`
	Coord   []int  `` /* 141-byte string literal not displayed */
	Text    string `` /* 153-byte string literal not displayed */
	Display string `json:"display,omitempty" jsonschema:"Optional X11 display (e.g. :0, :1); auto-detected when omitted"`
}

type GUIOutput added in v0.16.0

type GUIOutput struct {
	Action   string `json:"action" jsonschema:"Executed GUI action"`
	MimeType string `json:"mimeType" jsonschema:"Screenshot image MIME type"`
	Status   string `json:"status" jsonschema:"Operation status"`
}

type HTTPOptions

type HTTPOptions struct {
	Listen    string
	PublicURL string
	Token     string
	// TokenVerifier supplies deployment-owned authentication. It is mutually
	// exclusive with Token and must return a stable, nonempty UserID. The
	// optional Extra["tokenID"] identifies the credential, not the client.
	TokenVerifier   auth.TokenVerifier
	StateDir        string
	AllowedHosts    []string
	AllowedOrigins  []string
	HeaderTimeout   time.Duration
	BodyTimeout     time.Duration
	StreamIdle      time.Duration
	ToolTimeout     time.Duration
	SessionTimeout  time.Duration
	ShutdownTimeout time.Duration
	MaxSessions     int
	MaxRequests     int // Per-lane capacity, including independent dynamic authentication.
	Transfers       transfer.Limits
	// contains filtered or unexported fields
}

HTTPOptions configures authenticated Streamable HTTP. Token is consumed at construction; the runtime retains only its digest, never a printable token.

func DefaultHTTPOptions

func DefaultHTTPOptions() HTTPOptions

func (*HTTPOptions) ValidateLimits

func (o *HTTPOptions) ValidateLimits() error

ValidateLimits lets host configuration adapters validate typed limits before loading authentication material or starting a runtime.

type HTTPTransferInput added in v0.16.0

type HTTPTransferInput struct {
	Action     string `json:"action" jsonschema:"Transfer action: prepare_push, prepare_pull, status, or cancel"`
	RequestID  string `` /* 150-byte string literal not displayed */
	NodeID     string `` /* 130-byte string literal not displayed */
	RemotePath string `json:"remotePath,omitempty" jsonschema:"Absolute file path on the SSH target for prepare_push or prepare_pull"`
	Size       int64  `json:"size,omitempty" jsonschema:"Exact client file size in bytes for prepare_push"`
	SHA256     string `json:"sha256,omitempty" jsonschema:"Lowercase SHA-256 of the client file for prepare_push"`
	Overwrite  bool   `` /* 135-byte string literal not displayed */
	TransferID string `json:"transferID,omitempty" jsonschema:"Transfer task ID returned by prepare_push or prepare_pull, used by status and cancel"`
}

HTTPTransferInput is the polymorphic HTTP out-of-band transfer tool input.

type ListNodesInput

type ListNodesInput struct {
	Tag string `json:"tag,omitempty" jsonschema:"Filter nodes by tag. If empty, lists all nodes."`
}

type ListNodesOutput

type ListNodesOutput struct {
	Nodes  []NodeInfo `json:"nodes" jsonschema:"List of available nodes with detailed information"`
	Status string     `json:"status" jsonschema:"Operation status"`
}

type ListTunnelsInput

type ListTunnelsInput struct {
	Action string `json:"action,omitempty"`
	NodeID string `json:"nodeID,omitempty"`
	State  string `json:"state,omitempty"`
}

type ListTunnelsOutput

type ListTunnelsOutput struct {
	Tunnels []tunnel.Status `json:"tunnels"`
}

type NodeInfo

type NodeInfo = ports.NodeInfo

type Option

type Option func(*serverConfig)

func WithDependencies

func WithDependencies(dependencies ports.Dependencies) Option

func WithHTTP

func WithHTTP(options HTTPOptions) Option

WithHTTP switches the runtime to HTTP tools and session-based Streamable HTTP. Start it with Runtime.ServeHTTP rather than the stdio Run entry point.

func WithLogger

func WithLogger(log logger.DebugLogger) Option

func WithToolTimeout

func WithToolTimeout(timeout time.Duration) Option

WithToolTimeout sets a positive tool deadline for stdio and HTTP. It overrides HTTPOptions.ToolTimeout regardless of option order, including HTTP request and SDK middleware deadlines. Session and file-transfer limits are independent.

func WithTunnelRunner

func WithTunnelRunner(run tunnel.Runner) Option

WithTunnelRunner supplies a host-owned dedicated runner for compatibility adapters. HTTP never enables tunnel tools regardless of this option.

type PrepareDownloadInput

type PrepareDownloadInput struct {
	Action     string `json:"action,omitempty"`
	RequestID  string `json:"requestID"`
	NodeID     string `json:"nodeID"`
	RemotePath string `json:"remotePath"`
}

type PrepareUploadInput

type PrepareUploadInput struct {
	Action     string `json:"action,omitempty"`
	RequestID  string `json:"requestID"`
	NodeID     string `json:"nodeID"`
	RemotePath string `json:"remotePath"`
	Size       int64  `json:"size"`
	SHA256     string `json:"sha256"`
	Overwrite  bool   `json:"overwrite,omitempty"`
}

type PreparedTransferOutput

type PreparedTransferOutput struct {
	Task      transfer.Status   `json:"task"`
	URL       string            `json:"url,omitempty"`
	Method    string            `json:"method,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	StatusURL string            `json:"statusURL,omitempty"`
	CancelURL string            `json:"cancelURL,omitempty"`
}

type RecoveryEntry

type RecoveryEntry struct {
	Task              transfer.Status `json:"task"`
	TemporaryPath     string          `json:"temporaryPath,omitempty"`
	Verified          bool            `json:"verified"`
	DestinationExists bool            `json:"destinationExists"`
	ActualSize        int64           `json:"actualSize,omitempty"`
	ActualSHA256      string          `json:"actualSHA256,omitempty"`
	MatchesExpected   bool            `json:"matchesExpected"`
	Resolution        string          `json:"resolution,omitempty"`
}

func RecoverTransfers

func RecoverTransfers(ctx context.Context, options RecoveryOptions, opts ...Option) (_ []RecoveryEntry, retErr error)

RecoverTransfers is offline maintenance: the permanent journal lock prevents racing a running service. Listing never mutates task records or contacts SSH. Remote verification/cleanup and operator acknowledgement are explicit options.

type RecoveryOptions

type RecoveryOptions struct {
	StateDir       string
	TransferID     string
	Verify         bool
	Cleanup        bool
	ResolveUnknown bool
	Reason         string
	MaxRecords     int
	MaxFileBytes   int64
}

type Runtime

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

func NewRuntime

func NewRuntime(ctx context.Context, opts ...Option) (_ *Runtime, retErr error)

func (*Runtime) Close

func (r *Runtime) Close() error

func (*Runtime) HTTPHandler

func (r *Runtime) HTTPHandler() (http.Handler, error)

HTTPHandler returns the authenticated handler owned by this runtime. Every HTTP server using it must bind its lifecycle to this runtime and call Close.

func (*Runtime) Run

func (r *Runtime) Run(transport mcp.Transport) error

Run serves a transport until it ends or the runtime is closed. It does not relinquish the caller's responsibility to close the runtime.

func (*Runtime) ServeHTTP

func (r *Runtime) ServeHTTP(listener net.Listener) (retErr error)

ServeHTTP takes ownership of listener. It stops accepting requests on runtime cancellation and force-closes connections if graceful shutdown times out.

func (*Runtime) Shutdown

func (r *Runtime) Shutdown(ctx context.Context) error

type TerminalInput added in v0.16.0

type TerminalInput struct {
	NodeID    string               `json:"nodeID" jsonschema:"Target SSH node ID or alias (call 'nodes' first if unknown)"`
	Command   string               `` /* 178-byte string literal not displayed */
	Session   string               `` /* 223-byte string literal not displayed */
	Cwd       string               `json:"cwd,omitempty" jsonschema:"Optional working directory to switch to before executing cmd"`
	Timeout   int                  `` /* 214-byte string literal not displayed */
	Sudo      bool                 `json:"sudo,omitempty" jsonschema:"Whether to execute the command with sudo privileges (once mode only)"`
	Execution *ssh.ExecutionConfig `` /* 268-byte string literal not displayed */
}

func (TerminalInput) Validate added in v0.16.0

func (in TerminalInput) Validate() error

type TerminalOutput added in v0.16.0

type TerminalOutput struct {
	Output     string  `json:"output" jsonschema:"Command stdout/stderr (folded when verbose)"`
	Status     string  `json:"status" jsonschema:"Operation status: success, running, or failed"`
	Error      string  `json:"error,omitempty" jsonschema:"Error message if failed"`
	Outcome    string  `json:"outcome,omitempty" jsonschema:"Execution outcome: not_started, completed, or unknown"`
	ExitCode   *uint32 `json:"exitCode,omitempty" jsonschema:"Exit status code if received"`
	Signal     string  `json:"signal,omitempty" jsonschema:"Termination signal if terminated by signal"`
	PlanDigest string  `json:"planDigest,omitempty" jsonschema:"Digest of the executed command plan"`
	Truncated  bool    `json:"truncated,omitempty" jsonschema:"Whether output exceeded limit or was folded"`
	NewSession bool    `` /* 148-byte string literal not displayed */
}

type TransferFileInput

type TransferFileInput struct {
	NodeID     string `json:"nodeID" jsonschema:"Target SSH node ID or alias (call 'nodes' first if unknown)"`
	Direction  string `json:"direction" jsonschema:"Transfer direction: push (upload local to remote) or pull (download remote to local)"`
	LocalPath  string `json:"localPath" jsonschema:"Absolute path to the local file or directory"`
	RemotePath string `json:"remotePath" jsonschema:"Absolute path to the remote file or directory"`
}

TransferFileInput is the Stdio transfer tool input (direct local <-> remote SFTP).

type TransferFileOutput

type TransferFileOutput struct {
	Direction string `json:"direction,omitempty" jsonschema:"Executed transfer direction"`
	Status    string `json:"status" jsonschema:"Operation status"`
}

type TransferTaskInput

type TransferTaskInput struct {
	Action     string `json:"action,omitempty"`
	TransferID string `json:"transferID"`
}

type TunnelInput

type TunnelInput struct {
	Action   string `json:"action,omitempty"`
	TunnelID string `json:"tunnelID"`
}

type TunnelOutput

type TunnelOutput struct {
	Tunnel tunnel.Status `json:"tunnel"`
}

type TunnelPolyInput added in v0.16.0

type TunnelPolyInput struct {
	Action     string `json:"action" jsonschema:"Tunnel action: create, list, status, or stop"`
	RequestID  string `` /* 183-byte string literal not displayed */
	NodeID     string `` /* 144-byte string literal not displayed */
	Mode       string `json:"mode,omitempty" jsonschema:"For create: local (-L) or remote (-R). No dynamic forwarding."`
	ListenHost string `json:"listenHost,omitempty" jsonschema:"For create: IP literal or localhost; defaults to 127.0.0.1"`
	ListenPort int    `json:"listenPort,omitempty" jsonschema:"For create: listening TCP port, 0 to 65535 (0 allocates automatically)"`
	TargetHost string `json:"targetHost,omitempty" jsonschema:"For create: destination host name or unbracketed IP literal"`
	TargetPort int    `json:"targetPort,omitempty" jsonschema:"For create: destination TCP port, 1 to 65535"`
	TTLSeconds int    `json:"ttlSeconds,omitempty" jsonschema:"For create: lifetime after startup, 1 to 86400 seconds; default 3600"`
	TunnelID   string `json:"tunnelID,omitempty" jsonschema:"For status or stop: tunnel ID returned by create or list"`
	State      string `` /* 126-byte string literal not displayed */
}

type TunnelPolyOutput added in v0.16.0

type TunnelPolyOutput struct {
	Tunnel  *tunnel.Status  `json:"tunnel,omitempty"`
	Tunnels []tunnel.Status `json:"tunnels,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址