localhooks

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEchoHook 

func NewEchoHook() taskengine.HookRepo

NewEchoHook creates a new instance of EchoHook.

func NewJSSandboxHook 

func NewJSSandboxHook(
	env *jseval.Env,
	tracker libtracker.ActivityTracker,
) taskengine.HookRepo

NewJSSandboxHook wires the shared jseval.Env into a HookRepo.

func NewLocalExecHook 

func NewLocalExecHook(opts ...LocalExecOption) taskengine.HookRepo

NewLocalExecHook creates a new LocalExecHook with the given options.

func NewLocalFSHook 

func NewLocalFSHook(allowedDir string) taskengine.HookRepo

NewLocalFSHook creates a new instance of LocalFSHook.

func NewPrint 

func NewPrint(tracker libtracker.ActivityTracker) taskengine.HookRepo

NewPrint creates a new Print instance

func NewSSHHook 

func NewSSHHook(options ...SSHOption) (taskengine.HookRepo, error)

NewSSHHook creates a new SSH hook with secure defaults

func NewWebCaller 

func NewWebCaller(options ...WebhookOption) taskengine.HookRepo

NewWebCaller creates a new webhook caller

Types

type EchoHook 

type EchoHook struct{}

EchoHook is a simple hook that echoes back the input arguments.

func (*EchoHook) Exec 

func (e *EchoHook) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hookCall *taskengine.HookCall) (any, taskengine.DataType, error)

Exec handles execution by echoing the input arguments.

func (*EchoHook) GetSchemasForSupportedHooks 

func (e *EchoHook) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks.

func (*EchoHook) GetToolsForHookByName 

func (e *EchoHook) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName returns tools exposed by this hook.

func (*EchoHook) Supports 

func (e *EchoHook) Supports(ctx context.Context) ([]string, error)

Supports returns the hook types supported by this hook.

type HookCallRecord 

type HookCallRecord struct {
	Args       taskengine.HookCall
	Input      any
	InputType  taskengine.DataType
	Transition string
}

type HookResponse 

type HookResponse struct {
	Status     int
	Output     any
	OutputType taskengine.DataType
	Transition string
}

type HostKeyVerifier 

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

HostKeyVerifier handles host key verification

func NewHostKeyVerifier 

func NewHostKeyVerifier(knownHostsFile string, strict bool) (*HostKeyVerifier, error)

NewHostKeyVerifier creates a new host key verifier

func (*HostKeyVerifier) AddKnownHost 

func (v *HostKeyVerifier) AddKnownHost(host, key string)

AddKnownHost adds a custom known host key

func (*HostKeyVerifier) VerifyHostKey 

func (v *HostKeyVerifier) VerifyHostKey(hostname string, remote net.Addr, key ssh.PublicKey) error

VerifyHostKey implements ssh.HostKeyCallback

type JSSandboxHook 

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

JSSandboxHook implements taskengine.HookRepo for executing generated JS code in a sandbox using the shared jseval.Env.

Typical flow:

  1. A task with handler "prompt_to_js" generates code: output: { "code": "<javascript>" } (DataTypeJSON)

  2. Next task uses handler "hook" with Hook.Name = "js_execution" and passes the previous output as input.

  3. This hook executes the code in a fresh goja VM, with: - jseval.Env providing builtins (sendEvent, executeTask, etc.) - Collector capturing console logs and builtin calls

  4. The hook returns a JSON object:

    { "ok": true|false, "error": "..." | null, "result": <exported result or null>, "logs": [ ExecLogEntry, ... ] }

    and DOES NOT treat script errors as hook errors, so the chain can use this info as feedback to the LLM.

func (*JSSandboxHook) Exec 

func (h *JSSandboxHook) Exec(
	ctx context.Context,
	startingTime time.Time,
	input any,
	debug bool,
	hook *taskengine.HookCall,
) (any, taskengine.DataType, error)

Exec runs the provided JS code in a sandbox and returns a structured result.

Input conventions:

  • If input is map[string]any and contains "code": string, that string is executed.
  • If input is string, it is treated as JS source directly.

Errors in the JS itself (compile/runtime) are reported in the returned JSON and DO NOT cause Exec to return an error, so the workflow can introspect and send a feedback loop back to the LLM.

func (*JSSandboxHook) GetSchemasForSupportedHooks 

func (h *JSSandboxHook) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks. TODO.

func (*JSSandboxHook) GetToolsForHookByName 

func (h *JSSandboxHook) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName exposes the JS sandbox as a single function-tool ("execute_js") so models can call it directly when tools are wired via ExecuteConfig.Hooks / hook resolution. The tool description includes the available builtins and executeHook-callable tools for the model.

func (*JSSandboxHook) Supports 

func (h *JSSandboxHook) Supports(ctx context.Context) ([]string, error)

Supports returns the single hook name this repo serves.

type LocalExecHook 

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

