executor

package
v0.1.21 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 26 Imported by: 1

Documentation

Overview

Package executor provides remote tool execution capabilities. It enables running tools in isolated containers while the LLM orchestration happens in the main backend.

Index

Constants

View Source
const AttachmentMaterializationCapability = "attachments.v1"
View Source
const CallQuestionAnswersCapability = "call-question-answers.v1"

CallQuestionAnswersCapability identifies request-scoped question resumption.

View Source
const CommandResultsCapability = "bash-results.v1"

CommandResultsCapability identifies bash exit metadata and settled cancellation.

View Source
const ControllerAdmissionLifetime = 2 * time.Hour

ControllerAdmissionLifetime bounds offline admission, not live ownership. Trusted hosts check live authority before each operation. An offline executor can order only delivered generations; a delayed signed admission can be stale in its issuer's database without being stale against the local high-water mark.

View Source
const ControllerCredentialHeader = "X-Sol-Controller-Credential"

ControllerCredentialHeader carries an opaque, purpose-limited host admission. It must not contain a shell callback token or an unverified ownership claim.

View Source
const ControllerDrainCapability = "controller-drain.v2"

ControllerDrainCapability identifies authenticated single-controller admission with joined foreground callbacks. It does not imply descendant-process or external-effect quiescence.

View Source
const GitSnapshotCapability = "git-snapshot.v1"
View Source
const GitSnapshotTool = "_executor_git_snapshot"

GitSnapshotTool is an executor-private, ordered callback. It is not exposed in the model tool catalogue. The embedding controller uses it to obtain immutable source without running host Git against a transferred mutable directory.

View Source
const MaxBootstrapBytes int64 = 512 << 20
View Source
const SignedControllerCapability = "controller-signed.v1"

SignedControllerCapability identifies local, public-key admission verification.

View Source
const WorkspaceBootstrapCapability = "workspace-bootstrap.v1"

Variables

View Source
var (
	ErrControllerReplaced = errors.New("executor controller superseded; request outcome may be unknown")
	ErrControllerClosed   = errors.New("executor controller supervisor closed")
)

Functions

func IsTransportError added in v0.1.8

func IsTransportError(err error) bool

IsTransportError reports whether err is a broken tool runtime transport.

func MarshalRequest

func MarshalRequest(req tool.Request) ([]byte, error)

MarshalRequest serializes a tool request to JSON.

func SignControllerAdmission added in v0.1.21

func SignControllerAdmission(key ed25519.PrivateKey, admission ControllerAdmission) (string, error)

SignControllerAdmission is an issuer operation. The private key stays outside the executor container. Issuers must admit the exact live owner/resource first.

func UnmarshalResponse

func UnmarshalResponse(data []byte) (tool.Response, error)

UnmarshalResponse deserializes a tool response from JSON.

Types

type AttachmentMaterialization added in v0.1.19

type AttachmentMaterialization struct {
	Scope    string `json:"scope"`
	ID       string `json:"id"`
	Filename string `json:"filename"`
	Size     int64  `json:"size"`
	SHA256   string `json:"sha256"`
	URL      string `json:"url"`
	Origin   string `json:"origin"`
}

AttachmentMaterialization is a host-only exact-object download grant. It is transported separately from model tool requests and never contains credentials.

type BootstrapAuthority added in v0.1.21

type BootstrapAuthority interface {
	ValidateBootstrap(context.Context, ControllerIdentity, string, string) (ControllerGrant, error)
}

BootstrapAuthority authenticates initialization separately from execution. The digest is an immutable input binding, not authority supplied by a client.

type ControllerAdmission added in v0.1.21

type ControllerAdmission struct {
	Protocol string             `json:"protocol"`
	Identity ControllerIdentity `json:"identity"`
	Grant    ControllerGrant    `json:"grant"`
	Run      string             `json:"run"`
	Task     string             `json:"task,omitempty"`
	Owner    string             `json:"owner"`
	Purpose  string             `json:"purpose"`
	SHA256   string             `json:"sha256,omitempty"`
	IssuedAt time.Time          `json:"issued_at"`
}

ControllerAdmission binds a signed generation to one exact process and purpose. Owner/Run/Task are opaque issuer coordinates, not Sol authorization policy.

