runtime

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 24, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MatchesAnyName 

func MatchesAnyName(actual string, expected ...string) bool

MatchesAnyName compares against a small list of allowed names.

func MatchesName 

func MatchesName(actual, expected string) bool

MatchesName compares names case-insensitively after trimming whitespace.

func ModuleOrNil 

func ModuleOrNil[T ModuleHooks](host Host, newFn func(Host) T) T

ModuleOrNil returns nil when the host is absent, otherwise it constructs the module.

func ZerologFromHost 

func ZerologFromHost(host Host) zerolog.Logger

ZerologFromHost extracts a zerolog.Logger from a Host. Returns zerolog.Nop() if the underlying logger is not a zerolog.Logger.

Types

type AssistantMessageInfo 

type AssistantMessageInfo struct {
	Body             string
	Model            string
	PromptTokens     int64
	CompletionTokens int64
}

AssistantMessageInfo is a generic assistant response.

type CommandCall 

type CommandCall struct {
	Name    string
	Args    []string
	RawArgs string
	Scope   CommandScope
	Reply   func(format string, args ...any)
}

CommandCall is a concrete command execution request.

type CommandDefinition 

type CommandDefinition struct {
	Name           string
	Description    string
	Args           string
	Aliases        []string
	RequiresPortal bool
	RequiresLogin  bool
	AdminOnly      bool
}

CommandDefinition describes a chat command exposed by a module.

type CommandIntegration 

type CommandIntegration interface {
	Name() string
	CommandDefinitions(ctx context.Context, scope CommandScope) []CommandDefinition
	ExecuteCommand(ctx context.Context, call CommandCall) (handled bool, err error)
}

CommandIntegration is the pluggable seam for command definitions/execution.

type CommandScope 

type CommandScope struct {
	Client any
	Portal any
	Meta   any
	Event  any
}

CommandScope carries command execution context without importing connector internals.

type CompactionLifecycleEvent 

type CompactionLifecycleEvent struct {
	Client              any
	Portal              any
	Meta                any
	Phase               CompactionLifecyclePhase
	Attempt             int
	ContextWindowTokens int
	RequestedTokens     int
	PromptTokens        int
	MessagesBefore      int
	MessagesAfter       int
	TokensBefore        int
	TokensAfter         int
	DroppedCount        int
	Reason              string
	WillRetry           bool
	Error               string
}

CompactionLifecycleEvent provides compaction lifecycle details to integrations.

type CompactionLifecycleIntegration 

type CompactionLifecycleIntegration interface {
	Name() string
	OnCompactionLifecycle(ctx context.Context, evt CompactionLifecycleEvent)
}

CompactionLifecycleIntegration consumes compaction lifecycle events.

type CompactionLifecyclePhase 

type CompactionLifecyclePhase string

CompactionLifecyclePhase describes runtime compaction lifecycle hooks. 

const (
	CompactionLifecyclePreFlush CompactionLifecyclePhase = "pre_flush"
	CompactionLifecycleStart    CompactionLifecyclePhase = "start"
	CompactionLifecycleEnd      CompactionLifecyclePhase = "end"
	CompactionLifecycleFail     CompactionLifecyclePhase = "fail"
	CompactionLifecycleRefresh  CompactionLifecyclePhase = "post_refresh"
)

type CompletionResult 

type CompletionResult struct {
	AssistantMessage openai.ChatCompletionMessageParamUnion
	ToolCalls        []CompletionToolCall
	Done             bool
}

CompletionResult represents a model completion response.

type CompletionToolCall 

type CompletionToolCall struct {
	ID       string
	Name     string
	ArgsJSON string
}

CompletionToolCall represents a tool call from a model completion.

type ContextOverflowCall 

type ContextOverflowCall struct {
	Client          any
	Portal          any
	Meta            any
	Prompt          []openai.ChatCompletionMessageParamUnion
	RequestedTokens int
	ModelMaxTokens  int
	Attempt         int
}

ContextOverflowCall contains context-overflow retry state.

type EventIntegration 

type EventIntegration interface {
	Name() string
	OnSessionMutation(ctx context.Context, evt SessionMutationEvent)
	OnFileChanged(ctx context.Context, evt FileChangedEvent)
}

EventIntegration consumes session/file events.

type FileChangedEvent 

type FileChangedEvent struct {
	Client any
	Portal any
	Meta   any
	Path   string
}

FileChangedEvent is emitted when a file write/edit/apply_patch updates workspace data.

type Host 

