tools

package
v0.1.0-p8a.1 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 56 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	NodeInvocationObservationPrepared   = "prepared"
	NodeInvocationObservationDispatched = "dispatched"
	NodeInvocationObservationCompleted  = "completed"
	NodeInvocationObservationStatus     = "status"
	NodeInvocationObservationUncertain  = "uncertain"
	NodeInvocationObservationRejected   = "rejected"
	NodeInvocationObservationCancel     = "cancel"
)
View Source 
const (
	NodeTerminalObservationPrepared = "prepared"
	NodeTerminalObservationOpened   = "opened"
	NodeTerminalObservationStatus   = "status"
	NodeTerminalObservationSignal   = "signal"
	NodeTerminalObservationClosed   = "closed"
	NodeTerminalObservationUnknown  = "unknown"
)
View Source 
const (
	MaxRegexPatternLength = 200
	RegexSearchToolName   = "tool_search_tool_regex"
	BM25SearchToolName    = "tool_search_tool_bm25"
)

Variables

View Source 
var (
	ErrSessionNotFound = errors.New("session not found")
	ErrSessionDone     = errors.New("session already completed")
	ErrPTYNotSupported = errors.New("PTY is not supported on this platform")
	ErrNoStdin         = errors.New("no stdin available")
	ErrSessionWait     = errors.New("session completion is unavailable")
)
View Source 
var ErrNodeDiscoveryStale = errors.New("node discovery revision is stale")

ErrNodeDiscoveryStale marks a failed atomic preparation revalidation.

View Source 
var ErrRemoteWorkspaceUnavailable = errors.New("remote workspace unavailable")

Functions

func NodeFileApprovalAction 

func NodeFileApprovalAction(toolName string, arguments map[string]any) (string, bool, error)

NodeFileApprovalAction renders the exact operator-visible action from the retained file-transfer plan. The boolean is false for non-file tools.

func RoutedNodeFileArtifactOwner 

func RoutedNodeFileArtifactOwner(
	ctx context.Context,
	toolCallID string,
) (nodes.TransferArtifactOwner, error)

RoutedNodeFileArtifactOwner derives the canonical P2 owner used to reuse a committed node download from a later tool call on the same routed authority.

func SafeApprovalDenialResult 

func SafeApprovalDenialResult(err error) (*toolshared.ToolResult, bool)

SafeApprovalDenialResult returns a tool-authored, model-safe denial for an approval-preparation error. Ordinary errors are never forwarded to the model through this path.

func ToolLogArguments 

func ToolLogArguments(toolName string, arguments map[string]any) map[string]any

ToolLogArguments returns bounded log fields without retaining file paths, artifact references, transfer identities, or discovery authority.

Types

type AgentScopedTool 

type AgentScopedTool interface {
	ToolEnabledForAgent(agentID string) bool
}

AgentScopedTool lets a runtime tool deny registration for agents that do not hold its explicit out-of-band grant. This is checked before the tool is exposed to the agent's registry, so delegated agents do not discover tools they cannot use.

type ApprovalArgumentsProvider 

type ApprovalArgumentsProvider interface {
	ApprovalArguments(ctx context.Context, args map[string]any) (map[string]any, error)
}

ApprovalArgumentsProvider lets a trusted tool bind durable human approval to runtime-prepared authority rather than only to model-authored arguments. Implementations may persist prepared state, but must return the same canonical arguments when the same tool call is resumed.

type BM25SearchTool 

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

func NewBM25SearchTool 

func NewBM25SearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *BM25SearchTool

func (*BM25SearchTool) Description 

func (t *BM25SearchTool) Description() string

func (*BM25SearchTool) Execute 

func (t *BM25SearchTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*BM25SearchTool) Name 

func (t *BM25SearchTool) Name() string

func (*BM25SearchTool) Parameters 

func (t *BM25SearchTool) Parameters() map[string]any

func (*BM25SearchTool) PromptMetadata 

func (t *BM25SearchTool) PromptMetadata() toolshared.PromptMetadata

type BrowserActTool 

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

func NewBrowserActTool 

func NewBrowserActTool(cfg *config.Config, source BrowserToolSource) *BrowserActTool

func (*BrowserActTool) ApprovalArguments 

func (tool *BrowserActTool) ApprovalArguments(ctx context.Context, args map[string]any) (map[string]any, error)

func (*BrowserActTool) Description 

func (*BrowserActTool) Description() string

func (*BrowserActTool) Execute 

func (tool *BrowserActTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*BrowserActTool) Name 

func (*BrowserActTool) Name() string

func (*BrowserActTool) Parameters 

func (tool *BrowserActTool) Parameters() map[string]any

func (*BrowserActTool) ToolEnabledForAgent 

func (tool *BrowserActTool) ToolEnabledForAgent(agentID string) bool

func (*BrowserActTool) ToolLoopSemantics 

func (*BrowserActTool) ToolLoopSemantics() loopguard.Semantics

type BrowserObserveTool 

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

func NewBrowserObserveTool 

func NewBrowserObserveTool(cfg *config.Config, source BrowserToolSource) *BrowserObserveTool

func (*BrowserObserveTool) Description 

func (*BrowserObserveTool) Description() string

func (*BrowserObserveTool) Execute 

func (tool *BrowserObserveTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*BrowserObserveTool) Name 

func (*BrowserObserveTool) Name() string

func (*BrowserObserveTool) Parameters 

func (*BrowserObserveTool) Parameters() map[string]any

func (*BrowserObserveTool) ToolEnabledForAgent 

func (tool *BrowserObserveTool) ToolEnabledForAgent(agentID string) bool

func (*BrowserObserveTool) ToolLoopSemantics 

func (*BrowserObserveTool) ToolLoopSemantics() loopguard.Semantics

type BrowserSessionTool 

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

func NewBrowserSessionTool 

func NewBrowserSessionTool(cfg *config.Config, source BrowserToolSource) *BrowserSessionTool

func (*BrowserSessionTool) Description 

func (*BrowserSessionTool) Description() string

func (*BrowserSessionTool) Execute 

func (tool *BrowserSessionTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*BrowserSessionTool) Name 

func (*BrowserSessionTool) Name() string

func (*BrowserSessionTool) Parameters 

func (*BrowserSessionTool) Parameters() map[string]any

func (*BrowserSessionTool) ToolEnabledForAgent 

func (tool *BrowserSessionTool) ToolEnabledForAgent(agentID string) bool

func (*BrowserSessionTool) ToolLoopSemantics 

func (*BrowserSessionTool) ToolLoopSemantics() loopguard.Semantics

type BrowserTargetDiagnostics 

type BrowserTargetDiagnostics struct {
	Profiles   map[string]browser.PassiveReadiness
	Actions    []browser.ActionKind
	Screenshot bool
	Upload     bool
	Download   bool
	HeadedView bool
	Handoff    bool
}

BrowserTargetDiagnostics is one gateway-owned readiness and capability snapshot. Implementations must compute every field while holding the same runtime generation so discovery cannot combine stale capability flags with unavailable readiness.

type BrowserTargetsTool 

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

func NewBrowserTargetsTool 

func NewBrowserTargetsTool(cfg *config.Config, source BrowserToolSource) *BrowserTargetsTool

func (*BrowserTargetsTool) Description 

func (*BrowserTargetsTool) Description() string

func (*BrowserTargetsTool) Execute 

func (tool *BrowserTargetsTool) Execute(ctx context.Context, _ map[string]any) *toolshared.ToolResult

func (*BrowserTargetsTool) Name 

func (*BrowserTargetsTool) Name() string

func (*BrowserTargetsTool) Parameters 

func (*BrowserTargetsTool) Parameters() map[string]any

