intent

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Mar 29, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplyRequest 

type ApplyRequest struct {
	Intent    string
	Model     string
	Provider  string
	AutoStart bool
}

ApplyRequest contains parameters for applying a new intent.

type CLICaller 

type CLICaller struct{}

CLICaller implements LLMCaller by invoking the Claude Code CLI.

func (*CLICaller) Call 

func (c *CLICaller) Call(ctx context.Context, prompt string, model string) (string, error)

Call invokes `claude -p <prompt> --output-format json [--model <model>]` and extracts the result text from the JSON response.

type DAG 

type DAG struct {
	Nodes map[string]*DAGNode
}

DAG represents the directed acyclic graph of intent node dependencies.

func BuildIntentDAG 

func BuildIntentDAG(tree *IntentTree) (*DAG, error)

BuildIntentDAG constructs a DAG from an IntentTree, detecting cycles.

func (*DAG) DetectCycle 

func (d *DAG) DetectCycle() ([]string, error)

DetectCycle uses DFS three-color marking to detect cycles.

func (*DAG) TopologicalSort 

func (d *DAG) TopologicalSort() ([][]string, error)

TopologicalSort returns layers of node IDs that can be executed in parallel.

type DAGNode 

type DAGNode struct {
	Name       string
	Node       *IntentNode
	DependsOn  []string
	DependedBy []string
}

DAGNode represents a single node in the intent DAG.

type Decomposer 

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

Decomposer breaks a high-level intent into sub-intents using an LLM.

func NewDecomposer 

func NewDecomposer(caller LLMCaller) *Decomposer

NewDecomposer creates a Decomposer with the given LLM caller.

func (*Decomposer) Decompose 

func (d *Decomposer) Decompose(ctx context.Context, intent string, model string) (*IntentTree, error)

Decompose calls the LLM to break an intent into an IntentTree.

func (*Decomposer) DecomposeIncremental 

func (d *Decomposer) DecomposeIncremental(ctx context.Context, tree *IntentTree, newIntent string, model string) ([]*IntentNode, error)

DecomposeIncremental calls the LLM to produce an updated node list for an existing tree.

type DriftItem 

type DriftItem struct {
	NodeID     string    `json:"node_id"`
	Type       DriftType `json:"type"`
	Message    string    `json:"message"`
	DetectedAt time.Time `json:"detected_at"`
}

DriftItem records a single divergence between desired and current state.

type DriftType 

type DriftType string

DriftType classifies the kind of drift between desired and current state. 

const (
	DriftNodeFailed     DriftType = "node_failed"
	DriftNodeTimeout    DriftType = "node_timeout"
	DriftNewRequirement DriftType = "new_requirement"
	DriftNodeModified   DriftType = "node_modified"
)

type Engine 

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

Engine executes an IntentTree by scheduling nodes according to DAG order.

func NewEngine 

func NewEngine(tree *IntentTree, spawner KernelSpawner, callbacks EngineCallbacks) (*Engine, error)

NewEngine creates an Engine for the given IntentTree.

func (*Engine) Execute 

func (e *Engine) Execute(ctx context.Context) error

Execute runs the intent tree using an event-driven loop.

type EngineCallbacks 

type EngineCallbacks struct {
	OnNodeStart    func(nodeID string, pid types.PID)
	OnNodeComplete func(nodeID string, result string)
	OnNodeFailed   func(nodeID string, err string)
	OnProgress     func(completed, total int)
}

EngineCallbacks provides hooks for engine lifecycle events.

type ExitStatus 

type ExitStatus struct {
	Code   int
	Reason string
	Err    error
}

ExitStatus records the exit status of an intent node execution.

type IntentID 

type IntentID string

IntentID uniquely identifies an intent tree.

type IntentNode 

