engine

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package engine adapts EXTERNAL agentic CLIs (Claude Code, Codex, Copilot, OpenCode) into a normalized event stream.

TRANSITIONAL — DEVELOPMENT HARNESS, NOT THE STANDALONE PRODUCT.

The browser path that spawns one of these CLIs as its reasoning runtime is a dev/testing harness. The standalone Facet application (Release A) bundles a pinned compa kernel as its conversational driver and binds Facet tools NATIVELY, in-process -- it does not spawn a user-installed external CLI, and it does not host Facet through Facet's own module-v2 projection.

This package is retained because it works and exercises the intent -> tool selection -> artifact chain end to end. Do NOT build new product architecture on top of it. See docs/RELEASE_MANIFEST.md section 6.

These adapters remain legitimately useful for Release C, where an external CLI IS the intended reasoning driver -- the distinction is which release shape is being served, not whether the code is good.

Index

Constants

View Source 
const (
	EventSession    = "session"
	EventTextDelta  = "text_delta"
	EventThinkDelta = "think_delta"
	EventToolUse    = "tool_use"
	EventToolResult = "tool_result"
	EventQuestion   = "question"
	EventPermission = "permission"
	EventDone       = "done"
	EventError      = "error"
)

Event type constants for NormalizedEvent.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClaudeAdapter 

type ClaudeAdapter struct {
	Executable string
}

ClaudeAdapter implements EngineAdapter for Claude Code CLI.

func NewClaudeAdapter 

func NewClaudeAdapter() *ClaudeAdapter

NewClaudeAdapter creates a new ClaudeAdapter instance.

func (*ClaudeAdapter) BuildTurnArgs 

func (a *ClaudeAdapter) BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)

BuildTurnArgs constructs one autonomous Claude invocation.

func (*ClaudeAdapter) DisplayName 

func (a *ClaudeAdapter) DisplayName() string

func (*ClaudeAdapter) ExecutableName 

func (a *ClaudeAdapter) ExecutableName() string

func (*ClaudeAdapter) Name 

func (a *ClaudeAdapter) Name() string

func (*ClaudeAdapter) NormalizeEvent 

func (a *ClaudeAdapter) NormalizeEvent(line []byte) (normalized *NormalizedEvent, err error)

NormalizeEvent normalizes a raw Claude stream-json line into a NormalizedEvent.

type CodexAdapter 

type CodexAdapter struct {
	Executable string
}

CodexAdapter implements EngineAdapter for the OpenAI Codex CLI.

func NewCodexAdapter 

func NewCodexAdapter() *CodexAdapter

func (*CodexAdapter) BuildTurnArgs 

func (a *CodexAdapter) BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)

func (*CodexAdapter) DisplayName 

func (a *CodexAdapter) DisplayName() string

func (*CodexAdapter) ExecutableName 

func (a *CodexAdapter) ExecutableName() string

func (*CodexAdapter) Name 

func (a *CodexAdapter) Name() string

func (*CodexAdapter) NormalizeEvent 

func (a *CodexAdapter) NormalizeEvent(line []byte) (*NormalizedEvent, error)

type CompaKernelAdapter added in v1.1.0 

type CompaKernelAdapter struct {
	Executable string
}

CompaKernelAdapter implements EngineAdapter for the external Compa kernel. This is the standalone composition adapter: Facet UI operates the separately installed Compa kernel process.

func NewCompaKernelAdapter added in v1.1.0 

func NewCompaKernelAdapter() *CompaKernelAdapter

NewCompaKernelAdapter constructs a new CompaKernelAdapter.

func (*CompaKernelAdapter) BuildTurnArgs added in v1.1.0 

func (a *CompaKernelAdapter) BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)

BuildTurnArgs constructs command line arguments for the kernel agent.

func (*CompaKernelAdapter) DisplayName added in v1.1.0 

func (a *CompaKernelAdapter) DisplayName() string

func (*CompaKernelAdapter) ExecutableName added in v1.1.0 

func (a *CompaKernelAdapter) ExecutableName() string

func (*CompaKernelAdapter) Name added in v1.1.0 

func (a *CompaKernelAdapter) Name() string

func (*CompaKernelAdapter) NormalizeEvent added in v1.1.0 

func (a *CompaKernelAdapter) NormalizeEvent(line []byte) (*NormalizedEvent, error)

NormalizeEvent parses output from the kernel agent.

type CopilotAdapter 

type CopilotAdapter struct {
	Executable string
	// contains filtered or unexported fields
}

CopilotAdapter implements EngineAdapter for GitHub Copilot CLI.

func NewCopilotAdapter 

func NewCopilotAdapter() *CopilotAdapter

NewCopilotAdapter creates a new CopilotAdapter instance.

func (*CopilotAdapter) BuildTurnArgs 

func (a *CopilotAdapter) BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)

BuildTurnArgs constructs one autonomous Copilot invocation.

func (*CopilotAdapter) DisplayName 

func (a *CopilotAdapter) DisplayName() string

func (*CopilotAdapter) ExecutableName 

func (a *CopilotAdapter) ExecutableName() string

func (*CopilotAdapter) Name 

func (a *CopilotAdapter) Name() string

