orchestration

package
v0.0.0-...-f9a56e6 Latest Latest
Warning

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

 Go to latest Published: May 14, 2026 License: MPL-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package orchestration handles UTD template processing, prompt composition, and agent execution.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExpandFilePath 

func ExpandFilePath(path string) (string, error)

ExpandFilePath expands tilde and converts to absolute path. Returns the expanded path and any error.

func ExpandTilde 

func ExpandTilde(path string) (string, error)

ExpandTilde expands a leading ~ or ~/ to the user's home directory. Only handles bare ~ and ~/path, not ~user syntax. Returns the path unchanged if it does not start with ~ or ~/.

func ExtractOrigin 

func ExtractOrigin(v cue.Value) string

ExtractOrigin extracts the origin field from a CUE value.

func GenerateDryRunCommand 

func GenerateDryRunCommand(agent Agent, model, roleName string, contexts []string, workingDir string, cmdStr string) string

GenerateDryRunCommand generates the command.txt content for dry-run.

func GetCUECacheDir 

func GetCUECacheDir() (string, error)

GetCUECacheDir returns the CUE cache directory. Respects CUE_CACHE_DIR environment variable.

func GetTaskRole 

func GetTaskRole(cfg cue.Value, taskName string) string

GetTaskRole returns the role specified for a task.

func IsFilePath 

func IsFilePath(s string) bool

IsFilePath returns true if the string looks like a file path. Strings starting with ./, /, or ~ are file paths. Only bare ~ and ~/ are recognised as tilde paths; ~user syntax is not supported by ExpandTilde and is therefore not treated as a file path.

func IsUTDValid 

func IsUTDValid(fields UTDFields) bool

IsUTDValid checks if UTD fields satisfy the minimum requirement. At least one of file, command, or prompt must be specified.

func NeedsSetup 

func NeedsSetup(paths config.Paths) bool

NeedsSetup checks if auto-setup is required.

func ReadFilePath 

func ReadFilePath(path string) (string, error)

ReadFilePath reads the content of a file path, expanding tilde if present. Returns the content and any error.

func ResolveModulePath 

func ResolveModulePath(path, origin string) (string, error)

ResolveModulePath resolves an @module/ path to the CUE cache location. @module/ paths resolve relative to the cached module directory. The origin field contains the exact versioned module path (e.g., "github.com/.../task@v0.1.2") which maps directly to a cache directory.

func ValidateCommandTemplate 

func ValidateCommandTemplate(tmpl string) error

ValidateCommandTemplate checks for common template errors. Returns an error if the template contains quoted placeholders like '{{.prompt}}' since escapeForShell already wraps values in single quotes. Also detects {placeholder} syntax which should be {{.placeholder}}.

Types

type Agent 

type Agent struct {
	Name         string
	Bin          string
	Command      string
	DefaultModel string
	Models       map[string]string
	Description  string
}

Agent represents an agent configuration.

func ExtractAgent 

func ExtractAgent(cfg cue.Value, name string) (Agent, error)

ExtractAgent extracts agent configuration from CUE value.

type AutoSetup 

type AutoSetup struct {
	// contains filtered or unexported fields
}

AutoSetup performs first-run auto-setup. It detects installed AI CLI tools, prompts if needed, and writes config.

func NewAutoSetup 

func NewAutoSetup(stdout, stderr io.Writer, stdin io.Reader, isTTY bool) *AutoSetup

NewAutoSetup creates a new auto-setup handler.

func (*AutoSetup) Run 

func (a *AutoSetup) Run(ctx context.Context) (*AutoSetupResult, error)

Run executes the auto-setup flow.

type AutoSetupResult 

type AutoSetupResult struct {
	Agent      Agent
	ConfigPath string
}

AutoSetupResult contains the result of auto-setup.

type CommandData 

type CommandData map[string]string

CommandData holds data for command template substitution. Uses lowercase keys to match CUE field naming conventions.

type ComposeResult 

type ComposeResult struct {
	// Prompt is the fully composed prompt.
	Prompt string
	// Contexts is the list of contexts that were included.
	Contexts []Context
	// Selection is the context selection criteria used.
	Selection ContextSelection
	// Role is the resolved role content.
	Role string
	// RoleFile is the path to the role file (original for cwd files, temp for external/inline).
	RoleFile string
	// RoleName is the name of the role used.
	RoleName string
	// RoleResolutions tracks all roles checked during resolution for UI display.
	RoleResolutions []RoleResolution
	// Warnings contains any non-fatal issues.
	Warnings []string
}

ComposeResult contains the result of prompt composition.

type Composer 

type Composer struct {
	// contains filtered or unexported fields
}

Composer handles prompt composition from CUE configuration.

func NewComposer 

func NewComposer(processor *TemplateProcessor, workingDir string) *Composer

NewComposer creates a new prompt composer.

func (*Composer) Compose 

func (c *Composer) Compose(cfg cue.Value, selection ContextSelection, customText string) (ComposeResult, error)

Compose builds the final prompt from configuration.

func (*Composer) ComposeWithRole 

func (c *Composer) ComposeWithRole(cfg cue.Value, selection ContextSelection, roleName, customText string) (ComposeResult, error)

ComposeWithRole composes prompt and resolves role. When roleName is provided (explicit --role), errors are fatal. When using default selection, optional roles are skipped gracefully.

func (*Composer) ProcessContent 