type IntentNode struct {
	ID           string        `json:"id" yaml:"id"`
	Intent       string        `json:"intent" yaml:"intent"`
	Agent        string        `json:"agent,omitempty" yaml:"agent,omitempty"`
	Model        string        `json:"model,omitempty" yaml:"model,omitempty"`
	Provider     string        `json:"provider,omitempty" yaml:"provider,omitempty"`
	DependsOn    []string      `json:"depends_on,omitempty" yaml:"depends_on,omitempty"`
	State        IntentState   `json:"state" yaml:"state"`
	PID          types.PID     `json:"pid,omitempty" yaml:"pid,omitempty"`
	Result       string        `json:"result,omitempty" yaml:"result,omitempty"`
	Error        string        `json:"error,omitempty" yaml:"error,omitempty"`
	Children     []string      `json:"children,omitempty" yaml:"children,omitempty"`
	RetryCount   int           `json:"retry_count" yaml:"retry_count"`
	MaxRetries   int           `json:"max_retries" yaml:"max_retries"`
	Timeout      time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	LastFailedAt *time.Time    `json:"last_failed_at,omitempty" yaml:"last_failed_at,omitempty"`
}

IntentNode represents a single sub-intent within an IntentTree.

func (*IntentNode) CanRetry 

func (n *IntentNode) CanRetry() bool

CanRetry returns true if the node has remaining retry attempts.

func (*IntentNode) IncrRetry 

func (n *IntentNode) IncrRetry()

IncrRetry increments the retry counter and records the failure time.

type IntentState 

type IntentState string

IntentState represents the lifecycle state of an intent node or tree. 

const (
	IntentPending      IntentState = "pending"
	IntentDecomposing  IntentState = "decomposing"
	IntentAwaitConfirm IntentState = "await_confirm"
	IntentExecuting    IntentState = "executing"
	IntentCompleted    IntentState = "completed"
	IntentFailed       IntentState = "failed"
	IntentRetrying     IntentState = "retrying"
)

type IntentTree 

type IntentTree struct {
	ID           IntentID               `json:"id" yaml:"id"`
	RootIntent   string                 `json:"root_intent" yaml:"root_intent"`
	State        IntentState            `json:"state" yaml:"state"`
	Nodes        map[string]*IntentNode `json:"nodes" yaml:"nodes"`
	DesiredNodes map[string]IntentState `json:"desired_nodes,omitempty" yaml:"desired_nodes,omitempty"`
	Drifts       []DriftItem            `json:"drifts,omitempty" yaml:"drifts,omitempty"`
	CreatedAt    time.Time              `json:"created_at" yaml:"created_at"`
	CompletedAt  *time.Time             `json:"completed_at,omitempty" yaml:"completed_at,omitempty"`
}

IntentTree represents the full decomposition of a high-level intent.

func (*IntentTree) ActiveDrifts 

func (t *IntentTree) ActiveDrifts() []DriftItem

ActiveDrifts returns unresolved drift items.

func (*IntentTree) AddDrift 

func (t *IntentTree) AddDrift(item DriftItem)

AddDrift appends a drift record.

func (*IntentTree) ClearDrift 

func (t *IntentTree) ClearDrift(nodeID string)

ClearDrift removes drift records for the given node.

func (*IntentTree) ComputeDrifts 

func (t *IntentTree) ComputeDrifts() []DriftItem

ComputeDrifts scans all nodes and returns items where current != desired.

func (*IntentTree) InitDesired 

func (t *IntentTree) InitDesired()

InitDesired sets the desired state for all nodes to IntentCompleted.

func (*IntentTree) IsTerminal 

func (t *IntentTree) IsTerminal() bool

IsTerminal returns true when all nodes have reached a terminal state (completed or failed).

func (*IntentTree) MarkCompleted 

func (t *IntentTree) MarkCompleted(nodeID, result string)

MarkCompleted marks a node as completed with a result string.

func (*IntentTree) MarkFailed 

func (t *IntentTree) MarkFailed(nodeID, errMsg string)

MarkFailed marks a node as failed and cascades failure to dependent downstream nodes.

func (*IntentTree) Progress 

func (t *IntentTree) Progress() (completed, total int)

Progress returns the count of completed nodes and total nodes.

func (*IntentTree) ResetNode 

func (t *IntentTree) ResetNode(nodeID string)

ResetNode resets a node to pending state, clearing execution results but preserving config.

func (*IntentTree) RunnableNodes 

func (t *IntentTree) RunnableNodes() []*IntentNode

RunnableNodes returns all nodes whose dependencies are satisfied and state is pending or retrying.

type KernelSpawner 

type KernelSpawner interface {
	SpawnIntent(ctx context.Context, node *IntentNode) (types.PID, error)
	Wait(pid types.PID) (ExitStatus, error)
}

