executor

package
v0.1.19 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 21 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.

Variables

This section is empty.

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 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 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 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 NewToolServer

func NewToolServer(executor tool.Executor) *ToolServer

NewToolServer creates a ToolServer with the given executor.

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.

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 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) 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.

Jump to

Keyboard shortcuts

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