control

Documentation

Overview

Package control implements the client side of the "jungi control" remote messenger service integration.

A Client registers a session with the control service over HTTP, then maintains a persistent, authenticated websocket connection to it: sending periodic pings to keep the connection alive, reconnecting with exponential backoff on failure, and dispatching inbound non-assistant messages to a caller-supplied callback so they can be injected into the session as user turns.

It also forwards pending tool approval requests to the control service and dispatches inbound approval decisions to a caller-supplied callback, so a remote operator can approve or deny tool calls alongside the local TUI overlay.

Index

• type ApprovalRequest
• type Client
  • func New(cfg Config) Client
• type Config
• type InboundMessage
• type Logger

Types

type ApprovalRequest

type ApprovalRequest struct {
	RequestID    string
	ToolName     string
	Description  string
	InputPreview string
}

ApprovalRequest is the payload forwarded to the control service when a tool call requires manual approval.

type Client

type Client interface {
	// Connect registers a session with the control service and opens the
	// websocket connection, starting the ping and read loops. It blocks
	// until the initial registration and connection succeed, or ctx is
	// done, or an error occurs.
	Connect(ctx context.Context) error

	// Send transmits text as an outbound message frame. Returns an error
	// if the client is not currently connected.
	Send(text string) error

	// SendApprovalRequest forwards a pending tool approval request to the
	// control service. Returns an error if the client is not currently
	// connected.
	SendApprovalRequest(req ApprovalRequest) error

	// SessionID returns the remote session id assigned during
	// registration. Empty until Connect has completed successfully.
	SessionID() string

	// Close tears down the connection and stops all background loops.
	Close() error
}

Client is the interface session wiring depends on, so tests can supply a fake implementation without a real network connection.

func New

func New(cfg Config) Client

New constructs a Client from cfg. The returned client is not connected until Connect is called.

type Config

type Config struct {
	// URL is the base URL of the jungi control service, e.g.
	// "https://control.example.com". Required.
	URL string

	// Token is the bearer token used to authenticate both the HTTP session
	// registration request and the websocket connection. Required.
	Token string

	// Logger, when non-nil, receives errors encountered on the read,
	// ping, and reconnect loops. Optional.
	Logger Logger

	// OnMessage is invoked for every inbound non-assistant message
	// received over the websocket connection. Required for the
	// connection to be useful, but a nil callback is tolerated (messages
	// are simply dropped).
	OnMessage func(InboundMessage)

	// OnApprovalResponse is invoked for every inbound approval response
	// received over the websocket connection, with the correlating
	// request id and the decision ("allow" or "deny"). A nil callback is
	// tolerated (responses are simply dropped).
	OnApprovalResponse func(requestID, behavior string)
}

Config configures a Client.

type InboundMessage

type InboundMessage struct {
	Role    string     `json:"role"`
	Content string     `json:"content"`
	ID      flexibleID `json:"id"`
	From    string     `json:"from"`
}

InboundMessage is the payload of an inbound "message" frame, decoded from the websocket connection.

ID is typed as flexibleID rather than string for the same reason as registerResponse.ID: the control service may encode message ids as numbers rather than strings, and jungi never interprets the id beyond passing it through, so both forms are accepted.

type Logger

type Logger interface {
	Error(err error)
}

Logger is the minimal logging surface control needs. *logger.Logger satisfies this without the control package importing it directly, avoiding an import cycle risk and keeping the package easy to test.