Skip to content

github.com/ricardo/anthrogo/pkg/kairos

package kairos // import "github.com/ricardo/anthrogo/pkg/kairos"


CONSTANTS

const MaxHops = 2
    MaxHops is the maximum number of KAIROS hops allowed before Remote-typed
    subagents are excluded from a worker's registry.


FUNCTIONS

func DispatchRemote(ctx context.Context, endpoint, authToken, subagentType, description, prompt string) (string, error)
    DispatchRemote sends a RunRequest to a KAIROS worker at endpoint, streams
    the SSE response, and returns the accumulated final text.

    The client accumulates text deltas and returns the "final" field from the
    event: done frame (preferred) or the accumulated deltas as a fallback.
    On event: error the returned error contains the remote error message.

    DispatchRemote is a thin wrapper around DispatchRemoteWithOptions with no
    exec-tools-locally behaviour.

func DispatchRemoteWithOptions(ctx context.Context, endpoint string, req RunRequest, opts ClientOptions) (string, error)
    DispatchRemoteWithOptions is the full client entry-point. When
    opts.ExecToolsLocally is true it:
     1. Sends X-Anthrogo-Exec-Tools-Locally: true on the request.
     2. Captures the run_id from event: run_id.
     3. On each event: tool_use_request, dispatches via opts.ToolRegistry,
        gates via opts.Permissions, and POSTs the ToolResult back to
        /kairos/run/<rid>/tool-result.
     4. Continues consuming text deltas until event: done.

    The client-side permission gate (opts.Permissions) applies independently of
    any gate on the worker. A denied tool call produces an IsError ToolResult
    that the worker's engine sees and may handle as it sees fit.

func GenerateKeyPair() (priv ed25519.PrivateKey, pub ed25519.PublicKey, err error)
    GenerateKeyPair returns (private, public) keys.

func LoadPrivateKey(path string) (ed25519.PrivateKey, error)
    LoadPrivateKey reads a base64-encoded ed25519 private key from a file.

func LoadPublicKey(input string) (ed25519.PublicKey, error)
    LoadPublicKey reads a base64 ed25519 public key from a file or inline
    literal.

    Detection order:
     1. Try to decode input directly as base64. If the result is exactly
        ed25519.PublicKeySize (32) bytes, use it.
     2. Otherwise treat input as a file path and read the file, then decode its
        contents as base64.

    This handles the common case where an inline base64 literal happens to start
    with '/' (valid base64 character) without incorrectly treating it as a path.

func VerifyFrame(pub ed25519.PublicKey, frame SignedFrame) error
    VerifyFrame verifies the signature in the frame against its payload using
    the given public key. Returns nil on success, an error on failure.


TYPES

type ClientOptions struct {
    AuthToken        string
    ExecToolsLocally bool
    // ToolRegistry is required when ExecToolsLocally is true. Tool calls from
    // the remote subagent are dispatched through this registry on the client.
    ToolRegistry *tool.Registry
    // Permissions is required when ExecToolsLocally is true. The client-side
    // permission gate is applied before each tool call.
    Permissions *permissions.Context
    // OnTextDelta, if non-nil, is invoked for each event: text SSE message.
    // Called from the SSE parse loop goroutine; implementations must be thread-safe.
    OnTextDelta func(string)
    // TrustKey, if set, causes every incoming SSE frame to be decoded as a
    // SignedFrame first. The ed25519 signature is verified against this public
    // key before the payload is parsed. Any frame that fails verification causes
    // DispatchRemoteWithOptions to return an error immediately.
    TrustKey ed25519.PublicKey
    // InsecureSkipVerify disables TLS certificate verification. DEV ONLY.
    InsecureSkipVerify bool
    // CACertPath is the path to a PEM-encoded CA certificate bundle used to
    // verify the server's TLS certificate. Useful for internal/self-signed CAs.
    CACertPath string
}
    ClientOptions configures DispatchRemoteWithOptions.

type PermSnapshot struct {
    Mode             string                                    `json:"mode,omitempty"`
    AlwaysAllowRules map[permissions.Source][]permissions.Rule `json:"always_allow,omitempty"`
    AlwaysDenyRules  map[permissions.Source][]permissions.Rule `json:"always_deny,omitempty"`
    AlwaysAskRules   map[permissions.Source][]permissions.Rule `json:"always_ask,omitempty"`
}
    PermSnapshot is a JSON-safe projection of permissions.Context used to
    transmit the caller's permission rules to a KAIROS worker. HookDecide (a
    Go func) is intentionally not serialized; the worker rebuilds it from the
    transmitted Hooks config if non-nil.