type ControllerAuthority added in v0.1.21

type ControllerAuthority interface {
	Validate(context.Context, ControllerIdentity, string) (ControllerGrant, error)
}

ControllerAuthority verifies purpose-limited admission bound to every identity field. It runs before takeover and after drain, not before each message. The embedding trusted host owns live authorization before sending operations. Local ordering covers delivered generations, not undelivered issuer state.

type ControllerGrant added in v0.1.21

type ControllerGrant struct {
	Epoch       uint64    `json:"epoch"`
	AdmissionID string    `json:"admission_id"`
	ValidUntil  time.Time `json:"valid_until"`
}

ControllerGrant is returned by the trusted authority, never decoded from an unchecked client assertion. Epochs increase for every socket admission, including reconnects by the same owner. An admission is consumed even when its handshake acknowledgement is lost; reconnect requires a fresh admission.

type ControllerIdentity added in v0.1.21

type ControllerIdentity struct {
	ResourceID  string `json:"resource_id"`
	Incarnation string `json:"incarnation"`
	BootID      string `json:"boot_id"`
}

ControllerIdentity names a resource incarnation and this server process. BootID is generated by the server, not supplied by a connecting controller. The host must register it through its trusted resource initialization path; accepting an unregistered BootID would permit stale admission after restart.

type ControllerServerConfig added in v0.1.21

type ControllerServerConfig struct {
	ResourceID       string   `json:"resource_id"`
	Incarnation      string   `json:"incarnation"`
	VerificationKey  []byte   `json:"verification_key"`
	ArtifactToken    string   `json:"artifact_token"`
	BootstrapSHA256  string   `json:"bootstrap_sha256,omitempty"`
	BootstrapCommand []string `json:"bootstrap_command,omitempty"`
}

ControllerServerConfig contains public verification material and a narrow identity/artifact bearer. Neither grants signing or workspace mutation authority.

type ControllerStatus added in v0.1.21

type ControllerStatus struct {
	Identity ControllerIdentity `json:"identity"`
	Grant    ControllerGrant    `json:"grant"`
	Phase    string             `json:"phase"` // draining, active, consumed, superseded, closed
}

ControllerStatus describes admission only, never a command's outcome. A lost READY can be inspected without opening a replacement socket or replaying work.

type GitSnapshot added in v0.1.21

