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
- Variables
- func IsTransportError(err error) bool
- func MarshalRequest(req tool.Request) ([]byte, error)
- func SignControllerAdmission(key ed25519.PrivateKey, admission ControllerAdmission) (string, error)
- func UnmarshalResponse(data []byte) (tool.Response, error)
- type AttachmentMaterialization
- type BootstrapAuthority
- type ControllerAdmission
- type ControllerAuthority
- type ControllerGrant
- type ControllerIdentity
- type ControllerServerConfig
- type ControllerStatus
- type GitSnapshot
- type GitSnapshotExecutor
- type MaterializedAttachment
- type RemoteExecutor
- func (e *RemoteExecutor) Close() error
- func (e *RemoteExecutor) Execute(ctx context.Context, req tool.Request) (tool.Response, error)
- func (e *RemoteExecutor) MaterializeAttachment(ctx context.Context, request AttachmentMaterialization) (MaterializedAttachment, error)
- func (e *RemoteExecutor) Tools() []tool.Info
- type SignedControllerAuthority
- type ToolServer
- func (s *ToolServer) ControllerIdentity() ControllerIdentity
- func (s *ToolServer) ControllerStatusHandler() http.Handler
- func (s *ToolServer) EnableWorkspaceBootstrap(b *WorkspaceBootstrap)
- func (s *ToolServer) Handler() http.Handler
- func (s *ToolServer) ListenAndServe(addr string) error
- func (s *ToolServer) PermissionManager() *bus.PermissionManager
- func (s *ToolServer) QuestionManager() *bus.QuestionManager
- func (s *ToolServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *ToolServer) ShutdownControllers(ctx context.Context) error
- func (s *ToolServer) WorkspaceBootstrapHandler() http.Handler
- type Transport
- type TransportError
- type WSTransport
- func (t *WSTransport) Close() error
- func (t *WSTransport) FetchTools(ctx context.Context) ([]tool.Info, error)
- func (t *WSTransport) MaterializeAttachment(ctx context.Context, request AttachmentMaterialization) (MaterializedAttachment, error)
- func (t *WSTransport) PushAnswers(ctx context.Context, answers [][]string) error
- func (t *WSTransport) RequireAttachmentMaterialization(ctx context.Context) error
- func (t *WSTransport) RequireCallQuestionAnswers(ctx context.Context) error
- func (t *WSTransport) RequireCommandResults(ctx context.Context) error
- func (t *WSTransport) RequireGitSnapshot(ctx context.Context) error
- func (t *WSTransport) Send(ctx context.Context, req tool.Request) (tool.Response, error)
- func (t *WSTransport) SetActiveTools(ctx context.Context, toolNames []string) error
- func (t *WSTransport) SetRules(ctx context.Context, rules []bus.PermissionRule) error
- type WorkspaceBootstrap
Constants ¶
const AttachmentMaterializationCapability = "attachments.v1"
const CallQuestionAnswersCapability = "call-question-answers.v1"
CallQuestionAnswersCapability identifies request-scoped question resumption.
const CommandResultsCapability = "bash-results.v1"
CommandResultsCapability identifies bash exit metadata and settled cancellation.
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.
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.
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.
const GitSnapshotCapability = "git-snapshot.v1"
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.
const MaxBootstrapBytes int64 = 512 << 20
const SignedControllerCapability = "controller-signed.v1"
SignedControllerCapability identifies local, public-key admission verification.
const WorkspaceBootstrapCapability = "workspace-bootstrap.v1"
Variables ¶
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
IsTransportError reports whether err is a broken tool runtime transport.
func MarshalRequest ¶
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.
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) Tools ¶ added in v0.1.21
func (e *GitSnapshotExecutor) Tools() []tool.Info
type MaterializedAttachment ¶ added in v0.1.19
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 ¶
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
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) FetchTools ¶
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 ¶
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