rocketcode

Documentation

Overview

Package rocketcode provides the reusable RocketCode runtime.

Index

• Constants
• func ReplayInputFromParams(items []responses.ResponseInputItemUnionParam) ([]json.RawMessage, error)
• func ReplayInputToParams(raw []json.RawMessage) ([]responses.ResponseInputItemUnionParam, error)
• type Agent
• type AgentLoadResult
  • func LoadAgents(fsys fs.FS) AgentLoadResult
• type Agents
• type Attachment
• type ChatResponse
• type Config
• type Looper
  • func New(client *openai.Client, config Config, root *os.Root, agents Agents, ...) (Looper, error)
• type PermissionAction
• type PermissionBucket
• type PermissionRule
• type PermissionSet
  • func (ps *PermissionSet) Allow(permission, pattern string) error
  • func (ps *PermissionSet) Deny(permission, pattern string) error
  • func (ps PermissionSet) Evaluate(permission, subject string) (action PermissionAction, matched bool)
  • func (ps *PermissionSet) Set(permission, pattern string, action PermissionAction) error
• type PromptInput
• type PromptInputRole
• type PromptShellCommandExpansion
• type ProviderDiagnostic
• type ReplayDecodeError
  • func (e *ReplayDecodeError) Error() string
  • func (e *ReplayDecodeError) Unwrap() error
• type SessionEntry
• type Skill
• type SkillLoadResult
  • func LoadSkills(fsys fs.FS, root string) SkillLoadResult
• type Skills
  • func (s Skills) Find(query string) string
  • func (s Skills) FindAvailable(query string, agent *Agent) string
• type SubagentDiagnostic
• type Tool
• type ToolDiagnostic
• type ToolResult
  • func TextToolResult(output string) ToolResult

Constants

const (
	// ChatResponseAssistantMessage identifies final assistant message output.
	ChatResponseAssistantMessage = "assistant_message"
	// ChatResponseAssistantCommentary identifies assistant progress/commentary output.
	ChatResponseAssistantCommentary = "assistant_commentary"
	// ChatResponseAssistantTool identifies structured tool and subagent diagnostics.
	ChatResponseAssistantTool = "assistant_tool"
	// ChatResponseReasoningSummary identifies reasoning summary output.
	ChatResponseReasoningSummary = "reasoning_summary"
)

Functions

func ReplayInputFromParams

func ReplayInputFromParams(items []responses.ResponseInputItemUnionParam) ([]json.RawMessage, error)

ReplayInputFromParams returns SDK-native durable replay JSON after each item round-trips through responses.ResponseInputItemUnionParam.

func ReplayInputToParams

func ReplayInputToParams(raw []json.RawMessage) ([]responses.ResponseInputItemUnionParam, error)

ReplayInputToParams decodes SDK-native durable replay JSON through the OpenAI SDK input union.

Types

type Agent

type Agent struct {
	Name            string
	Description     string
	Model           string
	ReasoningEffort string
	Verbosity       string
	Prompt          string
	Location        string
	Permission      PermissionSet
	Frontmatter     map[string]any
	FileMode        fs.FileMode
}

Agent contains a single preloaded markdown agent definition.

type AgentLoadResult

type AgentLoadResult struct {
	Agents Agents
	Errors []error
}

AgentLoadResult contains loaded agents and any non-fatal load errors.

func LoadAgents

func LoadAgents(fsys fs.FS) AgentLoadResult

LoadAgents scans the top level of fsys for markdown agent files.

type Agents

type Agents struct {
	Items map[string]Agent
}

Agents contains all discovered agents keyed by name.

type Attachment

type Attachment struct {
	MIME     string `json:"mime"`
	Filename string `json:"filename,omitempty"`
	URL      string `json:"url"`
}

Attachment is a model-visible file attachment encoded as a URL, usually a data URL.

type ChatResponse

type ChatResponse struct {
	Kind     string
	Text     string
	Tool     *ToolDiagnostic
	Subagent *SubagentDiagnostic
	Provider *ProviderDiagnostic
}

