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
- func AssignToolDefinition() map[string]any
- func AssignToolHandler(exec *Executor) func(ctx context.Context, args map[string]any) (string, error)
- func ExtractToolsCalled(messages []llm.Message) map[string]int
- func NowToolDefinition() map[string]any
- func NowToolHandler(exec *Executor) func(ctx context.Context, args map[string]any) (string, error)
- type Executor
- func (e *Executor) ApplyProfileOverrides(overrides map[string]ProfileOverride)
- func (e *Executor) ConfigureLoopCompletionSink(sink looppkg.CompletionSink)
- func (e *Executor) ConfigureLoopExecution(runner looppkg.Runner, registry *looppkg.Registry)
- func (e *Executor) ConfigureSessionLifecycle(archiver agent.SessionArchiver, store *memory.SQLiteStore)
- func (e *Executor) Execute(ctx context.Context, task, profileName, guidance string, tags []string) (*Result, error)
- func (e *Executor) ProfileNames() []string
- func (e *Executor) SetAlwaysActiveTags(tags []string)
- func (e *Executor) SetArchiver(a *memory.ArchiveStore)
- func (e *Executor) SetEventBus(bus *events.Bus)
- func (e *Executor) SetLensProvider(fn func() []string)
- func (e *Executor) SetTempFileStore(tfs interface{ ... })
- func (e *Executor) SetTimezone(tz string)
- func (e *Executor) StartBackground(ctx context.Context, task, profileName, guidance string, tags []string) (string, error)
- type Profile
- type ProfileOverride
- type Result
- type ToolCallOutcome
Constants ¶
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.
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.
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 ¶
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 ¶
ExtractToolsCalled scans a message history and returns a map of tool names to invocation counts.
func NowToolDefinition ¶
NowToolDefinition returns the JSON schema 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 ¶
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 ¶
ProfileNames returns the names of all registered profiles.
func (*Executor) SetAlwaysActiveTags ¶
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 ¶
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 ¶
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 ¶
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 ¶
SetTimezone configures the IANA timezone used in delegate logging and archive metadata.
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 ¶
ToolCallOutcome records the name and success/failure of a single tool invocation during delegate execution.