func (*BrowserTargetsTool) ToolEnabledForAgent 

func (tool *BrowserTargetsTool) ToolEnabledForAgent(agentID string) bool

func (*BrowserTargetsTool) ToolLoopSemantics 

func (*BrowserTargetsTool) ToolLoopSemantics() loopguard.Semantics

type BrowserToolSource 

type BrowserToolSource interface {
	Available() bool
	ScreenshotAvailable() bool
	ArtifactTransferAvailable() bool
	DownloadAvailable() bool
	HandoffAvailable() bool
	ProfileAvailability(context.Context, string, string) (browser.ProfileAvailability, error)
	PassiveTargetDiagnostics(context.Context, string, []string) (BrowserTargetDiagnostics, error)
	Open(context.Context, browser.OpenRequest) (browser.Session, error)
	Status(context.Context, browser.Owner, string) (browser.Session, error)
	Close(context.Context, browser.Owner, string) (browser.Session, error)
	Handoff(context.Context, browser.Owner, string) (browser.Session, error)
	ReleaseHandoff(context.Context, browser.Owner, string) (browser.Session, error)
	Resume(context.Context, browser.Owner, string) (browser.Session, error)
	Observe(context.Context, browser.Owner, string, string) (browser.Observation, error)
	LookupScreenshot(context.Context, browser.Owner, string, string) (browser.ScreenshotArtifact, bool, error)
	CaptureScreenshot(context.Context, browser.ScreenshotRequest) (browser.ScreenshotArtifact, error)
	ClaimScreenshotDelivery(context.Context, browser.ScreenshotDeliveryRequest) error
	ClaimDownloadDelivery(context.Context, browser.DownloadDeliveryRequest) error
	PrepareAction(context.Context, browser.PrepareActionRequest) (browser.Preparation, error)
	ExecuteAction(context.Context, browser.Owner, string, *browser.ApprovalBinding) (browser.Invocation, error)
}

BrowserToolSource is the narrow gateway-owned boundary used by first-party browser tools. Implementations keep the runtime alive for the full method call so configuration reload cannot hand a tool a stale broker pointer.

type CreateGoalTool 

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

CreateGoalTool creates the one durable goal allowed for a routed conversation.

func NewCreateGoalTool 

func NewCreateGoalTool(manager *state.Manager) *CreateGoalTool

func (*CreateGoalTool) Description 

func (t *CreateGoalTool) Description() string

func (*CreateGoalTool) Execute 

func (t *CreateGoalTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*CreateGoalTool) Name 

func (t *CreateGoalTool) Name() string

func (*CreateGoalTool) Parameters 

func (t *CreateGoalTool) Parameters() map[string]any

type CronTool 

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

CronTool provides scheduling capabilities for the agent

func NewCronTool 

func NewCronTool(
	cronService *cron.CronService, executor JobExecutor, msgBus *bus.MessageBus, workspace string, restrict bool,
	execTimeout time.Duration, config *config.Config,
) (*CronTool, error)

NewCronTool creates a new CronTool execTimeout: 0 means no timeout, >0 sets the timeout duration

func (*CronTool) Description 

func (t *CronTool) Description() string

Description returns the tool description

func (*CronTool) Execute 