type Host interface {
	Logger() Logger
	RawLogger() any
	Now() time.Time
	ResolvePortalByRoomID(ctx context.Context, roomID string) any
	ResolveDefaultPortal(ctx context.Context) any
	ResolveLastActivePortal(ctx context.Context, agentID string) any
	DispatchInternalMessage(ctx context.Context, portal any, meta any, message string, source string) error
	SendAssistantMessage(ctx context.Context, portal any, body string) error
	RequestNow(ctx context.Context, reason string)
	ToolDefinitionByName(name string) (ToolDefinition, bool)
	ExecuteBuiltinTool(ctx context.Context, scope ToolScope, name string, rawArgsJSON string) (string, error)
	ResolveWorkspaceDir() string
	BridgeDB() any
	BridgeID() string
	LoginID() string
	ModuleEnabled(name string) bool
	ModuleConfig(name string) map[string]any
	AgentModuleConfig(agentID string, module string) map[string]any

	GetOrCreatePortal(ctx context.Context, portalID string, receiver string, displayName string, setupMeta func(meta any)) (portal any, roomID string, err error)
	SavePortal(ctx context.Context, portal any, reason string) error
	PortalRoomID(portal any) string
	PortalKeyString(portal any) string

	GetModuleMeta(meta any, key string) any
	SetModuleMeta(meta any, key string, value any)
	IsSimpleMode(meta any) bool
	AgentIDFromMeta(meta any) string
	CompactionCount(meta any) int
	IsGroupChat(ctx context.Context, portal any) bool
	IsInternalRoom(meta any) bool
	PortalMeta(portal any) any
	CloneMeta(portal any) any
	SetMetaField(meta any, key string, value any)

	RecentMessages(ctx context.Context, portal any, count int) []MessageSummary
	LastAssistantMessage(ctx context.Context, portal any) (id string, timestamp int64)
	WaitForAssistantMessage(ctx context.Context, portal any, afterID string, afterTS int64) (*AssistantMessageInfo, bool)

	RunHeartbeatOnce(ctx context.Context, reason string) (status string, reasonMsg string)
	ResolveHeartbeatSessionPortal(agentID string) (portal any, sessionKey string, err error)
	ResolveHeartbeatSessionKey(agentID string) string
	HeartbeatAckMaxChars(agentID string) int
	EnqueueSystemEvent(sessionKey string, text string, agentID string)
	PersistSystemEvents()
	ResolveLastTarget(agentID string) (channel string, target string, ok bool)

	ResolveAgentID(raw string, fallbackDefault string) string
	NormalizeAgentID(raw string) string
	AgentExists(normalizedID string) bool
	DefaultAgentID() string
	AgentTimeoutSeconds() int
	UserTimezone() (tz string, loc *time.Location)
	NormalizeThinkingLevel(raw string) (string, bool)

	EffectiveModel(meta any) string
	ContextWindow(meta any) int

	MergeDisconnectContext(ctx context.Context) (context.Context, context.CancelFunc)
	BackgroundContext(ctx context.Context) context.Context

	NewCompletion(ctx context.Context, model string, messages []openai.ChatCompletionMessageParamUnion, toolParams any) (*CompletionResult, error)

	IsToolEnabled(meta any, toolName string) bool
	AllToolDefinitions() []ToolDefinition
	ExecuteToolInContext(ctx context.Context, portal any, meta any, name string, argsJSON string) (string, error)
	ToolsToOpenAIParams(tools []ToolDefinition) any

	ReadTextFile(ctx context.Context, agentID string, path string) (content string, filePath string, found bool, err error)
	WriteTextFile(ctx context.Context, portal any, meta any, agentID string, mode string, path string, content string, maxBytes int) (finalPath string, err error)

	SmartTruncatePrompt(prompt []openai.ChatCompletionMessageParamUnion, ratio float64) []openai.ChatCompletionMessageParamUnion
	EstimateTokens(prompt []openai.ChatCompletionMessageParamUnion, model string) int
	CompactorReserveTokens() int
	SilentReplyToken() string
	OverflowFlushConfig() (enabled *bool, softThresholdTokens int, prompt string, systemPrompt string)

	IsLoggedIn() bool
	SessionPortals(ctx context.Context, loginID string, agentID string) ([]SessionPortalInfo, error)
	LoginDB() any
}

Host is the runtime surface shared by integration modules. It is intentionally direct: modules call host methods rather than retrieving nested capability objects or type-asserting optional host adapters.

type LifecycleIntegration 

type LifecycleIntegration interface {
	Start(ctx context.Context) error
	Stop()
}