ChatResponse is one user-visible response item emitted by the runtime.

type Config

type Config struct {
	Model                      shared.ResponsesModel
	ReasoningEffort            shared.ReasoningEffort
	Diagnostics                bool
	ExperimentalStrongerSkills bool
	ExpandPromptShellCommands  PromptShellCommandExpansion
	CompactThreshold           int64
	CompactionSteering         string
	ParallelToolCalls          int
	ShellOutputDir             string
	SandboxedBash              bool
	CustomTools                []Tool
	ShellEnv                   map[string]string
}

Config contains runtime settings supplied by the embedding application.

type Looper

type Looper interface {
	Loop(ctx context.Context, input <-chan PromptInput, sessionIn iter.Seq2[SessionEntry, error], sessionOut func(SessionEntry) error, interrupts <-chan os.Signal) error
}

Looper processes prompt input streams with a configured runtime.

func New

func New(
	client *openai.Client,
	config Config,
	root *os.Root,
	agents Agents,
	skills Skills,
	defaultAgent string,
	diagnosticsWriter io.Writer,
) (Looper, error)

New loads the supplied runtime dependencies and returns a configured looper.

type PermissionAction

type PermissionAction string

PermissionAction determines whether a matched operation is allowed or denied.

const (
	// PermissionAllow allows a matching operation.
	PermissionAllow PermissionAction = "allow"
	// PermissionDeny denies a matching operation.
	PermissionDeny PermissionAction = "deny"
)

type PermissionBucket

type PermissionBucket struct {
	Name  string
	Rules []PermissionRule
}

PermissionBucket groups permission rules under a named permission category.

type PermissionRule

type PermissionRule struct {
	Pattern string
	Action  PermissionAction
}

PermissionRule matches a subject pattern to a permission action.

type PermissionSet

type PermissionSet struct {
	Buckets []PermissionBucket
}

PermissionSet contains all permission buckets configured for an agent.

func (*PermissionSet) Allow

func (ps *PermissionSet) Allow(permission, pattern string) error

Allow appends an allow rule for permission and pattern.

func (*PermissionSet) Deny

func (ps *PermissionSet) Deny(permission, pattern string) error

Deny appends a deny rule for permission and pattern.

func (PermissionSet) Evaluate

func (ps PermissionSet) Evaluate(permission, subject string) (action PermissionAction, matched bool)

Evaluate returns the effective permission action for permission and subject. The matched result reports whether a configured rule explicitly matched. When matched is false, action is PermissionDeny, the default action.

func (*PermissionSet) Set

func (ps *PermissionSet) Set(permission, pattern string, action PermissionAction) error

Set appends a permission rule for permission and pattern.

type PromptInput

type PromptInput struct {
	// Role defaults to PromptInputRoleUser when empty.
	Role        PromptInputRole `json:"role,omitempty"`
	Text        string          `json:"text"`
	Attachments []Attachment    `json:"attachments,omitempty"`
	// Responses receives user-visible response items for this prompt. The runtime
	// closes it after the prompt's turn reaches a terminal state.
	Responses chan<- ChatResponse `json:"-"`
}

PromptInput is one prompt plus optional model-visible attachments.

type PromptInputRole

type PromptInputRole string

PromptInputRole identifies the instruction hierarchy role for a prompt input.

const (
	// PromptInputRoleUser identifies ordinary user prompt input.
	PromptInputRoleUser PromptInputRole = "user"
	// PromptInputRoleDeveloper identifies developer instruction prompt input.
	PromptInputRoleDeveloper PromptInputRole = "developer"
)

type PromptShellCommandExpansion

type PromptShellCommandExpansion struct {
	PrimaryPrompts  bool
	SubagentPrompts bool
	SkillPrompts    bool
	InputPrompts    bool
}

PromptShellCommandExpansion controls which prompt sources expand !`command` snippets.

type ProviderDiagnostic