LocalExecHook runs commands on the local host (same machine as the process). It is opt-in and can be restricted by an allowlist and optional denylist. Enable via -enable-local-exec.

func (*LocalExecHook) Exec 

func (h *LocalExecHook) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hook *taskengine.HookCall) (any, taskengine.DataType, error)

Exec implements taskengine.HookRepo. Input is passed as stdin to the command when it is a string or when map contains "stdin". When invoked from execute_tool_calls, hook.Args may be nil and the command comes from input (e.g. {"command":"ls"}). Args (when set): command (required), args (optional space-separated), cwd, timeout, shell (default false).

func (*LocalExecHook) GetSchemasForSupportedHooks 

func (h *LocalExecHook) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks implements taskengine.HooksWithSchema.

func (*LocalExecHook) GetToolsForHookByName 

func (h *LocalExecHook) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName implements taskengine.HooksWithSchema.

func (*LocalExecHook) Supports 

func (h *LocalExecHook) Supports(ctx context.Context) ([]string, error)

Supports implements taskengine.HookRegistry.

type LocalExecOption 

type LocalExecOption func(*LocalExecHook)

LocalExecOption configures LocalExecHook.

func WithLocalExecAllowedCommands 

func WithLocalExecAllowedCommands(commands []string) LocalExecOption

WithLocalExecAllowedCommands restricts execution to these executable names/paths.

func WithLocalExecAllowedDir 

func WithLocalExecAllowedDir(dir string) LocalExecOption

WithLocalExecAllowedDir restricts execution to scripts/binaries under this directory.

func WithLocalExecDeniedCommands 

func WithLocalExecDeniedCommands(commands []string) LocalExecOption

WithLocalExecDeniedCommands forbids these executable basenames or paths (checked before allowlist).

func WithLocalExecTimeout 

func WithLocalExecTimeout(d time.Duration) LocalExecOption

WithLocalExecTimeout sets the default execution timeout.

type LocalExecResult 

type LocalExecResult struct {
	ExitCode        int     `json:"exit_code"`
	Stdout          string  `json:"stdout"`
	Stderr          string  `json:"stderr"`
	Success         bool    `json:"success"`
	Error           string  `json:"error,omitempty"`
	DurationSeconds float64 `json:"duration_seconds"`
	Command         string  `json:"command,omitempty"`
}

LocalExecResult is the structured result returned by the local_shell hook.

type LocalFSHook 

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

LocalFSHook provides direct filesystem access tools.

func (*LocalFSHook) Exec 

func (h *LocalFSHook) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hookCall *taskengine.HookCall) (any, taskengine.DataType, error)

Exec handles filesystem tool execution.

func (*LocalFSHook) GetSchemasForSupportedHooks 

func (h *LocalFSHook) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

func (*LocalFSHook) GetToolsForHookByName 

func (h *LocalFSHook) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

func (*LocalFSHook) Supports 

func (h *LocalFSHook) Supports(ctx context.Context) ([]string, error)

type MockHookRepo 

type MockHookRepo struct {
	Calls           []HookCallRecord
	ResponseMap     map[string]HookResponse
	DefaultResponse HookResponse
	ErrorSequence   []error
	// contains filtered or unexported fields
}

MockHookRepo is a mock implementation of the HookProvider interface.

func NewMockHookRegistry 

func NewMockHookRegistry() *MockHookRepo

NewMockHookRegistry returns a new instance of MockHookProvider.

func (*MockHookRepo) CallCount 

func (m *MockHookRepo) CallCount() int

CallCount returns number of times Exec was called

func (*MockHookRepo) Exec 

func (m *MockHookRepo) Exec(
	ctx context.Context,
	startingTime time.Time,
	input any,
	inputType taskengine.DataType,
	transition string,
	args *taskengine.HookCall,
) (int, any, taskengine.DataType, string, error)

Exec simulates execution of a hook call.

func (*MockHookRepo) LastCall 

func (m *MockHookRepo) LastCall() *HookCallRecord

LastCall returns the most recent hook call

func (*MockHookRepo) Reset 

func (m *MockHookRepo) Reset()

Reset clears all recorded calls and resets counters

func (*MockHookRepo) Supports 

func (m *MockHookRepo) Supports(ctx context.Context) ([]string, error)

func (*MockHookRepo) WithErrorSequence 

func (m *MockHookRepo) WithErrorSequence(errors ...error) *MockHookRepo

WithErrorSequence sets a sequence of errors to return

func (*MockHookRepo) WithResponse 

func (m *MockHookRepo) WithResponse(hookType string, response HookResponse) *MockHookRepo

WithResponse configures a response for a specific hook type

type Print 

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

Print implements a simple hook that returns predefined messages

func (*Print) Exec 

func (h *Print) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hookCall *taskengine.HookCall) (any, taskengine.DataType, error)

func (*Print) GetSchemasForSupportedHooks 

func (h *Print) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks.

func (*Print) GetToolsForHookByName 

