delegate

package
v0.9.2 Latest Latest
Warning

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

Go to latest
Published: May 1, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package delegate implements the thane_now and thane_assign delegation tools for split-model execution. A calling model delegates subtasks to cheaper/local models that run with minimal context and a filtered tool set. thane_now is the synchronous front door (the caller blocks for the result); thane_assign is the async one-shot front door (the result is delivered back through the conversation/channel when the delegate completes).

Index

Constants

View Source
const (
	ExhaustMaxIterations = iterate.ExhaustMaxIterations
	ExhaustTokenBudget   = iterate.ExhaustTokenBudget
	ExhaustWallClock     = iterate.ExhaustWallClock
	ExhaustNoOutput      = iterate.ExhaustNoOutput
	ExhaustIllegalTool   = iterate.ExhaustIllegalTool
)

Exhaustion reason constants are defined in the iterate package. These aliases preserve backward compatibility for consumers that reference them via the delegate package.

View Source
const AssignToolDescription = "Assign a bounded task to a sub-agent that runs in the background and reports its result back through the current conversation or interactive channel when complete. " +
	"Use when the work will take long enough that the calling model should not block waiting — multi-step investigation, deferred report generation, anything where the caller wants to move on while the delegate completes. " +
	"Uses compact task context by default; set context_mode=full only for continuity-sensitive work. " +
	"For an answer needed in this turn, use thane_now. " +
	"For recurring scheduled work, use thane_curate."

AssignToolDescription is the LLM-facing description for thane_assign, the async one-shot member of the thane_* family.

View Source
const NowToolDescription = "Synchronously delegate a bounded task to a sub-agent and return the result inline. " +
	"Use when the calling model needs the answer in this turn — investigation, research, summarization, controlled tool execution. " +
	"Uses compact task context by default; set context_mode=full only for continuity-sensitive work. " +
	"Blocks until the delegate completes or exhausts its budget. " +
	"For fire-and-forget background work, use thane_assign instead. " +
	"For recurring document-anchored work on a schedule, use thane_curate."

NowToolDescription is the LLM-facing description for thane_now, the sync member of the thane_* family.

Variables

This section is empty.

Functions

func AssignToolDefinition

func AssignToolDefinition() map[string]any

AssignToolDefinition returns the JSON schema for thane_assign. The schema is identical to thane_now today; future revisions will add an output target parameter so async work can land in a document or directory tree instead of the current conversation/channel.

func AssignToolHandler

func AssignToolHandler(exec *Executor) func(ctx context.Context, args map[string]any) (string, error)

AssignToolHandler returns the handler for thane_assign.

func ExtractToolsCalled

func ExtractToolsCalled(messages []llm.Message) map[string]int

ExtractToolsCalled scans a message history and returns a map of tool names to invocation counts.

func NowToolDefinition

func NowToolDefinition() map[string]any

NowToolDefinition returns the JSON schema for thane_now.

func NowToolHandler

func NowToolHandler(exec *Executor) func(ctx context.Context, args map[string]any) (string, error)

NowToolHandler returns the handler for thane_now.

Types

type Executor

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

Executor runs delegate sub-agent tasks.

func NewExecutor

func NewExecutor(logger *slog.Logger, llmClient llm.Client, rtr *router.Router, parentReg *tools.Registry, defaultModel string) *Executor

NewExecutor creates a delegate executor. The returned executor is not usable until Executor.ConfigureLoopExecution has been called with a non-nil runner and registry; without those, Executor.Execute and Executor.StartBackground will fail. The remaining Configure* and Set* methods supply optional cross-cutting wiring.

func (*Executor) ApplyProfileOverrides

func (e *Executor) ApplyProfileOverrides(overrides map[string]ProfileOverride)