LifecycleIntegration is an optional capability for integrations that need runtime start/stop hooks.

type Logger 

type Logger interface {
	Debug(msg string, fields map[string]any)
	Info(msg string, fields map[string]any)
	Warn(msg string, fields map[string]any)
	Error(msg string, fields map[string]any)
}

Logger is a minimal structured logger abstraction.

type LoginLifecycleIntegration 

type LoginLifecycleIntegration interface {
	StopForLogin(bridgeID, loginID string)
}

LoginLifecycleIntegration is an optional capability for integrations that need per-login shutdown hooks.

type LoginPurgeIntegration 

type LoginPurgeIntegration interface {
	Name() string
	PurgeForLogin(ctx context.Context, scope LoginScope) error
}

LoginPurgeIntegration performs per-login data cleanup.

type LoginScope 

type LoginScope struct {
	Client   any
	Login    any
	BridgeID string
	LoginID  string
}

LoginScope carries per-login cleanup scope.

type MessageSummary 

type MessageSummary struct {
	Role string
	Body string
}

MessageSummary is a generic message summary.

type ModuleFactory 

type ModuleFactory func(host Host) ModuleHooks

ModuleFactory constructs a module instance from the runtime host.

type ModuleHooks 

type ModuleHooks interface {
	Name() string
}

ModuleHooks is the base contract every integration module implements.

type PromptIntegration 

type PromptIntegration interface {
	Name() string
	AdditionalSystemMessages(ctx context.Context, scope PromptScope) []openai.ChatCompletionMessageParamUnion
	AugmentPrompt(ctx context.Context, scope PromptScope, prompt []openai.ChatCompletionMessageParamUnion) []openai.ChatCompletionMessageParamUnion
}

PromptIntegration is the pluggable surface for prompt/system message augmentation.

type PromptScope 

type PromptScope struct {
	Client any
	Portal any
	Meta   any
}

PromptScope carries prompt-building context without coupling to connector internals.

type SessionMutationEvent 

type SessionMutationEvent struct {
	Client     any
	Portal     any
	Meta       any
	SessionKey string
	Force      bool
	Kind       SessionMutationKind
}

SessionMutationEvent is emitted when chat/session data changes.

type SessionMutationKind 

type SessionMutationKind string

SessionMutationKind describes why session context changed. 

const (
	SessionMutationUnknown SessionMutationKind = "unknown"
	SessionMutationMessage SessionMutationKind = "message"
	SessionMutationReplay  SessionMutationKind = "replay"
	SessionMutationEdit    SessionMutationKind = "edit"
	SessionMutationDelete  SessionMutationKind = "delete"
)

type SessionPortalInfo 

type SessionPortalInfo struct {
	Key       string
	PortalKey any
}

SessionPortalInfo is a generic portal reference for session listing.

type SettingSource 

type SettingSource string

SettingSource indicates where a setting value came from. 

const (
	SourceAgentPolicy    SettingSource = "agent_policy"
	SourceRoomOverride   SettingSource = "room_override"
	SourceUserDefault    SettingSource = "user_default"
	SourceProviderConfig SettingSource = "provider_config"
	SourceGlobalDefault  SettingSource = "global_default"
	SourceModelLimit     SettingSource = "model_limitation"
	SourceProviderLimit  SettingSource = "provider_limitation"
)

type ToolApprovalIntegration 

type ToolApprovalIntegration interface {
	Name() string
	ToolApprovalRequirement(toolName string, args map[string]any) (handled bool, required bool, action string)
}

ToolApprovalIntegration is an optional seam for tool approval policy overrides.

type ToolCall 

type ToolCall struct {
	Name        string
	Args        map[string]any
	RawArgsJSON string
	Scope       ToolScope
}

ToolCall is a concrete tool execution request.

type ToolDefinition 

type ToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
	Execute     func(ctx context.Context, args map[string]any) (string, error)
}

ToolDefinition describes a callable tool.

type ToolIntegration 

type ToolIntegration interface {
	Name() string
	ToolDefinitions(ctx context.Context, scope ToolScope) []ToolDefinition
	ExecuteTool(ctx context.Context, call ToolCall) (handled bool, result string, err error)
	ToolAvailability(ctx context.Context, scope ToolScope, toolName string) (known bool, available bool, source SettingSource, reason string)
}

ToolIntegration is the pluggable surface for tool definitions/availability/execution.

type ToolScope 

type ToolScope struct {
	Client any
	Portal any
	Meta   any
}

ToolScope carries integration context without coupling to connector internals.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.