type ProviderDiagnostic struct {
	Phase          string `json:"phase"`
	HTTPStatus     int    `json:"http_status,omitempty"`
	ResponseStatus string `json:"response_status,omitempty"`
	Code           string `json:"code,omitempty"`
	Message        string `json:"message,omitempty"`
	Attempt        int    `json:"attempt,omitempty"`
	RetryAfter     string `json:"retry_after,omitempty"`
	ResponseID     string `json:"response_id,omitempty"`
}

ProviderDiagnostic describes provider request diagnostics emitted when diagnostics are enabled.

type ReplayDecodeError

type ReplayDecodeError struct {
	EntryIndex int
	ItemIndex  int
	Kind       string
	Cause      error
}

ReplayDecodeError describes one durable replay item that could not be decoded through the OpenAI SDK input union.

func (*ReplayDecodeError) Error

func (e *ReplayDecodeError) Error() string

func (*ReplayDecodeError) Unwrap

func (e *ReplayDecodeError) Unwrap() error

type SessionEntry

type SessionEntry struct {
	Version     int               `json:"version"`
	Type        string            `json:"type"`
	Timestamp   time.Time         `json:"timestamp"`
	ResponseID  string            `json:"response_id,omitempty"`
	Model       string            `json:"model,omitempty"`
	ReplayInput []json.RawMessage `json:"replay_input,omitempty"`
	OutputTrace []json.RawMessage `json:"output_trace,omitempty"`
}

SessionEntry is one denormalized persisted session record.

type Skill

type Skill struct {
	Name          string
	Description   string
	License       string
	Compatibility string
	Metadata      map[string]any
	Location      string
	Content       string
}

Skill contains a single preloaded skill definition.

type SkillLoadResult

type SkillLoadResult struct {
	Skills Skills
	Errors []error
}

SkillLoadResult contains loaded skills and any non-fatal load errors.

func LoadSkills

func LoadSkills(fsys fs.FS, root string) SkillLoadResult

LoadSkills scans fsys for SKILL.md files and preloads valid skills.

type Skills

type Skills struct {
	Root  string
	Items map[string]Skill
	Dirs  []string
	// contains filtered or unexported fields
}

Skills contains all discovered skills keyed by name.

func (Skills) Find

func (s Skills) Find(query string) string

Find returns all matching skills ranked by relevance.

func (Skills) FindAvailable

func (s Skills) FindAvailable(query string, agent *Agent) string

FindAvailable returns visible skills matching query as user-facing text.

type SubagentDiagnostic

type SubagentDiagnostic struct {
	Name     string              `json:"name"`
	Label    string              `json:"label"`
	Text     string              `json:"text,omitempty"`
	Tool     *ToolDiagnostic     `json:"tool,omitempty"`
	Subagent *SubagentDiagnostic `json:"subagent,omitempty"`
	Provider *ProviderDiagnostic `json:"provider,omitempty"`
}

SubagentDiagnostic describes a subagent runtime diagnostic emitted when diagnostics are enabled.

type Tool

type Tool struct {
	Name               string
	Description        string
	Parameters         map[string]any
	Permission         string
	VisibilitySubjects []string
	Subjects           func(json.RawMessage) ([]string, error)
	Call               func(context.Context, json.RawMessage, chan<- ChatResponse) (ToolResult, error)
}

Tool is a custom function tool supplied by an embedding application.

type ToolDiagnostic

type ToolDiagnostic struct {
	Phase     string          `json:"phase"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	Result    string          `json:"result,omitempty"`
	Status    string          `json:"status,omitempty"`
	Action    json.RawMessage `json:"action,omitempty"`
}

ToolDiagnostic describes a tool runtime diagnostic emitted when diagnostics are enabled.

type ToolResult

type ToolResult struct {
	Output      string
	Attachments []Attachment
}

ToolResult is the output of a tool call, including optional model-visible attachments.

func TextToolResult

func TextToolResult(output string) ToolResult

TextToolResult returns a text-only tool result.