ApplyProfileOverrides applies configuration overrides to builtin profiles. Only positive fields in each override replace the builtin defaults. Negative values are logged as warnings and ignored. Unknown profile names are silently ignored (config may reference profiles that don't exist yet).

func (*Executor) ConfigureLoopCompletionSink

func (e *Executor) ConfigureLoopCompletionSink(sink looppkg.CompletionSink)

ConfigureLoopCompletionSink configures the detached completion sink used by background delegate launches that report back into a conversation.

func (*Executor) ConfigureLoopExecution

func (e *Executor) ConfigureLoopExecution(runner looppkg.Runner, registry *looppkg.Registry)

ConfigureLoopExecution configures loop-backed delegate execution. When both runner and registry are set, Execute launches a one-shot child loop through the shared loops-ng path, giving delegates the same telemetry path as other loop-driven work.

func (*Executor) ConfigureSessionLifecycle

func (e *Executor) ConfigureSessionLifecycle(archiver agent.SessionArchiver, store *memory.SQLiteStore)

ConfigureSessionLifecycle configures archival and cleanup for loop-backed delegate conversations. The archiver preserves parent session linkage and archived transcripts; the conversation store is cleared after completion so ephemeral delegate turns do not accumulate in working memory.

func (*Executor) Execute

func (e *Executor) Execute(ctx context.Context, task, profileName, guidance string, tags []string) (*Result, error)

Execute runs a delegated task with the given profile and guidance. Capability tags define the delegate's tool and context scope. Elective caller tags are inherited by default; compatibility profiles may add default tags only when the caller did not request an explicit scope.

func (*Executor) ProfileNames

func (e *Executor) ProfileNames() []string

ProfileNames returns the names of all registered profiles.

func (*Executor) SetAlwaysActiveTags

func (e *Executor) SetAlwaysActiveTags(tags []string)

SetAlwaysActiveTags configures the capability tags that are automatically included in every tag-scoped delegation, regardless of which tags the caller requests. This mirrors the agent loop's always_active tag behavior.

func (*Executor) SetArchiver

func (e *Executor) SetArchiver(a *memory.ArchiveStore)

SetArchiver configures the archive store for session lifecycle tracking. When set, each Executor.Execute call creates a first-class archive session with parent linkage, and archives its messages and tool calls for inspection in the web dashboard.

func (*Executor) SetEventBus

func (e *Executor) SetEventBus(bus *events.Bus)

SetEventBus configures the event bus for delegate lifecycle events. When set, each Execute call publishes spawn and complete events so the dashboard can render delegates as ephemeral child nodes.

func (*Executor) SetLensProvider

func (e *Executor) SetLensProvider(fn func() []string)

SetLensProvider configures a function that returns the currently active global lenses. These are merged into every delegate execution's effective tag set so lens-tagged KB articles and talents apply.

func (*Executor) SetTempFileStore

func (e *Executor) SetTempFileStore(tfs interface {
	ExpandLabels(convID, text string) string
})

SetTempFileStore configures temp file label expansion for delegate task descriptions. When set, occurrences of "temp:LABEL" in the task and guidance strings are replaced with actual file paths before the delegate LLM sees the message.

func (*Executor) SetTimezone

func (e *Executor) SetTimezone(tz string)

SetTimezone configures the IANA timezone used in delegate logging and archive metadata.

func (*Executor) StartBackground

func (e *Executor) StartBackground(ctx context.Context, task, profileName, guidance string, tags []string) (string, error)

StartBackground launches a detached delegate loop that reports its completion back into the current conversation.

type Profile

type Profile struct {
	// Name is the profile identifier (e.g., "general", "ha").
	Name string

	// Description is a human-readable summary for logging.
	Description string

	// DefaultTags are compatibility capability tags applied when the
	// caller does not request an explicit tag scope.
	DefaultTags []string

	// RouterHints are passed to the router for model selection.
	RouterHints map[string]string

	// MaxIter is the maximum number of tool-calling iterations.
	MaxIter int

	// MaxTokens is the maximum cumulative output tokens before budget exhaustion.
	MaxTokens int

	// MaxDuration is the maximum wall clock time for the delegation loop.
	MaxDuration time.Duration

	// ToolTimeout is the maximum time a single tool call may run before
	// being cancelled. Zero means defaultToolTimeout.
	ToolTimeout time.Duration
}

Profile defines the configuration for a delegation context.

type ProfileOverride

type ProfileOverride struct {
	ToolTimeout time.Duration
	MaxDuration time.Duration
	MaxIter     int
	MaxTokens   int
}

ProfileOverride holds optional overrides for a delegate profile. Only positive values are applied; zero and negative fields are ignored.

type Result

type Result struct {
	ProfileName              string            `json:"profile"`
	Content                  string            `json:"content"`
	Model                    string            `json:"model"`
	Iterations               int               `json:"iterations"`
	InputTokens              int               `json:"input_tokens"`
	OutputTokens             int               `json:"output_tokens"`
	CacheCreationInputTokens int               `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int               `json:"cache_read_input_tokens"`
	Exhausted                bool              `json:"exhausted"`
	ExhaustReason            string            `json:"exhaust_reason,omitempty"`
	ToolCalls                []ToolCallOutcome `json:"tool_calls,omitempty"`
	Duration                 time.Duration     `json:"duration"`
}

Result is the outcome of a delegated task execution.

type ToolCallOutcome

type ToolCallOutcome struct {
	Name    string `json:"name"`
	Success bool   `json:"success"`
}

ToolCallOutcome records the name and success/failure of a single tool invocation during delegate execution.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL