Documentation
¶
Overview ¶
Package speculation provides idle-time predictive execution. After the agent completes a turn, a speculative fork runs with read-only tools to predict the next action. When the user accepts, the prediction is applied; when the user types, it's discarded.
Architecture ported from Claude Code's speculation.ts.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ReadOnlyTools = map[string]bool{ "read": true, "read_file": true, "file_read": true, "FileRead": true, "grep": true, "search": true, "file_search": true, "Grep": true, "glob": true, "file_glob": true, "Glob": true, "lsp": true, "LSP": true, "list": true, "ls": true, }
ReadOnlyTools is the set of tool names safe for speculative execution.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// Callbacks set by the agent wiring.
// OnSpeculate is called to start a speculative fork.
// The callback receives a context that cancels on discard.
OnSpeculate func(ctx context.Context) (*Result, error)
// OnStateChange fires when state transitions.
OnStateChange func(old, new State)
// MaxTurns limits how long speculation runs.
MaxTurns int
// MaxDuration caps wall-clock time.
MaxDuration time.Duration
// contains filtered or unexported fields
}
Engine manages the speculation lifecycle.
func (*Engine) Discard ¶
func (e *Engine) Discard()
Discard cancels any running speculation. Called when user starts typing.
func (*Engine) Reset ¶
func (e *Engine) Reset()
Reset transitions the engine back to Idle from any terminal state (Accepted, Discarded). Allows the engine to be reused across multiple speculation cycles without creating a new Engine instance. Cancels any running speculation goroutine. Bumps the generation counter to invalidate any in-flight speculation results (bug #39 fix).
type Result ¶
type Result struct {
Summary string `json:"summary"` // human-readable prediction
ToolCalls []string `json:"tool_calls"` // predicted tool calls
StartedAt time.Time `json:"started_at"`
CompletedAt time.Time `json:"completed_at"`
}
Result holds the completed speculation output.
Source Files