Documentation
¶
Overview ¶
Package runtime owns the shared MCP protocol, tools and task lifetimes. Application configuration, credential stores and UI belong to host adapters.
Index ¶
- func FormatMCPError(err error) error
- type ClientIdentity
- type CreateTunnelInput
- type FileInput
- type FileOutput
- type GUIInput
- type GUIOutput
- type HTTPOptions
- type HTTPTransferInput
- type ListNodesInput
- type ListNodesOutput
- type ListTunnelsInput
- type ListTunnelsOutput
- type NodeInfo
- type Option
- type PrepareDownloadInput
- type PrepareUploadInput
- type PreparedTransferOutput
- type RecoveryEntry
- type RecoveryOptions
- type Runtime
- type TerminalInput
- type TerminalOutput
- type TransferFileInput
- type TransferFileOutput
- type TransferTaskInput
- type TunnelInput
- type TunnelOutput
- type TunnelPolyInput
- type TunnelPolyOutput
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatMCPError ¶
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 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 ListTunnelsInput ¶
type ListTunnelsOutput ¶
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 ¶
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 ¶
WithTunnelRunner supplies a host-owned dedicated runner for compatibility adapters. HTTP never enables tunnel tools regardless of this option.
type PrepareDownloadInput ¶
type PrepareUploadInput ¶
type PreparedTransferOutput ¶
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 Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
func (*Runtime) HTTPHandler ¶
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 ¶
Run serves a transport until it ends or the runtime is closed. It does not relinquish the caller's responsibility to close the runtime.
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 TransferTaskInput ¶
type TunnelInput ¶
type TunnelOutput ¶
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 */
}
Source Files
¶
- close.go
- http.go
- http_admission.go
- http_auth.go
- http_options.go
- http_transfer.go
- invocation.go
- output_fold.go
- recovery.go
- registry.go
- server.go
- tool_file.go
- tool_gui.go
- tool_nodes.go
- tool_terminal.go
- tool_transfer.go
- tool_tunnel.go
- transfer_binding.go
- transfer_cleanup.go
- transfer_remote.go
- transfer_timeout.go
- tunnel_runtime.go