types

Documentation

Index

• Variables
• func SummarizeInput(input map[string]any) string
• func TruncateString(s string, maxLen int) string
• type AssistantMessage
• type Config
• type ContentBlock
  • func (b *ContentBlock) GetUnifiedToolID() string
• type StreamMessage
  • func (m *StreamMessage) GetContentBlocks() []ContentBlock
• type UsageStats

Variables

var (
	// ErrDangerBlocked indicates that a command or input was intercepted and blocked by the WAF (Detector).
	ErrDangerBlocked = errors.New("danger event blocked: input matched forbidden patterns")

	// ErrInvalidConfig indicates that the provided configuration is invalid or missing required fields.
	ErrInvalidConfig = errors.New("invalid execution configuration")

	// ErrSessionNotFound indicates that the requested session does not exist in the pool.
	ErrSessionNotFound = errors.New("session not found")

	// ErrSessionDead indicates that the session is no longer alive and cannot be used.
	ErrSessionDead = errors.New("session is dead")

	// ErrTimeout indicates that an operation timed out before completion.
	ErrTimeout = errors.New("operation timed out")

	// ErrInputTooLarge indicates that the input exceeds the maximum allowed size.
	ErrInputTooLarge = errors.New("input exceeds maximum allowed size")

	// ErrProcessStart indicates that the CLI process failed to start.
	ErrProcessStart = errors.New("failed to start CLI process")

	// ErrPipeClosed indicates that the pipe (stdin/stdout/stderr) is closed.
	ErrPipeClosed = errors.New("pipe is closed")
)

Standard Sentinel Errors for the HotPlex SDK

Functions

func SummarizeInput

func SummarizeInput(input map[string]any) string

SummarizeInput creates a human-readable summary of tool input. Uses rune-level truncation to avoid creating invalid UTF-8.

func TruncateString

func TruncateString(s string, maxLen int) string

TruncateString truncates a string to a maximum length for logging. Uses rune-level truncation to avoid creating invalid UTF-8.

Types

type AssistantMessage

type AssistantMessage struct {
	ID      string         `json:"id,omitempty"`      // Unique message ID
	Type    string         `json:"type,omitempty"`    // Typically "message"
	Role    string         `json:"role,omitempty"`    // Typically "assistant"
	Content []ContentBlock `json:"content,omitempty"` // Sequence of text and tool blocks
}

AssistantMessage represents the structured message emitted by the model.

type Config

type Config struct {
	WorkDir          string // Absolute path to the isolated sandbox directory where CLI operations occur
	SessionID        string // Unique identifier used to route the request to a persistent process in the pool
	TaskInstructions string // Per-task instructions or objective prepended to the user prompt
}

Config defines the execution context for a single HotPlex interaction cycle (turn).

type ContentBlock

type ContentBlock struct {
	Type      string         `json:"type"`                  // Block type: "text", "tool_use", "tool_result"
	Text      string         `json:"text,omitempty"`        // Raw text content (for type="text")
	Name      string         `json:"name,omitempty"`        // Tool name (for type="tool_use")
	ID        string         `json:"id,omitempty"`          // Block identifier
	ToolUseID string         `json:"tool_use_id,omitempty"` // References the original tool_use (for type="tool_result")
	Input     map[string]any `json:"input,omitempty"`       // Tool input JSON (for type="tool_use")
	Content   string         `json:"content,omitempty"`     // Result content (for type="tool_result")
	IsError   bool           `json:"is_error,omitempty"`    // Whether the tool result indicates a failure
}

ContentBlock represents an atomic unit of model output (text or tool call).

func (*ContentBlock) GetUnifiedToolID

func (b *ContentBlock) GetUnifiedToolID() string

GetUnifiedToolID returns a tool identifier suitable for matching calls with results.

type StreamMessage

type StreamMessage struct {
	Message      *AssistantMessage `json:"message,omitempty"`        // Details of an assistant-generated message
	Input        map[string]any    `json:"input,omitempty"`          // Arguments passed to a tool invocation
	Type         string            `json:"type"`                     // Event category: "assistant", "tool_use", "result", "thought", etc.
	Timestamp    string            `json:"timestamp,omitempty"`      // ISO8601 timestamp of the event
	SessionID    string            `json:"session_id,omitempty"`     // The persistent session identifier in the CLI's internal DB
	Role         string            `json:"role,omitempty"`           // Message role: "user", "assistant", or "system"
	Name         string            `json:"name,omitempty"`           // Name of the tool being used or the block type
	Output       string            `json:"output,omitempty"`         // Raw string output from a tool or assistant
	Status       string            `json:"status,omitempty"`         // Lifecycle status of the event (e.g., "running", "success")
	Error        string            `json:"error,omitempty"`          // Detailed error message if an operation fails
	Content      []ContentBlock    `json:"content,omitempty"`        // Hierarchical content blocks (text, tool_use, etc.)
	Duration     int               `json:"duration_ms,omitempty"`    // Execution time in milliseconds for "result" messages
	Subtype      string            `json:"subtype,omitempty"`        // Fine-grained type classification (e.g., for "result" events)
	IsError      bool              `json:"is_error,omitempty"`       // Flag indicating if the overall turn resulted in an error
	TotalCostUSD float64           `json:"total_cost_usd,omitempty"` // Cumulative cost of the turn in USD
	Usage        *UsageStats       `json:"usage,omitempty"`          // Precise token consumption for the turn
	Result       string            `json:"result,omitempty"`         // Final summarized result of the execution
}

StreamMessage represents a single event in the stream-json format emitted by the Claude Code CLI. This is the internal wire protocol used for communication between the CLI and the SDK.

func (*StreamMessage) GetContentBlocks

func (m *StreamMessage) GetContentBlocks() []ContentBlock

GetContentBlocks returns the primary content blocks of the message, handling nested assistant structures.

type UsageStats

type UsageStats struct {
	InputTokens           int32 `json:"input_tokens"`                          // Total tokens in the prompt (including system and context)
	OutputTokens          int32 `json:"output_tokens"`                         // Total tokens generated by the model
	CacheWriteInputTokens int32 `json:"cache_creation_input_tokens,omitempty"` // Tokens saved to the provider's prompt cache
	CacheReadInputTokens  int32 `json:"cache_read_input_tokens,omitempty"`     // Tokens retrieved from the provider's prompt cache
}

UsageStats represents the token consumption breakdown for a single execution turn.