func (*CopilotAdapter) NormalizeEvent 

func (a *CopilotAdapter) NormalizeEvent(line []byte) (*NormalizedEvent, error)

NormalizeEvent parses a GitHub Copilot event line into a NormalizedEvent.

type EngineAdapter 

type EngineAdapter interface {
	Name() string
	DisplayName() string
	ExecutableName() string
	BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)
	NormalizeEvent(line []byte) (*NormalizedEvent, error)
}

EngineAdapter defines the interface for interacting with different agent CLI engines.

func GetAdapter 

func GetAdapter(name string) EngineAdapter

GetAdapter returns the EngineAdapter corresponding to the given name. Supported names: "claude", "opencode", "codex", and "copilot". Defaults to "claude" if name is empty or unrecognized.

func ListAdapters 

func ListAdapters() []EngineAdapter

ListAdapters returns a slice of all registered standard adapters.

type GenericAdapter 

type GenericAdapter struct {
	Executable string
}

GenericAdapter implements a flexible fallback EngineAdapter for arbitrary CLI tools.

func NewGenericAdapter 

func NewGenericAdapter() *GenericAdapter

NewGenericAdapter creates a new GenericAdapter instance.

func (*GenericAdapter) BuildArgs 

func (a *GenericAdapter) BuildArgs(dir string, mode string, extraArgs []string) ([]string, error)

BuildArgs constructs the arguments by simply returning extraArgs.

func (*GenericAdapter) DisplayName 

func (a *GenericAdapter) DisplayName() string

func (*GenericAdapter) ExecutableName 

func (a *GenericAdapter) ExecutableName() string

func (*GenericAdapter) FormatUserMessage 

func (a *GenericAdapter) FormatUserMessage(prompt string) ([]byte, error)

FormatUserMessage formats a prompt into a standard user message JSON payload.

func (*GenericAdapter) Name 

func (a *GenericAdapter) Name() string

func (*GenericAdapter) NormalizeEvent 

func (a *GenericAdapter) NormalizeEvent(line []byte) (*NormalizedEvent, error)

NormalizeEvent normalizes a JSON or plain-text line into a NormalizedEvent.

type NormalizedEvent 

type NormalizedEvent struct {
	Type       string         `json:"type"`
	SessionID  string         `json:"session_id,omitempty"`
	Content    string         `json:"content,omitempty"`
	Thinking   string         `json:"thinking,omitempty"`
	ToolName   string         `json:"tool_name,omitempty"`
	ToolID     string         `json:"tool_id,omitempty"`
	ToolInput  any            `json:"tool_input,omitempty"`
	ToolOutput string         `json:"tool_output,omitempty"`
	IsError    bool           `json:"is_error,omitempty"`
	CostUSD    float64        `json:"cost_usd,omitempty"`
	DurationMs int64          `json:"duration_ms,omitempty"`
	Tokens     int64          `json:"tokens,omitempty"`
	Question   any            `json:"question,omitempty"`
	Raw        map[string]any `json:"raw,omitempty"`
}

NormalizedEvent is a unified, engine-agnostic event model for CLI stream events.

type OpenCodeAdapter 

type OpenCodeAdapter struct {
	Executable string
}

OpenCodeAdapter implements EngineAdapter for OpenCode CLI.

func NewOpenCodeAdapter 

func NewOpenCodeAdapter() *OpenCodeAdapter

NewOpenCodeAdapter creates a new OpenCodeAdapter instance.

func (*OpenCodeAdapter) BuildTurnArgs 

func (a *OpenCodeAdapter) BuildTurnArgs(dir, mode, prompt, nativeID string, extraArgs []string) ([]string, error)

BuildTurnArgs constructs one autonomous OpenCode invocation.

func (*OpenCodeAdapter) DisplayName 

func (a *OpenCodeAdapter) DisplayName() string

func (*OpenCodeAdapter) ExecutableName 

func (a *OpenCodeAdapter) ExecutableName() string

func (*OpenCodeAdapter) Name 

func (a *OpenCodeAdapter) Name() string

func (*OpenCodeAdapter) NormalizeEvent 

func (a *OpenCodeAdapter) NormalizeEvent(line []byte) (*NormalizedEvent, error)

NormalizeEvent parses an OpenCode event line into a NormalizedEvent.

type QuestionItem 

type QuestionItem struct {
	Header      string           `json:"header,omitempty"`
	Question    string           `json:"question"`
	MultiSelect bool             `json:"multi_select,omitempty"`
	Options     []QuestionOption `json:"options,omitempty"`
}

QuestionItem represents a single question prompt with optional options and multi-selection.

type QuestionOption 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

QuestionOption represents a single option in a question item.

type QuestionSpec 

type QuestionSpec struct {
	Questions []QuestionItem `json:"questions,omitempty"`
	Raw       string         `json:"raw,omitempty"`
}

QuestionSpec represents structured questions parsed from an agent's output.

func ExtractQuestion 

func ExtractQuestion(text string) (*QuestionSpec, string, bool)

ExtractQuestion checks if text contains a fenced ```question JSON block and parses it. Returns the parsed QuestionSpec, the text with the block removed, and a boolean indicating match.

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.