edge

Documentation

Overview

Package edge is the customer-side execution surface of the unified Skybridge edge binary. It receives single read-only tool calls dispatched from the SaaS control plane and runs them locally, so customer data (live AWS reads) is gathered inside the customer network and only results travel back. It is the Go counterpart of the Python connector's local tool execution path.

Index

• Constants
• func EncodeToolRequest(name string, arguments map[string]any) (string, error)
• func SplitCommand(command string) ([]string, error)
• func ValidateReadOnlyAWSCommand(command string) (bool, string)
• type Handler
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Dispatch(ctx context.Context, call ToolCall) Result
  • func (r *Registry) Has(name string) bool
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(name string, h Handler)
• type Result
  • func ErrorResult(tool, msg string) Result
• type ToolCall
  • func DecodeToolRequest(goal string) (ToolCall, bool)

Constants

const MaxCommandLen = 1200

MaxCommandLen bounds a single CLI invocation.

Functions

func EncodeToolRequest

func EncodeToolRequest(name string, arguments map[string]any) (string, error)

EncodeToolRequest mirrors the Python encoder: a JSON object carrying the sentinel/version, the tool name, and its arguments. Exposed mainly for round-trip tests and tooling.

func SplitCommand

func SplitCommand(command string) ([]string, error)

SplitCommand tokenizes a shell-style command into argv. Call it only after ValidateReadOnlyAWSCommand has accepted the command (it assumes no backslash/metacharacters).

func ValidateReadOnlyAWSCommand

func ValidateReadOnlyAWSCommand(command string) (bool, string)

ValidateReadOnlyAWSCommand reports whether command is a single, read-only AWS CLI invocation. It returns (allowed, reason); reason is a short explanation suitable for audit/agent surfacing.

Types

type Handler

type Handler func(ctx context.Context, args map[string]any) (Result, error)

Handler executes one read-only tool locally and returns its Result. A returned error is for transport/internal failures; tool-level failures should be reported as a Result with ok=false so the SaaS side still gets a structured answer.

type Registry

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

Registry maps tool names to local handlers. Only tools that genuinely need to run at the customer edge (live AWS reads) are registered here; everything else stays SaaS-side and is never dispatched to the edge.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Dispatch

func (r *Registry) Dispatch(ctx context.Context, call ToolCall) Result

Dispatch runs a decoded tool call. Unknown tools return an ok=false Result (not an error) so the caller can forward a structured rejection up the tunnel; a non-nil error is reserved for handler transport failures. A handler that returns an error is converted into an ok=false Result too, so the edge never drops a dispatched call silently.

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has reports whether a tool is handled at the edge.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns the registered tool names, sorted (stable for logging/tests).

func (*Registry) Register

func (r *Registry) Register(name string, h Handler)

Register adds (or replaces) a handler for name. It panics on an empty name or nil handler since that is always a programming error at wiring time.

type Result

type Result map[string]any

Result is a JSON-serializable tool result. It mirrors the Python tool convention: every result carries at least {"ok": bool, "tool": name}, plus tool-specific fields. The SaaS side wraps this into a ToolResult agent event and applies PII redaction before it reaches the model/UI.

func ErrorResult

func ErrorResult(tool, msg string) Result

ErrorResult builds a uniform ok=false result for a tool.

type ToolCall

type ToolCall struct {
	Name      string
	Arguments map[string]any
}

ToolCall is a decoded single-tool request.

func DecodeToolRequest

func DecodeToolRequest(goal string) (ToolCall, bool)

DecodeToolRequest returns the decoded ToolCall and true if goal is a valid tool-call envelope. It is intentionally defensive: any parse failure, missing/wrong sentinel, unsupported version, or empty name yields ok=false so a real natural-language goal is never mistaken for a tool call.