func (h *Print) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName returns tools exposed by this hook.

func (*Print) Supports 

func (h *Print) Supports(ctx context.Context) ([]string, error)

type SSHClientCache 

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

SSHClientCache manages SSH connection pooling with thread safety

func NewSSHClientCache 

func NewSSHClientCache() *SSHClientCache

NewSSHClientCache creates a new SSH client cache

func (*SSHClientCache) Clear 

func (c *SSHClientCache) Clear()

Clear closes all connections and clears the cache

func (*SSHClientCache) Get 

func (c *SSHClientCache) Get(key string) (*ssh.Client, bool)

Get retrieves a cached SSH client

func (*SSHClientCache) IsAlive 

func (c *SSHClientCache) IsAlive(key string) bool

IsAlive checks if a cached client is still connected

func (*SSHClientCache) Put 

func (c *SSHClientCache) Put(key string, client *ssh.Client, config *ssh.ClientConfig)

Put stores an SSH client in the cache

func (*SSHClientCache) Remove 

func (c *SSHClientCache) Remove(key string)

Remove removes a client from the cache and closes it

type SSHConfig 

type SSHConfig struct {
	Host           string
	Port           int
	User           string
	Password       string
	PrivateKey     string
	PrivateKeyFile string
	Timeout        time.Duration
	HostKey        string // Expected host key for verification
	StrictHostKey  bool   // Whether to require host key verification
}

SSHConfig holds SSH connection parameters

type SSHHook 

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

SSHHook implements SSH remote command execution with proper security

func (*SSHHook) Close 

func (h *SSHHook) Close() error

Close cleans up any resources

func (*SSHHook) Exec 

func (h *SSHHook) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hook *taskengine.HookCall) (any, taskengine.DataType, error)

Exec implements the HookRepo interface

func (*SSHHook) GetSchemasForSupportedHooks 

func (h *SSHHook) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks

func (*SSHHook) GetToolsForHookByName 

func (h *SSHHook) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName returns tools exposed by this hook

func (*SSHHook) Supports 

func (h *SSHHook) Supports(ctx context.Context) ([]string, error)

Supports returns the hook types supported by this hook

type SSHOption 

type SSHOption func(*SSHHook) error

SSHOption configures the SSHHook

func WithClientCache 

func WithClientCache() SSHOption

WithClientCache enables connection pooling

func WithCustomHostKeyCallback 

func WithCustomHostKeyCallback(callback ssh.HostKeyCallback) SSHOption

WithCustomHostKeyCallback sets a custom host key verification callback

func WithDefaultPort 

func WithDefaultPort(port int) SSHOption

WithDefaultPort sets the default SSH port

func WithDefaultTimeout 

func WithDefaultTimeout(timeout time.Duration) SSHOption

WithDefaultTimeout sets the default connection/command timeout

func WithKnownHostsFile 

func WithKnownHostsFile(path string) SSHOption

WithKnownHostsFile sets the known_hosts file path

func WithStrictHostKey 

func WithStrictHostKey() SSHOption

WithStrictHostKey enables strict host key verification

type SSHResult 

type SSHResult struct {
	ExitCode int     `json:"exit_code"`
	Stdout   string  `json:"stdout"`
	Stderr   string  `json:"stderr"`
	Duration float64 `json:"duration_seconds"`
	Command  string  `json:"command"`
	Host     string  `json:"host"`
	Success  bool    `json:"success"`
	Error    string  `json:"error,omitempty"`
	HostKey  string  `json:"host_key,omitempty"` // Fingerprint of connected host
}

SSHResult holds command execution results

type WebCaller 

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

WebCaller makes HTTP requests to external services

func (*WebCaller) Exec 

func (h *WebCaller) Exec(ctx context.Context, startTime time.Time, input any, debug bool, hook *taskengine.HookCall) (any, taskengine.DataType, error)

Exec implements the HookRepo interface

func (*WebCaller) GetSchemasForSupportedHooks 

func (h *WebCaller) GetSchemasForSupportedHooks(ctx context.Context) (map[string]*openapi3.T, error)

GetSchemasForSupportedHooks returns OpenAPI schemas for supported hooks.

func (*WebCaller) GetToolsForHookByName 

func (h *WebCaller) GetToolsForHookByName(ctx context.Context, name string) ([]taskengine.Tool, error)

GetToolsForHookByName returns tools exposed by this hook.

func (*WebCaller) Supports 

func (h *WebCaller) Supports(ctx context.Context) ([]string, error)

Supports returns the hook types supported by this hook.

type WebhookOption 

type WebhookOption func(*WebCaller)

WebhookOption configures the WebhookCaller

func WithDefaultHeader 

func WithDefaultHeader(key, value string) WebhookOption

WithDefaultHeader sets a default header

func WithHTTPClient 

func WithHTTPClient(client *http.Client) WebhookOption

WithHTTPClient sets a custom HTTP client

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.