localhooks

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2026 License: Apache-2.0 Imports: 24 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 MCPAuthConfig added in v0.4.0 

type MCPAuthConfig struct {
	// Type is "bearer" or "" (none).
	Type MCPAuthType

	// Token is a literal bearer token. Prefer APIKeyFromEnv for security.
	Token string

	// APIKeyFromEnv is the name of an environment variable holding the bearer token.
	APIKeyFromEnv string
}

MCPAuthConfig holds auth parameters for connecting to an MCP server.

func (*MCPAuthConfig) ResolveToken added in v0.4.0 

func (a *MCPAuthConfig) ResolveToken() string

ResolveToken returns the bearer token from literal value or env var.

type MCPAuthType added in v0.4.0 

type MCPAuthType string

MCPAuthType identifies the auth mechanism for remote MCP servers. 

const (
	MCPAuthNone   MCPAuthType = ""
	MCPAuthBearer MCPAuthType = "bearer"
)

type MCPServerConfig added in v0.4.0 

type MCPServerConfig struct {
	// Name is the hook name used in chain JSON, e.g. "filesystem".
	Name string

	// Transport: "stdio" (default), "sse", or "http".
	Transport MCPTransport

	// Stdio transport: Command + Args to spawn.
	Command string
	Args    []string

	// Remote transport: URL of the SSE MCP endpoint.
	URL string

	// Auth for remote transports (optional).
	Auth *MCPAuthConfig

	// ConnectTimeout for the initial handshake (default 30s).
	ConnectTimeout time.Duration

	// MCPSessionID is the persisted session ID to resume (for HTTP/SSE transports).
	MCPSessionID string

	// OnSessionID is a callback fired when the server issues a new session ID.
	OnSessionID func(string)

	// Tracker is the activity tracker for observing MCP pool operations.
	Tracker libtracker.ActivityTracker
}

MCPServerConfig describes a single MCP server connection.

type MCPSessionPool added in v0.4.0 

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

MCPSessionPool manages a single MCP client session with reconnect support. Mirrors the SSHClientCache pattern: mutex-protected, reconnects on failure.

func NewMCPSessionPool added in v0.4.0 

func NewMCPSessionPool(cfg MCPServerConfig) *MCPSessionPool

NewMCPSessionPool creates (but does not connect) a session pool for the given config.

func (*MCPSessionPool) CallTool added in v0.4.0 

func (p *MCPSessionPool) CallTool(ctx context.Context, toolName string, args map[string]any) (any, error)

CallTool calls a tool on the persistent session, reconnecting once if the session appears to have been lost. The pool must be connected first.

func (*MCPSessionPool) Close added in v0.4.0 

func (p *MCPSessionPool) Close() error

Close terminates the session cleanly.

func (*MCPSessionPool) Connect added in v0.4.0 

func (p *MCPSessionPool) Connect(ctx context.Context) error

Connect establishes the MCP session. Safe to call multiple times (idempotent).

func (*MCPSessionPool) ListTools added in v0.4.0 

func (p *MCPSessionPool) ListTools(ctx context.Context) ([]*mcp.Tool, error)

ListTools returns all tools advertised by the MCP server, reconnecting once if the session has been lost.

func (*MCPSessionPool) Reconnect added in v0.4.0 

func (p *MCPSessionPool) Reconnect(ctx context.Context) error

Reconnect tears down the current session and re-connects. Called automatically by MCPHookRepo.Exec on transport errors.

func (*MCPSessionPool) Session added in v0.4.0 

func (p *MCPSessionPool) Session(ctx context.Context) (*mcp.ClientSession, error)

Session returns the active session, connecting lazily if not yet established.

type MCPTransport added in v0.4.0 

type MCPTransport string

MCPTransport identifies how to connect to an MCP server. 

const (
	MCPTransportStdio MCPTransport = "stdio"
	MCPTransportSSE   MCPTransport = "sse"
	MCPTransportHTTP  MCPTransport = "http"
)

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.