type RemoteContext struct {
    HopDepth    int           `json:"hop_depth"`
    Hooks       *hooks.Config `json:"hooks,omitempty"`
    Permissions *PermSnapshot `json:"permissions,omitempty"`
}
    RemoteContext travels from client → worker over /kairos/run JSON body.
    HopDepth counts how many KAIROS hops this request has traversed already;
    workers reject Remote-type subagents when HopDepth >= MaxHops (default 2).
    Hooks + Permissions are best-effort: shell paths inside hooks are taken
    as-is (won't resolve relative to client cwd on worker); permission rules
    apply to the worker's local tool dispatch.

type RunHandler func(ctx context.Context, req RunRequest, emit func(textDelta string)) (finalText string, err error)
    RunHandler is the function signature the server invokes for each request.
    emit is called for each text delta; the returned finalText is sent as the
    event: done payload. On error, event: error is sent instead.

type RunHandlerWithToolForward func(
    ctx context.Context,
    req RunRequest,
    emitText func(string),
    emitToolUse func(req ToolUseRequest),
    waitForResult func(toolUseID string) (ToolResult, error),
) (string, error)
    RunHandlerWithToolForward extends RunHandler for the exec-tools-locally
    mode. The worker invokes emitToolUse to push a tool_use_request SSE event to
    the client, then calls waitForResult which blocks until the client POSTs the
    matching result to /kairos/run/<rid>/tool-result.

    Note: the permission gate is NOT applied on the worker side — the client
    runs its own gate before POSTing the result back. A denied tool call arrives
    as an IsError result.

type RunRequest struct {
    SubagentType  string         `json:"subagent_type"`
    Prompt        string         `json:"prompt"`
    Description   string         `json:"description,omitempty"`
    RemoteContext *RemoteContext `json:"remote_context,omitempty"`
}
    RunRequest is the JSON body for POST /kairos/run.

type Server struct {
    // Has unexported fields.
}
    Server is an HTTP handler that exposes POST /kairos/run as a KAIROS worker
    endpoint.

func NewServer(handler RunHandler, authToken string) *Server
    NewServer creates a Server with the given handler and optional Bearer
    auth token. If authToken is empty, all requests are accepted without
    authentication.

func NewServerWithSigning(handler RunHandler, authToken string, signingKey ed25519.PrivateKey) *Server
    NewServerWithSigning creates a Server with a signing key. Every SSE event
    payload is wrapped in a SignedFrame (signed with the ed25519 private
    key) before transmission. Clients must set ClientOptions.TrustKey to the
    corresponding public key to verify frames.

func NewServerWithToolForward(handler RunHandler, handlerWithForward RunHandlerWithToolForward, authToken string) *Server
    NewServerWithToolForward creates a Server that supports both plain
    RunHandler requests and exec-tools-locally requests (when the client sends
    X-Anthrogo-Exec-Tools-Locally: true). When that header is absent the plain
    handler is used.

func (s *Server) Handler() http.Handler
    Handler returns an http.Handler that serves /kairos/run,
    /kairos/run/{rid}/tool-result, and /kairos/healthz.

func (s *Server) Run(ctx context.Context, addr string) error
    Run starts an HTTP server on addr and blocks until ctx is cancelled or the
    server fails. It shuts down gracefully when ctx is done.

func (s *Server) RunAutocert(ctx context.Context, addr string, domains []string, cacheDir string) error
    RunAutocert starts an HTTPS server on addr using Let's Encrypt
    auto-provisioned certificates for the given domains. Certificates are cached
    under cacheDir. Port 443 must be reachable from the internet for the ACME
    HTTP-01 challenge. It blocks until ctx is cancelled or the server fails,
    and shuts down gracefully when ctx is done.

func (s *Server) RunTLS(ctx context.Context, addr, certFile, keyFile string) error
    RunTLS starts an HTTPS server on addr using the supplied PEM cert and key
    files. It blocks until ctx is cancelled or the server fails, and shuts down
    gracefully when ctx is done.

func (s *Server) SetHandlerWithForward(h RunHandlerWithToolForward)
    SetHandlerWithForward sets the exec-tools-locally handler on an
    existing Server. This is useful when a Server was constructed via
    NewServerWithSigning and also needs to support the exec-tools-locally
    protocol.

type SignedFrame struct {
    Payload   json.RawMessage `json:"payload"`
    Signature string          `json:"sig"` // base64 of Sign(payload)
}
    SignedFrame wraps an SSE payload with a base64 ed25519 signature over its
    canonical JSON marshalling.

func SignFrame(priv ed25519.PrivateKey, payload []byte) SignedFrame
    SignFrame signs the given payload bytes with the private key and returns a
    SignedFrame.

type ToolResult struct {
    ToolUseID string `json:"tool_use_id"`
    Text      string `json:"text"`
    IsError   bool   `json:"is_error"`
}
    ToolResult is the payload the client POSTs back to the worker after
    executing a tool locally. IsError mirrors tool.Result.IsError.

type ToolUseRequest struct {
    ToolUseID string         `json:"tool_use_id"`
    ToolName  string         `json:"tool_name"`
    ToolInput map[string]any `json:"tool_input"`
}
    ToolUseRequest is the payload sent by the worker over SSE when it needs the
    client to execute a tool call. The worker blocks waiting for the matching
    ToolResult to arrive via POST /kairos/run/<rid>/tool-result.