type GitSnapshot struct {
	ID     string `json:"id"`
	Head   string `json:"head"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

func DecodeGitSnapshot added in v0.1.21

func DecodeGitSnapshot(response tool.Response) (GitSnapshot, error)

type GitSnapshotExecutor added in v0.1.21

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

func NewGitSnapshotExecutor added in v0.1.21

func NewGitSnapshotExecutor(inner tool.Executor, workspace, artifacts string) *GitSnapshotExecutor

func (*GitSnapshotExecutor) ArtifactHandler added in v0.1.21

func (e *GitSnapshotExecutor) ArtifactHandler() http.Handler

ArtifactHandler serves immutable capture bytes. Its embedding host must authenticate resource-specific access. It never accepts a filesystem path.

func (*GitSnapshotExecutor) Execute added in v0.1.21

func (e *GitSnapshotExecutor) Execute(ctx context.Context, request tool.Request) (tool.Response, error)

func (*GitSnapshotExecutor) Tools added in v0.1.21

func (e *GitSnapshotExecutor) Tools() []tool.Info

type MaterializedAttachment added in v0.1.19

type MaterializedAttachment struct {
	Path   string `json:"path"`
	Reused bool   `json:"reused"`
}

type RemoteExecutor

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

RemoteExecutor implements tool.Executor by forwarding requests over a Transport to a remote ToolServer.

func NewRemoteExecutor

func NewRemoteExecutor(transport Transport, tools []tool.Info) *RemoteExecutor

NewRemoteExecutor creates a RemoteExecutor with the given transport and tool definitions. The tools parameter provides the tool schemas that the LLM needs to see.

func (*RemoteExecutor) Close

func (e *RemoteExecutor) Close() error

Close closes the underlying transport.

func (*RemoteExecutor) Execute

func (e *RemoteExecutor) Execute(ctx context.Context, req tool.Request) (tool.Response, error)

Execute implements tool.Executor by sending the request over the transport.

func (*RemoteExecutor) MaterializeAttachment added in v0.1.19

func (e *RemoteExecutor) MaterializeAttachment(ctx context.Context, request AttachmentMaterialization) (MaterializedAttachment, error)

func (*RemoteExecutor) Tools

func (e *RemoteExecutor) Tools() []tool.Info

Tools implements tool.Executor by returning the cached tool definitions.

type SignedControllerAuthority added in v0.1.21

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

func NewSignedControllerAuthority added in v0.1.21

func NewSignedControllerAuthority(config ControllerServerConfig) (*SignedControllerAuthority, error)

func (*SignedControllerAuthority) Validate added in v0.1.21

func (a *SignedControllerAuthority) Validate(ctx context.Context, identity ControllerIdentity, credential string) (ControllerGrant, error)

func (*SignedControllerAuthority) ValidateBootstrap added in v0.1.21

func (a *SignedControllerAuthority) ValidateBootstrap(ctx context.Context, identity ControllerIdentity, credential, digest string) (ControllerGrant, error)

type ToolServer

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

ToolServer wraps a tool.Executor and serves requests over WebSocket. It runs in the container and executes tools locally. It owns a Bus, PermissionManager, and QuestionManager so that tools executing inside the container can call AskPermission/AskQuestion.

func NewControlledToolServer added in v0.1.21

func NewControlledToolServer(exec tool.Executor, resourceID, incarnation string, authority ControllerAuthority) *ToolServer

NewControlledToolServer creates a resource-local single-controller server. The authority and resource identity are required. Its Handler fails closed without a valid controller credential; NewToolServer is the separate, explicitly uncontrolled API. A fresh BootID prevents process restart from resetting admission ordering under an unchanged authority binding.

func NewToolServer

func NewToolServer(executor tool.Executor) *ToolServer

NewToolServer creates a ToolServer with the given executor.

func (*ToolServer) ControllerIdentity added in v0.1.21

func (s *ToolServer) ControllerIdentity() ControllerIdentity

ControllerIdentity returns the identity for trusted host registration. It is not a credential and must not itself grant permission to register a boot.

func (*ToolServer) ControllerStatusHandler added in v0.1.21

func (s *ToolServer) ControllerStatusHandler() http.Handler

ControllerStatusHandler returns a read-only, authenticated status endpoint. The embedding host chooses its route. Status cannot reattach a socket: even an active equal-epoch admission requires a fresh grant to replace a lost socket.

func (*ToolServer) EnableWorkspaceBootstrap added in v0.1.21

func (s *ToolServer) EnableWorkspaceBootstrap(b *WorkspaceBootstrap)

EnableWorkspaceBootstrap requires initialization before any ordinary socket.

func (*ToolServer) Handler

func (s *ToolServer) Handler() http.Handler

Handler returns an http.Handler for the WebSocket endpoint.

func (*ToolServer) ListenAndServe

func (s *ToolServer) ListenAndServe(addr string) error

ListenAndServe starts the server on the given address.

func (*ToolServer) PermissionManager

func (s *ToolServer) PermissionManager() *bus.PermissionManager

PermissionManager returns the server's permission manager.

func (*ToolServer) QuestionManager

func (s *ToolServer) QuestionManager() *bus.QuestionManager

QuestionManager returns the server's question manager.

func (*ToolServer) ServeHTTP

func (s *ToolServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler for easy integration.

func (*ToolServer) ShutdownControllers added in v0.1.21

func (s *ToolServer) ShutdownControllers(ctx context.Context) error

ShutdownControllers permanently disables admission, cancels the current controller and joins its foreground callbacks. A deadline reports incomplete drain; it does not re-enable the resource or claim callback settlement. net/http Shutdown does not join hijacked WebSocket connections.

func (*ToolServer) WorkspaceBootstrapHandler added in v0.1.21

func (s *ToolServer) WorkspaceBootstrapHandler() http.Handler

type Transport

type Transport interface {
	// Send sends a tool request and waits for the response.
	Send(ctx context.Context, req tool.Request) (tool.Response, error)

	// Close closes the transport connection.
	Close() error
}

Transport abstracts the communication layer between RemoteExecutor and ToolServer. Implementations can use WebSocket, HTTP, gRPC, or any other protocol.

type TransportError added in v0.1.8

type TransportError struct {
	Op  string
	Err error
}

TransportError marks a broken tool runtime transport. It is fatal to the run because the model cannot repair a dead websocket by retrying tool calls.

func (*TransportError) Error added in v0.1.8

func (e *TransportError) Error() string

func (*TransportError) FatalToolError added in v0.1.8

func (e *TransportError) FatalToolError() bool

func (*TransportError) Unwrap added in v0.1.8

func (e *TransportError) Unwrap() error

type WSTransport

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

WSTransport implements Transport using WebSocket.

func NewControlledWSTransport added in v0.1.21

func NewControlledWSTransport(ctx context.Context, url, credential string, identity ControllerIdentity, grant ControllerGrant) (*WSTransport, error)

NewControlledWSTransport consumes a host-issued admission and waits for the resource's joined-drain acknowledgement before exposing the transport. The expected identity/grant come from trusted host admission, not this endpoint. Handshake failure has an unknown admission outcome. Callers must obtain a fresh admission to reconnect; this constructor never retries or replays commands.

func NewWSTransport

func NewWSTransport(url string, headers ...http.Header) (*WSTransport, error)

NewWSTransport creates a WebSocket transport by connecting to the given URL. The URL should be in the format "ws://host:port/ws". Optional headers are sent during the handshake (e.g., Authorization).

func (*WSTransport) Close

func (t *WSTransport) Close() error

Close implements Transport.

func (*WSTransport) FetchTools

func (t *WSTransport) FetchTools(ctx context.Context) ([]tool.Info, error)

FetchTools requests the tool definitions from the remote server.

func (*WSTransport) MaterializeAttachment added in v0.1.19

func (t *WSTransport) MaterializeAttachment(ctx context.Context, request AttachmentMaterialization) (MaterializedAttachment, error)

func (*WSTransport) PushAnswers

func (t *WSTransport) PushAnswers(ctx context.Context, answers [][]string) error

PushAnswers sends pre-loaded answers to the remote ToolServer and waits for ack.

func (*WSTransport) RequireAttachmentMaterialization added in v0.1.19

func (t *WSTransport) RequireAttachmentMaterialization(ctx context.Context) error

func (*WSTransport) RequireCallQuestionAnswers added in v0.1.19

func (t *WSTransport) RequireCallQuestionAnswers(ctx context.Context) error

func (*WSTransport) RequireCommandResults added in v0.1.18

func (t *WSTransport) RequireCommandResults(ctx context.Context) error

RequireCommandResults checks the executable's contract without executing a tool. Source mounts and application runtime versions do not identify this executable.

func (*WSTransport) RequireGitSnapshot added in v0.1.21

func (t *WSTransport) RequireGitSnapshot(ctx context.Context) error

func (*WSTransport) Send

func (t *WSTransport) Send(ctx context.Context, req tool.Request) (tool.Response, error)

Send implements Transport. A settled cancellation returns both the remote response and the context error. Transport errors without a response cannot establish a command's exit outcome.

func (*WSTransport) SetActiveTools

func (t *WSTransport) SetActiveTools(ctx context.Context, toolNames []string) error

SetActiveTools tells the remote ToolServer which tools to expose and accept.

func (*WSTransport) SetRules

func (t *WSTransport) SetRules(ctx context.Context, rules []bus.PermissionRule) error

SetRules sends permission rules to the remote ToolServer and waits for ack.

type WorkspaceBootstrap added in v0.1.21

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

WorkspaceBootstrap publishes one initialized directory by atomic rename. The root is private container-owned storage; command is a trusted installed program accepting input-directory and output-directory arguments. Inputs are data only.

func NewWorkspaceBootstrap added in v0.1.21

func NewWorkspaceBootstrap(root, digest string, command []string) *WorkspaceBootstrap

func (*WorkspaceBootstrap) Ready added in v0.1.21

func (b *WorkspaceBootstrap) Ready() bool

Jump to

Keyboard shortcuts

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