KernelSpawner defines the kernel operations needed by the intent engine.

type LLMCaller 

type LLMCaller interface {
	Call(ctx context.Context, prompt string, model string) (string, error)
}

LLMCaller abstracts LLM invocation for intent decomposition.

type Manager 

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

Manager handles intent lifecycle: creation, decomposition, execution, status.

func NewManager 

func NewManager(decomposer *Decomposer, spawner KernelSpawner, config ReconcilerConfig) *Manager

NewManager creates a Manager with the given decomposer, spawner, and reconciler config.

func (*Manager) Apply 

func (m *Manager) Apply(ctx context.Context, req ApplyRequest) (*IntentTree, error)

Apply decomposes a high-level intent and stores the resulting IntentTree.

func (*Manager) ApplyIncremental 

func (m *Manager) ApplyIncremental(ctx context.Context, intentID IntentID, newIntent, model, provider string) (*IntentTree, *MergeResult, error)

ApplyIncremental performs an incremental update on an existing intent tree.

func (*Manager) Confirm 

func (m *Manager) Confirm(intentID IntentID) error

Confirm transitions an intent from await_confirm to executing.

func (*Manager) Execute 

func (m *Manager) Execute(ctx context.Context, intentID IntentID, callbacks ReconcilerCallbacks) error

Execute starts execution of a confirmed intent tree using the Reconciler.

func (*Manager) ListActive 

func (m *Manager) ListActive() []*IntentTree

ListActive returns all non-terminal IntentTrees.

func (*Manager) ListAll 

func (m *Manager) ListAll() []*IntentTree

ListAll returns all IntentTrees (active and completed).

func (*Manager) Status 

func (m *Manager) Status(intentID IntentID) (*IntentTree, error)

Status returns the IntentTree for the given ID, or error if not found.

type MergeResult 

type MergeResult struct {
	AddedNodes     []string // New node IDs added to the tree
	ModifiedNodes  []string // Existing node IDs whose intent changed (reset to pending)
	UnchangedNodes []string // Existing node IDs unchanged by the merge
}

MergeResult describes the outcome of an incremental merge operation.

func MergeIncremental 

func MergeIncremental(existing *IntentTree, newNodes []*IntentNode) (*MergeResult, error)

type Reconciler 

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

Reconciler executes an IntentTree with retry, timeout, and drift management.

func NewReconciler 

func NewReconciler(tree *IntentTree, spawner KernelSpawner, config ReconcilerConfig, callbacks ReconcilerCallbacks) (*Reconciler, error)

NewReconciler creates a Reconciler for the given IntentTree.

func (*Reconciler) Execute 

func (r *Reconciler) Execute(ctx context.Context) error

Execute runs the intent tree with reconciliation (retry, timeout, drift tracking).

func (*Reconciler) MergeAndInject 

func (r *Reconciler) MergeAndInject(newNodes []*IntentNode) (*MergeResult, error)

MergeAndInject atomically merges new nodes into the tree and schedules runnable nodes. This performs the merge under the reconciler's lock to prevent data races with the event loop (H3 fix), and calls spawnRunnable to schedule new nodes (H1 fix). Used by Manager.ApplyIncremental when the reconciler is actively executing.

type ReconcilerCallbacks 

type ReconcilerCallbacks struct {
	OnNodeRetry     func(nodeID string, attempt int, maxRetries int)
	OnNodeTimeout   func(nodeID string)
	OnDriftDetected func(drift DriftItem)
	OnDriftResolved func(nodeID string)
	OnNodeStart     func(nodeID string, pid types.PID)
	OnNodeComplete  func(nodeID string, result string)
	OnNodeFailed    func(nodeID string, err string)
	OnProgress      func(completed, total int)
}

ReconcilerCallbacks provides hooks for reconciler lifecycle events.

type ReconcilerConfig 

type ReconcilerConfig struct {
	DefaultMaxRetries int
	DefaultTimeout    time.Duration
	ReconcileInterval time.Duration
	MaxReconcileDelay time.Duration
}

ReconcilerConfig holds tuning parameters for the Reconciler.

func DefaultReconcilerConfig 

func DefaultReconcilerConfig() ReconcilerConfig

DefaultReconcilerConfig returns production defaults.

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.