func (c *Composer) ProcessContent(content, instructions string) (ProcessResult, error)

ProcessContent processes raw content through template substitution. This is used for file-based tasks where the content is read directly but still needs template processing for placeholders like {{.instructions}}.

func (*Composer) ResolveTask 

func (c *Composer) ResolveTask(cfg cue.Value, name, instructions string) (ProcessResult, error)

ResolveTask resolves a task by name and processes its UTD.

type Context 

type Context struct {
	Name        string
	Description string
	Content     string
	Required    bool
	Default     bool
	Tags        []string
	File        string // Source file path (if file-based)
	Status      string // "loaded", "skipped", "error"
	Error       string // Error message if resolution failed
}

Context represents a resolved context.

type ContextSelection 

type ContextSelection struct {
	// IncludeRequired always includes required contexts.
	IncludeRequired bool
	// IncludeDefaults includes default contexts (for `start` command).
	IncludeDefaults bool
	// Tags specifies which tagged contexts to include.
	Tags []string
}

ContextSelection specifies which contexts to include.

type DefaultFileReader 

type DefaultFileReader struct{}

DefaultFileReader implements FileReader using os.ReadFile.

func (*DefaultFileReader) Read 

func (r *DefaultFileReader) Read(path string) (string, error)

Read reads file contents from the filesystem.

type ExecuteConfig 

type ExecuteConfig struct {
	Agent      Agent
	Model      string
	Role       string
	RoleFile   string
	Prompt     string
	PromptFile string
	WorkingDir string
	DryRun     bool
}

ExecuteConfig holds the configuration for agent execution.

type Executor 

type Executor struct {
	// contains filtered or unexported fields
}

Executor handles agent command execution.

func NewExecutor 

func NewExecutor(workingDir string) *Executor

NewExecutor creates a new agent executor.

func (*Executor) BuildCommand 

func (e *Executor) BuildCommand(cfg ExecuteConfig) (string, error)

BuildCommand builds the agent command from template and config.

func (*Executor) Execute 

func (e *Executor) Execute(cfg ExecuteConfig) error

Execute builds and runs the agent command, replacing the current process.

func (*Executor) ExecuteCommand 

func (e *Executor) ExecuteCommand(cmdStr string, cfg ExecuteConfig) error

ExecuteCommand runs a pre-built command string, replacing the current process. Use this when the command has already been built and validated.

func (*Executor) ExecuteWithoutReplace 

func (e *Executor) ExecuteWithoutReplace(cfg ExecuteConfig) (string, error)

ExecuteWithoutReplace runs the agent command without process replacement. Useful for testing or when process replacement is not desired.

type FileReader 

type FileReader interface {
	// Read reads the contents of a file.
	Read(path string) (string, error)
}

FileReader reads file contents. This interface allows for dependency injection in tests.

type ProcessResult 

type ProcessResult struct {
	// Content is the rendered template output.
	Content string
	// TempFile is the path to the temp file created for {{.file}} placeholder.
	// Only set when the source was file-based and temp file was created.
	TempFile string
	// FileRead indicates whether a file was read.
	FileRead bool
	// CommandExecuted indicates whether a command was executed.
	CommandExecuted bool
	// Warnings contains any non-fatal issues encountered.
	Warnings []string
}

ProcessResult contains the result of template processing.

type RoleResolution 

type RoleResolution struct {
	Name     string // Role name (map key or file path)
	Status   string // "loaded", "skipped", "error"
	File     string // Source file path (if file-based)
	Optional bool   // Whether this role is optional
	Error    string // Error message if resolution failed
}

RoleResolution tracks the resolution status of a role during fallback.

type ShellRunner 

type ShellRunner interface {
	// Run executes a command and returns stdout.
	// workingDir specifies the directory to run in.
	// shell specifies the shell to use (e.g., "bash -c").
	// timeout specifies the timeout in seconds (0 = default).
	Run(command, workingDir, shell string, timeout int) (string, error)
}

ShellRunner executes shell commands and returns output. This interface allows for dependency injection in tests.

type TemplateData 

type TemplateData map[string]string

TemplateData holds the data available for UTD template substitution. Uses lowercase keys to match documented placeholder names (e.g., {{.file}}, {{.instructions}}).

type TemplateProcessor 

type TemplateProcessor struct {
	// contains filtered or unexported fields
}

TemplateProcessor handles UTD template resolution.

func NewTemplateProcessor 

func NewTemplateProcessor(fr FileReader, sr ShellRunner, workingDir string) *TemplateProcessor

NewTemplateProcessor creates a new template processor.

func (*TemplateProcessor) Process 

func (p *TemplateProcessor) Process(fields UTDFields, instructions string) (ProcessResult, error)

Process resolves a UTD template with lazy evaluation. It only reads files or executes commands if the template references them.

type UTDFields 

type UTDFields struct {
	// File is the path to read content from.
	File string
	// Command is the shell command to execute.
	Command string
	// Prompt is the template string to render.
	Prompt string
	// Shell is the shell to use for command execution (optional).
	Shell string
	// Timeout is the command timeout in seconds (optional, 0 = default).
	Timeout int
}

UTDFields represents the raw Unified Template Design (UTD) fields extracted from CUE configuration.

func ExtractUTDFields 

func ExtractUTDFields(v cue.Value) UTDFields

ExtractUTDFields extracts UTD fields from a CUE value.

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.