func (t *CronTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

Execute runs the tool with the given arguments

func (*CronTool) ExecuteJob 

func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string

ExecuteJob executes a cron job through the agent

func (*CronTool) Name 

func (t *CronTool) Name() string

Name returns the tool name

func (*CronTool) Parameters 

func (t *CronTool) Parameters() map[string]any

Parameters returns the tool parameters schema

func (*CronTool) SetTaskRegistry 

func (t *CronTool) SetTaskRegistry(registry *taskregistry.Registry)

type DelegateTool 

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

DelegateTool delegates a task to a specific named agent and waits for the result. Unlike spawn (async, fire-and-forget) or subagent (sync but generic), delegate targets a named agent and runs the task using that agent's own workspace, model, and tools.

func NewDelegateTool 

func NewDelegateTool() *DelegateTool

func (*DelegateTool) Description 

func (t *DelegateTool) Description() string

func (*DelegateTool) Execute 

func (t *DelegateTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*DelegateTool) Name 

func (t *DelegateTool) Name() string

func (*DelegateTool) Parameters 

func (t *DelegateTool) Parameters() map[string]any

func (*DelegateTool) SetAllowlistChecker 

func (t *DelegateTool) SetAllowlistChecker(check func(targetAgentID string) bool)

func (*DelegateTool) SetSelfAgentID 

func (t *DelegateTool) SetSelfAgentID(id string)

func (*DelegateTool) SetSpawner 

func (t *DelegateTool) SetSpawner(spawner SubTurnSpawner)

func (*DelegateTool) SetTaskRegistry 

func (t *DelegateTool) SetTaskRegistry(registry *taskregistry.Registry)

type ExecTool 

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

func NewExecTool 

func NewExecTool(workingDir string, restrict bool, allowPaths ...[]*regexp.Regexp) (*ExecTool, error)

func NewExecToolWithConfig 

func NewExecToolWithConfig(
	workingDir string,
	restrict bool,
	cfg *config.Config,
	allowPaths ...[]*regexp.Regexp,
) (*ExecTool, error)

func NewExecToolWithRuntimeConfig 

func NewExecToolWithRuntimeConfig(
	workingDir string,
	scratchDir string,
	restrict bool,
	cfg *config.Config,
	allowPaths ...[]*regexp.Regexp,
) (*ExecTool, error)

NewExecToolWithRuntimeConfig keeps MintClaw-owned scratch state outside the execution root used as the subprocess working directory.

func (*ExecTool) Close 

func (t *ExecTool) Close() error

Close stops and terminates sessions owned by a runtime-scoped exec tool.

func (*ExecTool) Description 

func (t *ExecTool) Description() string

func (*ExecTool) Execute 

func (t *ExecTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*ExecTool) Name 

func (t *ExecTool) Name() string

func (*ExecTool) Parameters 

func (t *ExecTool) Parameters() map[string]any

func (*ExecTool) SetAllowPatterns 

func (t *ExecTool) SetAllowPatterns(patterns []string) error

func (*ExecTool) SetRestrictToWorkspace 

func (t *ExecTool) SetRestrictToWorkspace(restrict bool)

func (*ExecTool) SetTimeout 

func (t *ExecTool) SetTimeout(timeout time.Duration)

type GetGoalTool 

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

GetGoalTool exposes the durable goal for the current routed conversation.

func NewGetGoalTool 

func NewGetGoalTool(manager *state.Manager) *GetGoalTool

func (*GetGoalTool) Description 

func (t *GetGoalTool) Description() string

func (*GetGoalTool) Execute 

func (t *GetGoalTool) Execute(ctx context.Context, _ map[string]any) *toolshared.ToolResult

func (*GetGoalTool) Name 

func (t *GetGoalTool) Name() string

func (*GetGoalTool) Parameters 

func (t *GetGoalTool) Parameters() map[string]any

type HiddenToolDoc 

type HiddenToolDoc struct {
	Name        string
	Description string
}

HiddenToolDoc is a lightweight representation of a hidden tool for search indexing.

type HiddenToolSnapshot 

type HiddenToolSnapshot struct {
	Docs    []HiddenToolDoc
	Version uint64
}

HiddenToolSnapshot holds a consistent snapshot of hidden tools and the registry version at which it was taken. Used by BM25SearchTool cache.

type ImageGenerateTool 

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

ImageGenerateTool generates images through a provider adapter and returns generated files through the MediaStore outbound media pipeline.

func NewImageGenerateTool 

func NewImageGenerateTool(
	workspace string,
	model string,
	store media.MediaStore,
	options ...ImageGenerateToolOption,
) *ImageGenerateTool

func (*ImageGenerateTool) Description 

func (t *ImageGenerateTool) Description() string

func (*ImageGenerateTool) Execute 

func (t *ImageGenerateTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*ImageGenerateTool) Name 

func (t *ImageGenerateTool) Name() string

func (*ImageGenerateTool) Parameters 

func (t *ImageGenerateTool) Parameters() map[string]any

func (*ImageGenerateTool) SetMediaStore 

func (t *ImageGenerateTool) SetMediaStore(store media.MediaStore)

type ImageGenerateToolOption 

type ImageGenerateToolOption func(*ImageGenerateTool)

func WithImageGenerationOutputDir 

func WithImageGenerationOutputDir(outputDir string) ImageGenerateToolOption

func WithImageGenerationProvider 

func WithImageGenerationProvider(provider providers.ImageGenerationCapable) ImageGenerateToolOption

func WithImageGenerationProviderResolver 

func WithImageGenerationProviderResolver(resolver ImageGenerationProviderResolver) ImageGenerateToolOption

type ImageGenerationProviderResolver 

type ImageGenerationProviderResolver func(model string) (providers.ImageGenerationCapable, string, error)

type JobExecutor 

type JobExecutor interface {
	ProcessDirectWithChannel(ctx context.Context, content, sessionKey, channel, chatID string) (string, error)
	// PublishResponseIfNeeded sends response to the outbound bus only when the
	// agent did not already deliver content through the message tool in this round.
	PublishResponseIfNeeded(
		ctx context.Context,
		workspace, agentID, channel, chatID, sessionKey, response string,
	)
}

JobExecutor is the interface for executing cron jobs through the agent

type MemoryMutationPayload 

type MemoryMutationPayload struct {
	Operation        string `json:"operation"`
	Outcome          string `json:"outcome"`
	Target           string `json:"target"`
	ContentHash      string `json:"content_hash,omitempty"`
	ContentBytes     int    `json:"content_bytes,omitempty"`
	ReplacementHash  string `json:"replacement_hash,omitempty"`
	ReplacementBytes int    `json:"replacement_bytes,omitempty"`
	IdempotencyHash  string `json:"idempotency_hash,omitempty"`
	MatchCount       int    `json:"match_count,omitempty"`
	ErrorCode        string `json:"error_code,omitempty"`
}

type MemoryTool 

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

func NewMemoryTool 

func NewMemoryTool(workspace string, invalidate func(), eventBus runtimeevents.Bus) *MemoryTool

func (*MemoryTool) Description 

func (t *MemoryTool) Description() string

func (*MemoryTool) Execute 

func (t *MemoryTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*MemoryTool) Name 

func (t *MemoryTool) Name() string

func (*MemoryTool) Parameters 

func (t *MemoryTool) Parameters() map[string]any

func (*MemoryTool) ToolLoopSemantics 

func (t *MemoryTool) ToolLoopSemantics() loopguard.Semantics

type NodeCancelTool 

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

func NewNodeCancelTool 

func NewNodeCancelTool(cfg *config.Config, source NodeInvocationSource) *NodeCancelTool

func (*NodeCancelTool) Description 

func (*NodeCancelTool) Description() string

func (*NodeCancelTool) Execute 

func (tool *NodeCancelTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*NodeCancelTool) Name 

func (*NodeCancelTool) Name() string

func (*NodeCancelTool) Parameters 

func (*NodeCancelTool) Parameters() map[string]any

func (*NodeCancelTool) SetEventPublisher 

func (tool *NodeCancelTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for cancellation audit events.

func (*NodeCancelTool) ToolLoopSemantics 

func (*NodeCancelTool) ToolLoopSemantics() loopguard.Semantics

type NodeDiscoveryRecord 

type NodeDiscoveryRecord struct {
	Snapshot     nodes.Snapshot
	Registration *nodes.Registration
	Connected    bool
}

type NodeDiscoverySource 

type NodeDiscoverySource interface {
	Lookup(string) (NodeDiscoveryRecord, bool, error)
}

type NodeDiscoveryTool 

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

func NewNodeDiscoveryTool 

func NewNodeDiscoveryTool(cfg *config.Config, source NodeDiscoverySource) *NodeDiscoveryTool

func (*NodeDiscoveryTool) Description 

func (*NodeDiscoveryTool) Description() string

func (*NodeDiscoveryTool) Execute 

func (tool *NodeDiscoveryTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*NodeDiscoveryTool) Name 

func (*NodeDiscoveryTool) Name() string

func (*NodeDiscoveryTool) Parameters 

func (*NodeDiscoveryTool) Parameters() map[string]any

func (*NodeDiscoveryTool) ToolLoopSemantics 

func (*NodeDiscoveryTool) ToolLoopSemantics() loopguard.Semantics

type NodeDownloadTool 

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

func NewNodeDownloadTool 

func NewNodeDownloadTool(cfg *config.Config, source NodeFileTransferSource) *NodeDownloadTool

func (*NodeDownloadTool) ApprovalArguments 

func (tool *NodeDownloadTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*NodeDownloadTool) Description 

func (*NodeDownloadTool) Description() string

func (*NodeDownloadTool) Execute 

func (tool *NodeDownloadTool) Execute(
	ctx context.Context,
	args map[string]any,
) *toolshared.ToolResult

func (*NodeDownloadTool) Name 

func (*NodeDownloadTool) Name() string

func (*NodeDownloadTool) Parameters 

func (*NodeDownloadTool) Parameters() map[string]any

func (*NodeDownloadTool) SetEventPublisher 

func (tool *NodeDownloadTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for file-transfer observations.

func (*NodeDownloadTool) SetMediaStore 

func (tool *NodeDownloadTool) SetMediaStore(store media.MediaStore)

func (*NodeDownloadTool) ToolEnabledForAgent 

func (tool *NodeDownloadTool) ToolEnabledForAgent(agentID string) bool

func (*NodeDownloadTool) ToolLoopSemantics 

func (*NodeDownloadTool) ToolLoopSemantics() loopguard.Semantics

type NodeFileInfoTool 

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

func NewNodeFileInfoTool 

func NewNodeFileInfoTool(cfg *config.Config, source NodeFileTransferSource) *NodeFileInfoTool

func (*NodeFileInfoTool) ApprovalArguments 

func (tool *NodeFileInfoTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*NodeFileInfoTool) Description 

func (*NodeFileInfoTool) Description() string

func (*NodeFileInfoTool) Execute 

func (tool *NodeFileInfoTool) Execute(
	ctx context.Context,
	args map[string]any,
) *toolshared.ToolResult

func (*NodeFileInfoTool) Name 

func (*NodeFileInfoTool) Name() string

func (*NodeFileInfoTool) Parameters 

func (*NodeFileInfoTool) Parameters() map[string]any

func (*NodeFileInfoTool) SetEventPublisher 

func (tool *NodeFileInfoTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for file-transfer observations.

func (*NodeFileInfoTool) ToolEnabledForAgent 

func (tool *NodeFileInfoTool) ToolEnabledForAgent(agentID string) bool

func (*NodeFileInfoTool) ToolLoopSemantics 

func (*NodeFileInfoTool) ToolLoopSemantics() loopguard.Semantics

type NodeFileTransferBinding 

type NodeFileTransferBinding struct {
	TransferID     string
	Direction      protocol.TransferDirection
	ProfileAlias   string
	PolicyRevision string
	Path           string
	Publication    string
	TotalSize      uint64
	SHA256         [sha256.Size]byte
	ExpiresAt      int64
	Filename       string
	ContentType    string
	SourceKind     string
	JobProfile     string
	JobID          string
	JobArtifactRef string
	AgentID        string
	SessionID      string
	ActorID        string
}

type NodeFileTransferResult 

type NodeFileTransferResult struct {
	TransferID     string `json:"transfer_id"`
	State          string `json:"state"`
	Path           string `json:"path,omitempty"`
	Type           string `json:"type,omitempty"`
	Size           uint64 `json:"size,omitempty"`
	Mode           uint32 `json:"mode,omitempty"`
	ModifiedAt     int64  `json:"modified_at,omitempty"`
	SHA256         string `json:"sha256,omitempty"`
	Sequence       uint64 `json:"sequence,omitempty"`
	Transferred    uint64 `json:"transferred,omitempty"`
	Code           string `json:"code,omitempty"`
	ArtifactRef    string `json:"artifact_ref,omitempty"`
	Filename       string `json:"filename,omitempty"`
	ContentType    string `json:"content_type,omitempty"`
	PolicyRevision string `json:"policy_revision,omitempty"`
	DeliveryState  string `json:"delivery_state,omitempty"`
	RecoveryAction string `json:"recovery_action,omitempty"`
}

type NodeFileTransferSource 

type NodeFileTransferSource interface {
	NodeInvocationSource
	SnapshotUploadArtifact(
		context.Context,
		nodes.TransferArtifactOwner,
		string,
		string,
		string,
		int64,
		int64,
		string,
		media.MediaStore,
		media.MediaOwner,
	) (nodes.TransferArtifactRecord, error)
	InspectFile(
		context.Context,
		nodes.ID,
		NodeFileTransferBinding,
	) (NodeFileTransferResult, error)
	DispatchFileTransfer(
		context.Context,
		nodes.GatewayInvocationOwner,
		nodes.GatewayInvocationRecord,
	) (NodeFileTransferResult, bool, error)
	QueryFileTransfer(
		context.Context,
		nodes.GatewayInvocationPrincipal,
		nodes.GatewayInvocationRecord,
	) (NodeFileTransferResult, error)
	CancelFileTransfer(
		context.Context,
		nodes.GatewayInvocationPrincipal,
		nodes.GatewayInvocationRecord,
	) (NodeFileTransferResult, bool, error)
	HandoffDownloadedArtifact(
		context.Context,
		nodes.TransferArtifactOwner,
		string,
		media.MediaStore,
		media.MediaOwner,
	) (string, bool, error)
}

type NodeInvocationEventPayload 

type NodeInvocationEventPayload struct {
	Observation       string                       `json:"observation"`
	InvocationID      string                       `json:"invocation_id"`
	Target            string                       `json:"target"`
	Workspace         string                       `json:"workspace,omitempty"`
	WorkspaceRevision string                       `json:"workspace_revision,omitempty"`
	Command           string                       `json:"command"`
	Risk              nodes.Risk                   `json:"risk"`
	GatewayState      nodes.GatewayInvocationState `json:"gateway_state"`
	State             string                       `json:"state"`
	ErrorCode         string                       `json:"error_code,omitempty"`
	Service           string                       `json:"service,omitempty"`
	Action            nodes.ServiceAction          `json:"action,omitempty"`
	LogEntries        int                          `json:"log_entries,omitempty"`
	JobProfile        string                       `json:"job_profile,omitempty"`
	JobID             string                       `json:"job_id,omitempty"`
	JobState          string                       `json:"job_state,omitempty"`
	JobLogStream      string                       `json:"job_log_stream,omitempty"`
	JobLogBytes       int                          `json:"job_log_bytes,omitempty"`
	JobLogCursor      int64                        `json:"job_log_cursor,omitempty"`
	ArtifactCount     int                          `json:"artifact_count,omitempty"`
	CancelDisposition string                       `json:"cancel_disposition,omitempty"`
}

NodeInvocationEventPayload is a redacted, passive invocation snapshot published to the runtime event bus. Concurrent observations are not a transaction log and may arrive out of order. Command input, output, node identity, and plan authority are intentionally excluded.

type NodeInvocationSource 

type NodeInvocationSource interface {
	NodeDiscoverySource
	PrepareInvocation(
		nodeRef string,
		target string,
		toolCallID string,
		principal nodes.GatewayInvocationPrincipal,
		plan nodes.ExecutionPlan,
		descriptor nodes.CommandDescriptor,
		allowCreate bool,
		validate func(NodeDiscoveryRecord) error,
	) (nodes.GatewayInvocationRecord, bool, error)
	LookupInvocationByToolCall(
		principal nodes.GatewayInvocationPrincipal,
		toolCallID string,
	) (nodes.GatewayInvocationRecord, bool, error)
	LookupInvocation(
		principal nodes.GatewayInvocationPrincipal,
		invocationID string,
	) (nodes.GatewayInvocationRecord, bool, error)
	DispatchInvocation(
		ctx context.Context,
		owner nodes.GatewayInvocationOwner,
		invocationID string,
		expectedPlanHash string,
	) (result json.RawMessage, dispatched bool, err error)
	QueryInvocation(
		ctx context.Context,
		principal nodes.GatewayInvocationPrincipal,
		target string,
		nodeID nodes.ID,
		invocationID string,
	) (nodes.InvocationRecord, error)
	CancelInvocation(
		ctx context.Context,
		principal nodes.GatewayInvocationPrincipal,
		target string,
		nodeID nodes.ID,
		invocationID string,
	) (record nodes.InvocationRecord, requested bool, err error)
}

type NodeInvokeTool 

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

func NewNodeInvokeTool 

func NewNodeInvokeTool(cfg *config.Config, source NodeInvocationSource) *NodeInvokeTool

func (*NodeInvokeTool) ApprovalArguments 

func (tool *NodeInvokeTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*NodeInvokeTool) Description 

func (*NodeInvokeTool) Description() string

func (*NodeInvokeTool) Execute 

func (tool *NodeInvokeTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*NodeInvokeTool) Name 

func (*NodeInvokeTool) Name() string

func (*NodeInvokeTool) Parameters 

func (*NodeInvokeTool) Parameters() map[string]any

func (*NodeInvokeTool) SetEventPublisher 

func (tool *NodeInvokeTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for node invocation audit events.

func (*NodeInvokeTool) ToolLoopSemantics 

func (*NodeInvokeTool) ToolLoopSemantics() loopguard.Semantics

type NodeStatusTool 

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

func NewNodeStatusTool 

func NewNodeStatusTool(cfg *config.Config, source NodeInvocationSource) *NodeStatusTool

func (*NodeStatusTool) Description 

func (*NodeStatusTool) Description() string

func (*NodeStatusTool) Execute 

func (tool *NodeStatusTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*NodeStatusTool) Name 

func (*NodeStatusTool) Name() string

func (*NodeStatusTool) Parameters 

func (*NodeStatusTool) Parameters() map[string]any

func (*NodeStatusTool) SetEventPublisher 

func (tool *NodeStatusTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for node status audit events.

func (*NodeStatusTool) ToolLoopSemantics 

func (*NodeStatusTool) ToolLoopSemantics() loopguard.Semantics

type NodeTerminalEventPayload 

type NodeTerminalEventPayload struct {
	Observation string `json:"observation"`
	TerminalID  string `json:"terminal_id,omitempty"`
	Target      string `json:"target"`
	Profile     string `json:"profile"`
	State       string `json:"state"`
	ErrorCode   string `json:"error_code,omitempty"`
}

NodeTerminalEventPayload is a passive redacted lifecycle observation. It contains no terminal bytes, owner identity, paths, environment, broker details, credentials, or authority digests.

type NodeTerminalOperator 

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

NodeTerminalOperator opens terminals for an explicitly authenticated operator while sharing the same target and command authority checks as the model-facing tool.

func NewNodeTerminalOperator 

func NewNodeTerminalOperator(cfg *config.Config, source NodeTerminalSource) *NodeTerminalOperator

NewNodeTerminalOperator creates the deterministic operator-side terminal opener using the same configured target authority as the model-facing tool.

func (*NodeTerminalOperator) Open 

func (operator *NodeTerminalOperator) Open(
	ctx context.Context,
	request NodeTerminalOperatorOpenRequest,
) (NodeTerminalOperatorOpenResult, error)

Open treats the authenticated operator's explicit request as the session-start approval. It still revalidates all durable node and command authority immediately before dispatch.

type NodeTerminalOperatorOpenRequest 

type NodeTerminalOperatorOpenRequest struct {
	AgentID           string
	OperatorSessionID string
	RequestID         string
	Owner             nodes.TerminalOwner
	Target            string
	Profile           string
	WorkingScope      string
	Columns           int
	Rows              int
}

NodeTerminalOperatorOpenRequest contains authenticated, server-derived operator identity plus the bounded terminal authority requested by the CLI.

type NodeTerminalOperatorOpenResult 

type NodeTerminalOperatorOpenResult struct {
	TerminalID   string `json:"terminal_id"`
	State        string `json:"state"`
	AttachBefore int64  `json:"attach_before"`
}

NodeTerminalOperatorOpenResult is the safe handoff needed to attach the authenticated operator WebSocket.

type NodeTerminalSource 

type NodeTerminalSource interface {
	NodeDiscoverySource
	PrepareTerminal(
		nodeID nodes.ID,
		nodeRef string,
		openID string,
		idempotencyKey string,
		owner nodes.TerminalOwner,
		workingScope string,
		columns int,
		rows int,
		allowCreate bool,
	) (nodes.GatewayTerminalRecord, bool, error)
	OpenTerminal(
		ctx context.Context,
		owner nodes.TerminalOwner,
		openID string,
		expectedPlanHash string,
	) (nodes.TerminalMetadata, bool, error)
	TerminalStatus(
		ctx context.Context,
		owner nodes.TerminalOwner,
		terminalID string,
	) (nodes.TerminalMetadata, error)
	SignalTerminal(
		ctx context.Context,
		owner nodes.TerminalOwner,
		terminalID string,
		signal string,
	) (nodes.TerminalMetadata, error)
	CloseTerminal(
		ctx context.Context,
		owner nodes.TerminalOwner,
		terminalID string,
	) (nodes.TerminalMetadata, error)
	BindTerminalOperator(
		owner nodes.TerminalOwner,
		terminalID string,
		operatorSessionID string,
	) error
}

type NodeTerminalTool 

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

func NewNodeTerminalTool 

func NewNodeTerminalTool(cfg *config.Config, source NodeTerminalSource) *NodeTerminalTool

func (*NodeTerminalTool) ApprovalArguments 

func (tool *NodeTerminalTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*NodeTerminalTool) Description 

func (*NodeTerminalTool) Description() string

func (*NodeTerminalTool) Execute 

func (tool *NodeTerminalTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*NodeTerminalTool) Name 

func (*NodeTerminalTool) Name() string

func (*NodeTerminalTool) Parameters 

func (*NodeTerminalTool) Parameters() map[string]any

func (*NodeTerminalTool) SetEventPublisher 

func (tool *NodeTerminalTool) SetEventPublisher(eventBus runtimeevents.Bus)

func (*NodeTerminalTool) ToolLoopSemantics 

func (*NodeTerminalTool) ToolLoopSemantics() loopguard.Semantics

type NodeUploadTool 

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

func NewNodeUploadTool 

func NewNodeUploadTool(cfg *config.Config, source NodeFileTransferSource) *NodeUploadTool

func (*NodeUploadTool) ApprovalArguments 

func (tool *NodeUploadTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*NodeUploadTool) Description 

func (*NodeUploadTool) Description() string

func (*NodeUploadTool) Execute 

func (tool *NodeUploadTool) Execute(
	ctx context.Context,
	args map[string]any,
) *toolshared.ToolResult

func (*NodeUploadTool) Name 

func (*NodeUploadTool) Name() string

func (*NodeUploadTool) Parameters 

func (*NodeUploadTool) Parameters() map[string]any

func (*NodeUploadTool) SetEventPublisher 

func (tool *NodeUploadTool) SetEventPublisher(eventBus runtimeevents.Bus)

SetEventPublisher injects the runtime event bus used for file-transfer observations.

func (*NodeUploadTool) SetMediaStore 

func (tool *NodeUploadTool) SetMediaStore(store media.MediaStore)

func (*NodeUploadTool) ToolEnabledForAgent 

func (tool *NodeUploadTool) ToolEnabledForAgent(agentID string) bool

func (*NodeUploadTool) ToolLoopSemantics 

func (*NodeUploadTool) ToolLoopSemantics() loopguard.Semantics

type ProcessSession 

type ProcessSession struct {
	ID         string
	PID        int
	Command    string
	PTY        bool
	Background bool
	StartTime  int64
	ExitCode   int
	Status     string
	// contains filtered or unexported fields
}

func (*ProcessSession) GetExitCode 

func (s *ProcessSession) GetExitCode() int

func (*ProcessSession) GetPtyKeyMode 

func (s *ProcessSession) GetPtyKeyMode() PtyKeyMode

func (*ProcessSession) GetStatus 

func (s *ProcessSession) GetStatus() string

func (*ProcessSession) IsDone 

func (s *ProcessSession) IsDone() bool

func (*ProcessSession) Kill 

func (s *ProcessSession) Kill() error

func (*ProcessSession) Read 

func (s *ProcessSession) Read() string

func (*ProcessSession) SetExitCode 

func (s *ProcessSession) SetExitCode(code int)

func (*ProcessSession) SetPtyKeyMode 

func (s *ProcessSession) SetPtyKeyMode(mode PtyKeyMode)

func (*ProcessSession) SetStatus 

func (s *ProcessSession) SetStatus(status string)

func (*ProcessSession) ToSessionInfo 

func (s *ProcessSession) ToSessionInfo() toolshared.SessionInfo

func (*ProcessSession) Write 

func (s *ProcessSession) Write(data string) error

type PtyKeyMode 

type PtyKeyMode uint8

PtyKeyMode represents arrow key encoding mode for PTY sessions. Programs send smkx/rmkx sequences to switch between CSI and SS3 modes. 

const (
	PtyKeyModeCSI PtyKeyMode = iota // triggered by rmkx (\x1b[?1l)
	PtyKeyModeSS3                   // triggered by smkx (\x1b[?1h)
)
const PtyKeyModeNotFound PtyKeyMode = 255

type RegexSearchTool 

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

func NewRegexSearchTool 

func NewRegexSearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *RegexSearchTool

func (*RegexSearchTool) Description 

func (t *RegexSearchTool) Description() string

func (*RegexSearchTool) Execute 

func (t *RegexSearchTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*RegexSearchTool) Name 

func (t *RegexSearchTool) Name() string

func (*RegexSearchTool) Parameters 

func (t *RegexSearchTool) Parameters() map[string]any

func (*RegexSearchTool) PromptMetadata 

func (t *RegexSearchTool) PromptMetadata() toolshared.PromptMetadata

type RemoteWorkspaceNodeRouter 

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

RemoteWorkspaceNodeRouter maps compatible local file-tool shapes onto the hidden typed workspace commands. Generic nodes_invoke cannot dispatch those commands, so the configured workspace remains the only gateway authority.

func NewRemoteWorkspaceNodeRouter 

func NewRemoteWorkspaceNodeRouter(
	cfg *config.Config,
	source NodeInvocationSource,
	agentID string,
	toolName string,
) (*RemoteWorkspaceNodeRouter, error)

func (*RemoteWorkspaceNodeRouter) ApprovalArgumentsRemoteWorkspace 

func (router *RemoteWorkspaceNodeRouter) ApprovalArgumentsRemoteWorkspace(
	ctx context.Context,
	toolName string,
	workspaceAlias string,
	toolArgs map[string]any,
) (map[string]any, error)

func (*RemoteWorkspaceNodeRouter) ExecuteRemoteWorkspace 

func (router *RemoteWorkspaceNodeRouter) ExecuteRemoteWorkspace(
	ctx context.Context,
	toolName string,
	workspaceAlias string,
	toolArgs map[string]any,
) *toolshared.ToolResult

func (*RemoteWorkspaceNodeRouter) SetEventPublisher 

func (router *RemoteWorkspaceNodeRouter) SetEventPublisher(eventBus runtimeevents.Bus)

func (*RemoteWorkspaceNodeRouter) WorkspaceAliases 

func (router *RemoteWorkspaceNodeRouter) WorkspaceAliases() []string

type RemoteWorkspaceSource 

type RemoteWorkspaceSource interface {
	WorkspaceAliases() []string
	ApprovalArgumentsRemoteWorkspace(
		context.Context,
		string,
		string,
		map[string]any,
	) (map[string]any, error)
	ExecuteRemoteWorkspace(
		context.Context,
		string,
		string,
		map[string]any,
	) *toolshared.ToolResult
}

RemoteWorkspaceSource executes one compatible tool against an explicit operator-configured remote workspace. It is deliberately narrower than a generic tool proxy.

type RemoteWorkspaceTool 

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

RemoteWorkspaceTool preserves one agent-specific local tool and routes only calls that explicitly carry a configured workspace alias.

func NewRemoteWorkspaceTool 

func NewRemoteWorkspaceTool(
	local toolshared.Tool,
	remote RemoteWorkspaceSource,
) (*RemoteWorkspaceTool, error)

func (*RemoteWorkspaceTool) ApprovalArguments 

func (tool *RemoteWorkspaceTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*RemoteWorkspaceTool) Description 

func (tool *RemoteWorkspaceTool) Description() string

func (*RemoteWorkspaceTool) Execute 

func (tool *RemoteWorkspaceTool) Execute(
	ctx context.Context,
	args map[string]any,
) *toolshared.ToolResult

func (*RemoteWorkspaceTool) Name 

func (tool *RemoteWorkspaceTool) Name() string

func (*RemoteWorkspaceTool) Parameters 

func (tool *RemoteWorkspaceTool) Parameters() map[string]any

func (*RemoteWorkspaceTool) ToolLoopSemantics 

func (tool *RemoteWorkspaceTool) ToolLoopSemantics() loopguard.Semantics

type RequestUserInputTool 

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

func NewRequestUserInputTool 

func NewRequestUserInputTool(options RequestUserInputToolOptions) (*RequestUserInputTool, error)

func (*RequestUserInputTool) Description 

func (t *RequestUserInputTool) Description() string

func (*RequestUserInputTool) Execute 

func (t *RequestUserInputTool) Execute(_ context.Context, args map[string]any) *toolshared.ToolResult

func (*RequestUserInputTool) Name 

func (t *RequestUserInputTool) Name() string

func (*RequestUserInputTool) Parameters 

func (t *RequestUserInputTool) Parameters() map[string]any

func (*RequestUserInputTool) ToolLoopSemantics 

func (*RequestUserInputTool) ToolLoopSemantics() loopguard.Semantics

type RequestUserInputToolOptions 

type RequestUserInputToolOptions struct {
	DefaultTimeout time.Duration
	MaxTimeout     time.Duration
}

type SessionManager 

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

func NewSessionManager 

func NewSessionManager() *SessionManager

func (*SessionManager) Add 

func (sm *SessionManager) Add(session *ProcessSession) bool

func (*SessionManager) Close 

func (sm *SessionManager) Close() error

Close rejects new sessions, terminates admitted processes, and stops cleanup.

func (*SessionManager) Get 

func (sm *SessionManager) Get(sessionID string) (*ProcessSession, error)

func (*SessionManager) List 

func (sm *SessionManager) List() []toolshared.SessionInfo

func (*SessionManager) Remove 

func (sm *SessionManager) Remove(sessionID string)

func (*SessionManager) Stop 

func (sm *SessionManager) Stop()

Stop shuts down the background cleanup goroutine. Safe to call multiple times from concurrent goroutines. After Stop returns, the SessionManager is still usable — only the cleanup goroutine is terminated.

type SpawnStatusTool 

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

SpawnStatusTool reports the status of subagents that were spawned via the spawn tool. It can query a specific task by ID, or list every known task with a summary count broken-down by status.

func NewSpawnStatusTool 

func NewSpawnStatusTool(manager *SubagentManager) *SpawnStatusTool

NewSpawnStatusTool creates a SpawnStatusTool backed by the given manager.

func (*SpawnStatusTool) Description 

func (t *SpawnStatusTool) Description() string

func (*SpawnStatusTool) Execute 

func (t *SpawnStatusTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*SpawnStatusTool) Name 

func (t *SpawnStatusTool) Name() string

func (*SpawnStatusTool) Parameters 

func (t *SpawnStatusTool) Parameters() map[string]any

type SpawnSubTurnFunc 

type SpawnSubTurnFunc func(
	ctx context.Context,
	taskID string,
	task, label, agentID string,
	tools *ToolRegistry,
	maxTokens int,
	temperature float64,
	hasMaxTokens, hasTemperature bool,
) (*toolshared.ToolResult, error)

type SpawnTool 

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

func NewSpawnTool 

func NewSpawnTool(manager *SubagentManager) *SpawnTool

func (*SpawnTool) Description 

func (t *SpawnTool) Description() string

func (*SpawnTool) Execute 

func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*SpawnTool) ExecuteAsync 

func (t *SpawnTool) ExecuteAsync(
	ctx context.Context,
	args map[string]any,
	cb toolshared.AsyncCallback,
) *toolshared.ToolResult

ExecuteAsync implements AsyncExecutor. The callback is passed through to the subagent manager as a call parameter — never stored on the SpawnTool instance.

func (*SpawnTool) Name 

func (t *SpawnTool) Name() string

func (*SpawnTool) Parameters 

func (t *SpawnTool) Parameters() map[string]any

func (*SpawnTool) SetAllowlistChecker 

func (t *SpawnTool) SetAllowlistChecker(check func(targetAgentID string) bool)

func (*SpawnTool) SetSpawner 

func (t *SpawnTool) SetSpawner(spawner SubTurnSpawner)

SetSpawner sets the SubTurnSpawner for direct sub-turn execution.

type SubTurnConfig 

type SubTurnConfig struct {
	Model              string
	Tools              []toolshared.Tool
	SystemPrompt       string
	MaxTokens          int
	Temperature        float64
	Async              bool          // true for async (spawn), false for sync (subagent)
	Critical           bool          // continue running after parent finishes gracefully
	Timeout            time.Duration // 0 = use default (5 minutes)
	MaxContextRunes    int           // 0 = auto, -1 = no limit, >0 = explicit limit
	ActualSystemPrompt string
	InitialMessages    []providers.Message
	InitialTokenBudget *atomic.Int64 // Shared token budget for team members; nil if no budget
	TargetAgentID      string        // If set, run as this agent (its workspace, model, tools)
	DeliveryMode       toolshared.AsyncDeliveryMode
	TaskID             string // Durable task owning this child turn, when one exists.
}

SubTurnConfig holds configuration for spawning a sub-turn.

type SubTurnSpawner 

type SubTurnSpawner interface {
	SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*toolshared.ToolResult, error)
}

SubTurnSpawner is an interface for spawning sub-turns. This avoids circular dependency between tools and agent packages.

type SubagentManager 

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

func NewSubagentManagerWithRegistry 

func NewSubagentManagerWithRegistry(
	provider providers.LLMProvider,
	defaultModel, workspace string,
	registry *taskregistry.Registry,
) *SubagentManager

NewSubagentManagerWithRegistry requires the canonical task registry shared by every manager that owns the same workspace.

func (*SubagentManager) GetTask 

func (sm *SubagentManager) GetTask(taskID string) (*SubagentTask, bool)

func (*SubagentManager) GetTaskCopy 

func (sm *SubagentManager) GetTaskCopy(taskID string) (SubagentTask, bool)

GetTaskCopy returns a copy of the task with the given ID, taken under the read lock, so the caller receives a consistent snapshot with no data race.

func (*SubagentManager) ListTaskCopies 

func (sm *SubagentManager) ListTaskCopies() []SubagentTask

ListTaskCopies returns value copies of all tasks, taken under the read lock, so callers receive consistent snapshots with no data race.

func (*SubagentManager) ListTasks 

func (sm *SubagentManager) ListTasks() []*SubagentTask

func (*SubagentManager) RegisterTool 

func (sm *SubagentManager) RegisterTool(tool toolshared.Tool)

RegisterTool registers a tool for subagent execution.

func (*SubagentManager) SetLLMOptions 

func (sm *SubagentManager) SetLLMOptions(maxTokens int, temperature float64)

SetLLMOptions sets max tokens and temperature for subagent LLM calls.

func (*SubagentManager) SetLoopDetection 

func (sm *SubagentManager) SetLoopDetection(config loopguard.Config)

func (*SubagentManager) SetMediaResolver 

func (sm *SubagentManager) SetMediaResolver(
	resolver func([]providers.Message) []providers.Message,
)

SetMediaResolver injects a message preprocessor that resolves media:// refs into LLM-ready content before each tool-loop iteration. This is only used by the legacy RunToolLoop fallback path.

func (*SubagentManager) SetSpawner 

func (sm *SubagentManager) SetSpawner(spawner SpawnSubTurnFunc)

func (*SubagentManager) SetTools 

func (sm *SubagentManager) SetTools(tools *ToolRegistry)

SetTools sets the tool registry for subagent execution. If not set, subagent will have access to the provided tools.

func (*SubagentManager) Spawn 

func (sm *SubagentManager) Spawn(
	ctx context.Context,
	task, label, agentID, originChannel, originChatID string,
	deliveryMode toolshared.AsyncDeliveryMode,
	callback toolshared.AsyncCallback,
) (string, error)

type SubagentTask 

type SubagentTask struct {
	ID            string
	Task          string
	Label         string
	AgentID       string
	OriginChannel string
	OriginChatID  string
	DeliveryMode  toolshared.AsyncDeliveryMode
	Status        string
	Result        string
	Created       int64
}

type SubagentTool 

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

SubagentTool executes a subagent task synchronously and returns the result. It directly calls SubTurnSpawner with Async=false for synchronous execution.

func NewSubagentTool 

func NewSubagentTool(manager *SubagentManager) *SubagentTool

func (*SubagentTool) Description 

func (t *SubagentTool) Description() string

func (*SubagentTool) Execute 

func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*SubagentTool) Name 

func (t *SubagentTool) Name() string

func (*SubagentTool) Parameters 

func (t *SubagentTool) Parameters() map[string]any

func (*SubagentTool) SetSpawner 

func (t *SubagentTool) SetSpawner(spawner SubTurnSpawner)

SetSpawner sets the SubTurnSpawner for direct sub-turn execution.

type TaskStatusTool 

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

TaskStatusTool reports durable runtime task/run records across spawn, delegate, cron, and future background runtimes.

func NewTaskStatusTool 

func NewTaskStatusTool(registry *taskregistry.Registry) *TaskStatusTool

func (*TaskStatusTool) Description 

func (t *TaskStatusTool) Description() string

func (*TaskStatusTool) Execute 

func (t *TaskStatusTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*TaskStatusTool) Name 

func (t *TaskStatusTool) Name() string

func (*TaskStatusTool) Parameters 

func (t *TaskStatusTool) Parameters() map[string]any

type ToolEntry 

type ToolEntry struct {
	Tool   toolshared.Tool
	IsCore bool
	TTL    int
}

type ToolLoopConfig 

type ToolLoopConfig struct {
	Provider      providers.LLMProvider
	Model         string
	Tools         *ToolRegistry
	MaxIterations int
	LLMOptions    map[string]any
	LoopDetection loopguard.Config

	// MediaResolver resolves media:// refs in messages before each LLM call.
	// This is optional and is mainly used by subagent legacy fallback execution
	// so subagents can reuse the same multimodal media handling as the main loop.
	MediaResolver func(messages []providers.Message) []providers.Message
}

ToolLoopConfig configures the tool execution loop.

type ToolLoopResult 

type ToolLoopResult struct {
	Content    string
	Iterations int
}

ToolLoopResult contains the result of running the tool loop.

func RunToolLoop 

func RunToolLoop(
	ctx context.Context,
	config ToolLoopConfig,
	messages []providers.Message,
	channel, chatID string,
) (*ToolLoopResult, error)

RunToolLoop executes the LLM + tool call iteration loop. This is the core agent logic that can be reused by both main agent and subagents.

type ToolRegistry 

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

func NewToolRegistry 

func NewToolRegistry() *ToolRegistry

func (*ToolRegistry) ApprovalArguments 

func (r *ToolRegistry) ApprovalArguments(
	ctx context.Context,
	name string,
	args map[string]any,
) (map[string]any, error)

ApprovalArguments returns the trusted arguments that durable human approval must bind for this call. Ordinary tools retain the existing model-argument binding. The returned map is used only for hashing and is never sent to the model or substituted for execution arguments.

func (*ToolRegistry) Clone 

func (r *ToolRegistry) Clone() *ToolRegistry

Clone creates an independent copy of the registry containing the same tool entries (shallow copy of each ToolEntry). This is used to give subagents a snapshot of the parent agent's tools without sharing the same registry — tools registered on the parent after cloning (e.g. spawn, spawn_status, task_status) will NOT be visible to the clone, preventing recursive subagent spawning. The version counter is reset to 0 in the clone as it's a new independent registry.

func (*ToolRegistry) Count 

func (r *ToolRegistry) Count() int

Count returns the number of registered tools.

func (*ToolRegistry) Execute 

func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string]any) *toolshared.ToolResult

func (*ToolRegistry) ExecuteTrustedWithContext 

func (r *ToolRegistry) ExecuteTrustedWithContext(
	ctx context.Context,
	binding *TrustedToolExecution,
	args map[string]any,
	channel, chatID string,
	asyncCallback toolshared.AsyncCallback,
) *toolshared.ToolResult

ExecuteTrustedWithContext executes the exact first-party tool instance bound during target-scoped approval. Registry replacement after validation cannot redirect execution to a different tool.

func (*ToolRegistry) ExecuteWithContext 

func (r *ToolRegistry) ExecuteWithContext(
	ctx context.Context,
	name string,
	args map[string]any,
	channel, chatID string,
	asyncCallback toolshared.AsyncCallback,
) *toolshared.ToolResult

ExecuteWithContext executes a tool with channel/chatID context and optional async callback. If the tool implements AsyncExecutor and a non-nil callback is provided, ExecuteAsync is called instead of Execute — the callback is a parameter, never stored as mutable state on the tool.

func (*ToolRegistry) Get 

func (r *ToolRegistry) Get(name string) (toolshared.Tool, bool)

func (*ToolRegistry) GetAll 

func (r *ToolRegistry) GetAll() []toolshared.Tool

GetAll returns all registered tools (both core and non-core with TTL > 0). Used by SubTurn to inherit parent's tool set.

func (*ToolRegistry) GetDefinitions 

func (r *ToolRegistry) GetDefinitions() []map[string]any

func (*ToolRegistry) GetSummaries 

func (r *ToolRegistry) GetSummaries() []string

GetSummaries returns human-readable summaries of all registered tools. Returns a slice of "name - description" strings.

func (*ToolRegistry) HasRegistered 

func (r *ToolRegistry) HasRegistered(name string) bool

HasRegistered reports whether a tool name is present in the registry, including hidden tools whose TTL is currently zero.

func (*ToolRegistry) List 

func (r *ToolRegistry) List() []string

List returns a list of all registered tool names.

func (*ToolRegistry) LoopSemantics 

func (r *ToolRegistry) LoopSemantics(name string) loopguard.Semantics

LoopSemantics returns explicit loop-detection semantics for a registered tool. Unclassified and unavailable tools fail closed as unknown.

func (*ToolRegistry) PromoteTools 

func (r *ToolRegistry) PromoteTools(names []string, ttl int)

PromoteTools atomically sets the TTL for multiple non-core tools. This prevents a concurrent TickTTL from decrementing between promotions.

func (*ToolRegistry) Register 

func (r *ToolRegistry) Register(tool toolshared.Tool)

func (*ToolRegistry) RegisterHidden 

func (r *ToolRegistry) RegisterHidden(tool toolshared.Tool)

RegisterHidden saves hidden tools (visible only via TTL)

func (*ToolRegistry) Seal 

func (r *ToolRegistry) Seal()

Seal freezes catalog membership and visibility for a trusted runtime.

func (*ToolRegistry) SearchBM25 

func (r *ToolRegistry) SearchBM25(query string, maxSearchResults int) []ToolSearchResult

SearchBM25 ranks hidden tools against query using BM25 via utils.BM25Engine. This non-cached variant rebuilds the engine on every call. Used by tests and any code that doesn't hold a BM25SearchTool instance.

func (*ToolRegistry) SearchRegex 

func (r *ToolRegistry) SearchRegex(pattern string, maxSearchResults int) ([]ToolSearchResult, error)

func (*ToolRegistry) SetAllowlist 

func (r *ToolRegistry) SetAllowlist(names []string)

SetAllowlist restricts registrations to the provided runtime tool names. A nil slice means "allow all". An empty-but-non-nil slice means "allow none".

func (*ToolRegistry) SetMediaStore 

func (r *ToolRegistry) SetMediaStore(store media.MediaStore)

SetMediaStore injects a MediaStore into all registered tools that can consume it, and remembers it for future registrations.

func (*ToolRegistry) SnapshotHiddenTools 

func (r *ToolRegistry) SnapshotHiddenTools() HiddenToolSnapshot

SnapshotHiddenTools returns all non-core tools and the current registry version under a single read-lock, guaranteeing consistency between the two values.

func (*ToolRegistry) TickTTL 

func (r *ToolRegistry) TickTTL()

TickTTL decreases TTL only for non-core tools

func (*ToolRegistry) ToProviderDefs 

func (r *ToolRegistry) ToProviderDefs() []providers.ToolDefinition

ToProviderDefs converts tool definitions to provider-compatible format. This is the format expected by LLM provider APIs.

func (*ToolRegistry) TrustedNodeApprovalBypassTarget 

func (r *ToolRegistry) TrustedNodeApprovalBypassTarget(
	name string,
	args map[string]any,
) (string, *TrustedToolExecution, bool)

TrustedNodeApprovalBypassTarget returns the explicit target only when the registered tool carries the package-private first-party node capability.

func (*ToolRegistry) Unregister 

func (r *ToolRegistry) Unregister(name string)

Unregister removes a tool from the registry if present. It is mainly used when creating scoped child registries with a narrower capability surface.

func (*ToolRegistry) ValidateArguments 

func (r *ToolRegistry) ValidateArguments(name string, args map[string]any) error

ValidateArguments checks model-supplied arguments without executing the tool. Approval flows use it before creating durable authority.

func (*ToolRegistry) Version 

func (r *ToolRegistry) Version() uint64

Version returns the current registry version (atomically).

type ToolSearchResult 

type ToolSearchResult struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

ToolSearchResult represents the result returned to the LLM. Parameters are omitted from the JSON response to save context tokens; the LLM will see full schemas via ToProviderDefs after promotion.

type TrustedToolExecution 

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

TrustedToolExecution binds approval provenance to the exact tool instance that must execute. Its fields are intentionally private so callers cannot forge a binding for an injected or replacement tool.

type UpdateGoalTool 

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

UpdateGoalTool lets the model record a terminal goal state.

func NewUpdateGoalTool 

func NewUpdateGoalTool(manager *state.Manager) *UpdateGoalTool

func (*UpdateGoalTool) Description 

func (t *UpdateGoalTool) Description() string

func (*UpdateGoalTool) Execute 

func (t *UpdateGoalTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*UpdateGoalTool) Name 

func (t *UpdateGoalTool) Name() string

func (*UpdateGoalTool) Parameters 

func (t *UpdateGoalTool) Parameters() map[string]any

type UpdatePlanTool 

type UpdatePlanTool struct{}

func NewUpdatePlanTool 

func NewUpdatePlanTool() *UpdatePlanTool

func (*UpdatePlanTool) Description 

func (t *UpdatePlanTool) Description() string

func (*UpdatePlanTool) Execute 

func (t *UpdatePlanTool) Execute(ctx context.Context, args map[string]any) *toolshared.ToolResult

func (*UpdatePlanTool) Name 

func (t *UpdatePlanTool) Name() string

func (*UpdatePlanTool) Parameters 

func (t *UpdatePlanTool) Parameters() map[string]any

type WorkspaceExecTool 

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

WorkspaceExecTool binds one explicit remote workspace to the existing system.exec.v1 or job.start.v1 invocation path. It owns no process or job lifecycle of its own.

func NewWorkspaceExecTool 

func NewWorkspaceExecTool(
	cfg *config.Config,
	source NodeInvocationSource,
	agentID string,
) (*WorkspaceExecTool, error)

func (*WorkspaceExecTool) ApprovalArguments 

func (tool *WorkspaceExecTool) ApprovalArguments(
	ctx context.Context,
	args map[string]any,
) (map[string]any, error)

func (*WorkspaceExecTool) Description 

func (*WorkspaceExecTool) Description() string

func (*WorkspaceExecTool) Execute 

func (tool *WorkspaceExecTool) Execute(
	ctx context.Context,
	args map[string]any,
) *toolshared.ToolResult

func (*WorkspaceExecTool) Name 

func (*WorkspaceExecTool) Name() string

func (*WorkspaceExecTool) Parameters 

func (tool *WorkspaceExecTool) Parameters() map[string]any

func (*WorkspaceExecTool) SetEventPublisher 

func (tool *WorkspaceExecTool) SetEventPublisher(eventBus runtimeevents.Bus)

func (*WorkspaceExecTool) SetInvocationSourceFactory 

func (tool *WorkspaceExecTool) SetInvocationSourceFactory(
	factory func() (NodeInvocationSource, error),
)

SetInvocationSourceFactory makes generation-bound gateway authority resolve at call time, after any config-reload node reconciliation has completed.

func (*WorkspaceExecTool) ToolLoopSemantics 

func (*WorkspaceExecTool) ToolLoopSemantics() loopguard.Semantics

Source Files

View all Source files

Directories

Path Synopsis

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.