tools

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// PRCommentKindIssue is a conversation comment (the issue comments API).
	PRCommentKindIssue = "issue"
	// PRCommentKindReview is an inline code comment on the diff.
	PRCommentKindReview = "review"
	// PRCommentKindReviewSummary is the top-level body of a submitted review.
	PRCommentKindReviewSummary = "review_summary"
)

Kinds of comments on a pull request or issue.

View Source
const (
	// ReviewStatePending indicates that the review or pre-review is in progress.
	ReviewStatePending = "⏳"
	// ReviewStateApproved indicates that the review concluded with an approval.
	ReviewStateApproved = "✅"
	// ReviewStateRejected indicates that the review concluded with a rejection.
	ReviewStateRejected = "❎"
	// ReviewStateElse indicates non-blocking feedback, uncertain outcome, or general completion.
	ReviewStateElse = "✳️"
)
View Source
const OtherChoiceOption = "Other (specify below)"

Variables

View Source
var DefaultPreferredHarnesses = []string{"antigravity", "opencode", "claudeAgent", "codex"}

DefaultPreferredHarnesses defines standard priority of coding harnesses.

View Source
var DefaultPreferredOmnigentHarnesses = []string{
	"antigravity-native-ui",
	"opencode-native-ui",
	"claude-native-ui",
	"codex-native-ui",
	"cursor-native-ui",
	"pi-native-ui",
}

DefaultPreferredOmnigentHarnesses defines standard priority of coding harnesses in Omnigent.

View Source
var ErrDiffTooLarge = errors.New("PR diff exceeds GitHub API limit (406)")

ErrDiffTooLarge is returned when GitHub rejects a PR diff request with HTTP 406 (e.g. diff exceeds limit).

Functions

func AskDeveloperTimeout added in v0.9.0

func AskDeveloperTimeout(ctx context.Context) time.Duration

AskDeveloperTimeout returns the configured timeout for developer elicitation from context, or the default 2-minute timeout if unset.

func CleanThreadTitle added in v0.8.0

func CleanThreadTitle(title string) string

CleanThreadTitle strips existing review status emoji prefixes (and following spaces) from a thread title.

func ContextWithStateWriter added in v0.6.0

func ContextWithStateWriter(ctx context.Context, w io.Writer) context.Context

ContextWithStateWriter returns a new context carrying the given state writer. This is retained for test assertions and potential downstream integrations where state is logged directly via context (rather than through reporter callbacks).

func FetchGitCommits

func FetchGitCommits(ctx context.Context, workingDir, base, head string) (string, error)

FetchGitCommits returns a bulleted list of commit subjects (first line of message) between base and head, excluding merge commits.

func FetchGitDiff

func FetchGitDiff(ctx context.Context, workingDir, base, head string, ignoredLockFiles []string) (string, []string, error)

func FetchPRDiff added in v0.8.0

func FetchPRDiff(ctx context.Context, client *github.Client, owner, repo string, prNumber int, paths []string, ignoredLockFiles []string) (string, error)

FetchPRDiff fetches the git diff for a PR. If paths are supplied, only diffs for those paths are returned. Lockfiles in ignoredLockFiles are omitted.

func FetchPRFiles added in v0.8.0

func FetchPRFiles(ctx context.Context, client *github.Client, owner, repo string, prNumber int, ignoredLockFiles []string) ([]string, error)

FetchPRFiles fetches the list of changed files for a pull request, excluding ignored lock files.

func FormatHarnessOptionsForDeveloper added in v0.9.0

func FormatHarnessOptionsForDeveloper(choices []CodingHarnessChoice) []string

FormatHarnessOptionsForDeveloper converts candidate choices to string options for ask_developer.

func FormatOmnigentAgentOptionsForDeveloper added in v0.9.0

func FormatOmnigentAgentOptionsForDeveloper(choices []OmnigentAgentChoice) []string

FormatOmnigentAgentOptionsForDeveloper converts candidate choices to string options for ask_developer.

func FormatThreadTitle added in v0.8.0

func FormatThreadTitle(emoji, baseTitle string) string

FormatThreadTitle formats a thread title with the specified review status emoji prefix.

func GetCurrentSessionTitle added in v0.9.0

func GetCurrentSessionTitle(ctx context.Context) (string, error)

GetCurrentSessionTitle returns the title of the current Omnigent session if running in Omnigent.

func GetCurrentThreadTitle added in v0.8.0

func GetCurrentThreadTitle(ctx context.Context) (string, error)

GetCurrentThreadTitle returns the title of the current T3 thread if running in a T3 session.

func IsOmnigentSession added in v0.9.0

func IsOmnigentSession() bool

IsOmnigentSession returns true if Cassandra is currently running inside an Omnigent environment.

func IsT3Session added in v0.8.0

func IsT3Session() bool

IsT3Session returns true if Cassandra is currently running inside a T3 Code environment.

func MaskCassandraInCapabilities added in v0.9.0

func MaskCassandraInCapabilities(raw string) string

MaskCassandraInCapabilities marks Cassandra as non-child-task and read-only in orchestrator_capabilities output.

func MaskCassandraInOmnigentAgents added in v0.9.0

func MaskCassandraInOmnigentAgents(raw string) string

MaskCassandraInOmnigentAgents removes or masks Cassandra from sys_agent_list output.

func ParseRepoSlug added in v0.8.0

func ParseRepoSlug(raw string) (owner, repo string, err error)

ParseRepoSlug parses owner and repo from an owner/repo slug or git URL.

func RegisterLocalTools

func RegisterLocalTools(r *Registry, root, base, head string, ignoredLockFiles []string, wishlistDir string, allowAskDeveloper bool, allowPRComment bool, notifier UserNotifier, diffMapProvider func() map[string]string, metadataJSONFile ...string)

func RegisterToolWithArgs added in v0.5.0

func RegisterToolWithArgs[T any](r *Registry, def llm.ToolDef, handler func(ctx context.Context, args T) (string, error))

func ResolveBase added in v0.9.0

func ResolveBase(ctx context.Context, workingDir, base, head string) string

ResolveBase turns a branch name (e.g. a PR base branch from metadata) into the commit that a PR diff should be taken from: the merge-base of base and head.

A bare branch name is ambiguous: git resolves it to the local branch, which can be arbitrarily stale and would make the diff include everything that landed on the base since. So the remote-tracking ref (origin/<base>) is preferred, falling back to base as given (local branch, SHA, or other revision). Using the merge-base rather than the base tip keeps commits that landed on the base after the PR branched off out of the diff and commit list.

The base branch is fetched first (best effort) so that origin/<base> reflects the remote rather than whenever the clone was last updated.

If base cannot be resolved locally it is returned unchanged, so the later git diff/log reports the failure against the name the caller supplied.

func StateWriterFromContext added in v0.6.0

func StateWriterFromContext(ctx context.Context) io.Writer

StateWriterFromContext extracts the state writer from the context, if present.

func UpdateSessionTitlePrefix added in v0.9.0

func UpdateSessionTitlePrefix(ctx context.Context, emoji string) error

UpdateSessionTitlePrefix updates the current Omnigent session title with the specified review status emoji prefix. If not in an Omnigent session, it is a no-op and returns nil.

func UpdateThreadTitlePrefix added in v0.8.0

func UpdateThreadTitlePrefix(ctx context.Context, emoji string) error

UpdateThreadTitlePrefix updates the current T3 thread title with the specified review status emoji prefix. If not in a T3 session, it is a no-op and returns nil.

func WithAskDeveloperTimeout added in v0.6.0

func WithAskDeveloperTimeout(ctx context.Context, d time.Duration) context.Context

WithAskDeveloperTimeout wraps a context to override the ask_developer timeout.

func WithTestStreams added in v0.6.0

func WithTestStreams(ctx context.Context, in io.Reader, out io.Writer) context.Context

WithTestStreams wraps a context to override standard input/output of ask_developer.

Types

type AskDeveloperRequest added in v0.9.0

type AskDeveloperRequest struct {
	Question      string   `json:"question"`
	Reasoning     string   `json:"reasoning"`
	Options       []string `json:"options,omitempty"`
	IsMultiSelect bool     `json:"is_multi_select,omitempty"`
}

AskDeveloperRequest represents a question or prompt presented to the developer.

type AskDeveloperResponse added in v0.9.0

type AskDeveloperResponse struct {
	Status   string   `json:"status"`             // "answered", "skipped", "timeout"
	Selected []string `json:"selected,omitempty"` // selected options, if any
	Response string   `json:"response,omitempty"` // free-text response, if provided
	Message  string   `json:"message,omitempty"`  // explanation when skipped or timed out
}

AskDeveloperResponse represents the structured response from asking the developer.

type CapabilityModel added in v0.9.0

type CapabilityModel struct {
	ID    string `json:"id"`
	Label string `json:"label,omitempty"`
}

CapabilityModel describes a model offered by a provider instance.

type CodingHarnessChoice added in v0.9.0

type CodingHarnessChoice struct {
	InstanceID  string `json:"instanceId"`
	DisplayName string `json:"displayName"`
	ModelID     string `json:"model"`
	ModelLabel  string `json:"modelLabel"`
	IsPreferred bool   `json:"isPreferred"`
}

CodingHarnessChoice describes a candidate coding harness option for the developer.

func GetAvailableCodingHarnessChoices added in v0.9.0

func GetAvailableCodingHarnessChoices(capabilitiesRaw string, cfg T3LaunchConfig) []CodingHarnessChoice

GetAvailableCodingHarnessChoices inspects capabilities and returns candidate coding choices.

type DefaultTerminalPrompter added in v0.9.0

type DefaultTerminalPrompter struct{}

DefaultTerminalPrompter prompts the developer via Charm huh forms in the terminal.

func (DefaultTerminalPrompter) AskDeveloper added in v0.9.0

type DeveloperPrompter added in v0.9.0

type DeveloperPrompter interface {
	AskDeveloper(ctx context.Context, req AskDeveloperRequest) (AskDeveloperResponse, error)
}

DeveloperPrompter handles presenting clarification questions to the developer across different interaction modes (terminal, TUI, ACP elicitation, etc.).

type FetchPRCommentsOptions added in v0.9.0

type FetchPRCommentsOptions struct {
	// MaxPagesPerKind limits how many pages (of 100 comments) are read for each of the conversation
	// and inline review comment lists. Zero means no limit.
	MaxPagesPerKind int
	// IgnoreMissingReviewComments treats a 404 from the review comments endpoint as "none". It lets
	// the same call work for plain issues, which have no inline comments.
	IgnoreMissingReviewComments bool
}

FetchPRCommentsOptions tunes FetchPRComments. The zero value fetches every page and fails on any API error.

type ModelSelection added in v0.8.0

type ModelSelection struct {
	InstanceID string `json:"instanceId,omitempty"`
	Model      string `json:"model"`
	Options    any    `json:"options,omitempty"`
	Provider   string `json:"provider,omitempty"`
}

ModelSelection specifies provider instance and model parameters for thread launch.

func ResolveLaunchHarness added in v0.9.0

func ResolveLaunchHarness(capabilitiesRaw string, cfg T3LaunchConfig, requested *ModelSelection) (*ModelSelection, error)

ResolveLaunchHarness deterministically picks an enabled coding harness and model.

type NoOpUserNotifier added in v0.6.0

type NoOpUserNotifier struct{}

func (NoOpUserNotifier) NotifyUser added in v0.6.0

func (NoOpUserNotifier) NotifyUser()

type OmnigentAgentChoice added in v0.9.0

type OmnigentAgentChoice struct {
	AgentID     string `json:"agentId"`
	DisplayName string `json:"displayName"`
	Harness     string `json:"harness"`
	IsPreferred bool   `json:"isPreferred"`
}

OmnigentAgentChoice describes a candidate coding agent option for the developer.

func GetAvailableOmnigentAgentChoices added in v0.9.0

func GetAvailableOmnigentAgentChoices(agentListRaw string, cfg OmnigentLaunchConfig) []OmnigentAgentChoice

GetAvailableOmnigentAgentChoices inspects agent list and returns candidate coding choices.

type OmnigentAgentEntry added in v0.9.0

type OmnigentAgentEntry struct {
	AgentID           string `json:"agent_id"`
	Name              string `json:"name"`
	Description       string `json:"description,omitempty"`
	Harness           string `json:"harness"`
	AvailableOnHost   *bool  `json:"available_on_host,omitempty"`
	UnavailableReason string `json:"unavailable_reason,omitempty"`
}

OmnigentAgentEntry describes an agent returned by sys_agent_list.

func FilterEnabledOmnigentAgents added in v0.9.0

func FilterEnabledOmnigentAgents(agents []OmnigentAgentEntry) []OmnigentAgentEntry

FilterEnabledOmnigentAgents filters out Cassandra and unavailable harnesses.

func ResolveOmnigentLaunchAgent added in v0.9.0

func ResolveOmnigentLaunchAgent(agentListRaw string, cfg OmnigentLaunchConfig, requestedAgentID string) (*OmnigentAgentEntry, error)

ResolveOmnigentLaunchAgent deterministically picks an enabled coding agent in Omnigent.

type OmnigentAgentListResponse added in v0.9.0

type OmnigentAgentListResponse struct {
	Builtins      []OmnigentAgentEntry `json:"builtins"`
	SessionAgents []OmnigentAgentEntry `json:"session_agents"`
	LocalConfigs  []OmnigentAgentEntry `json:"local_configs"`
}

OmnigentAgentListResponse mirrors sys_agent_list output.

type OmnigentLaunchConfig added in v0.9.0

type OmnigentLaunchConfig struct {
	PreferredHarnesses []string
	PreferredModel     string
	PromptForHarness   bool
}

OmnigentLaunchConfig specifies launch configuration for Omnigent sessions.

type OmnigentSessionLaunchArgs added in v0.9.0

type OmnigentSessionLaunchArgs struct {
	Title           string `json:"title"`
	Message         string `json:"message"`
	AgentID         string `json:"agentId,omitempty"`
	Model           string `json:"model,omitempty"`
	Placement       string `json:"placement,omitempty"`
	ReasoningEffort string `json:"reasoningEffort,omitempty"`
}

OmnigentSessionLaunchArgs represents arguments passed to omnigent_session_launch.

type OrchestratorCapabilities added in v0.9.0

type OrchestratorCapabilities struct {
	ParentThreadID              string               `json:"parentThreadId"`
	InheritedProviderInstanceID string               `json:"inheritedProviderInstanceId"`
	InheritedModel              string               `json:"inheritedModel"`
	InheritedOptions            any                  `json:"inheritedOptions"`
	RuntimeMode                 string               `json:"runtimeMode"`
	InteractionMode             string               `json:"interactionMode"`
	Providers                   []ProviderCapability `json:"providers"`
}

OrchestratorCapabilities mirrors T3's orchestrator_capabilities payload.

type PRCommentRecord added in v0.9.0

type PRCommentRecord struct {
	Kind    string
	ID      int64
	Number  int // pull request or issue number; 0 when the API response does not say
	Author  string
	Body    string
	Created time.Time
	Updated time.Time
	URL     string
	State   string // review summaries only, e.g. APPROVED

	// Inline review comments only.
	Path         string
	Line         int
	StartLine    int
	OriginalLine int
	Outdated     bool
}

PRCommentRecord is the neutral, API-shaped form of a comment on a pull request or issue. It is shared by the comment tools and by the cmd/github utility, which maps it to its own types.

func FetchPRComments added in v0.9.0

func FetchPRComments(ctx context.Context, client *github.Client, owner, repo string, number int, opts FetchPRCommentsOptions) (comments []PRCommentRecord, truncated bool, err error)

FetchPRComments lists the conversation comments and the inline review comments of a pull request (or, with IgnoreMissingReviewComments, an issue), oldest first. truncated reports that MaxPagesPerKind stopped the listing before all comments were read.

func (PRCommentRecord) DisplayLine added in v0.9.0

func (c PRCommentRecord) DisplayLine() int

DisplayLine returns the line to show for an inline comment: the current line, or the line the comment was originally made on when the code has since changed.

type PRStackItem added in v0.8.0

type PRStackItem struct {
	PRNumber int    `json:"pr_number"`
	Title    string `json:"title"`
	Branch   string `json:"branch"`
	Base     string `json:"base"`
	Head     string `json:"head"`
}

PRStackItem represents a pull request in a stacked PR chain.

func FetchPRStack added in v0.8.0

func FetchPRStack(ctx context.Context, client *github.Client, owner, repo string, prNumber int) ([]PRStackItem, error)

FetchPRStack fetches the stacked PR chain for the given PR number using GitHub's native Stacks API. If the PR is not part of a stack (or if stacks are not enabled/available), it returns (nil, nil).

func InferPRStack added in v0.9.0

func InferPRStack(ctx context.Context, client *github.Client, owner, repo string, prNumber int) (stack []PRStackItem, notes []string, err error)

InferPRStack reconstructs a stack of pull requests from their branches: the parent of a PR is the open PR whose head branch is this PR's base branch, and its children are the open PRs based on this PR's head branch. It is the fallback for when GitHub's Stacks API has nothing to say. The result is ordered bottom (closest to the default branch) to top and includes the PR itself; notes describe ambiguities and limits that were hit.

type PRSummary added in v0.8.0

type PRSummary struct {
	PRNumber     int      `json:"pr_number"`
	RepoFullName string   `json:"repo_full_name"`
	Title        string   `json:"title"`
	Description  string   `json:"description"`
	Author       string   `json:"author"`
	Branch       string   `json:"branch"`
	Base         string   `json:"base"`
	Head         string   `json:"head"`
	ChangedFiles []string `json:"changed_files"`
}

PRSummary represents pull request details and changed files for agent tools.

func FetchPRMetadata added in v0.8.0

func FetchPRMetadata(ctx context.Context, client *github.Client, owner, repo string, prNumber int, ignoredLockFiles []string) (*PRSummary, error)

FetchPRMetadata fetches the PR summary including title, description, author, branch refs, and changed files.

type ProviderCapability added in v0.9.0

type ProviderCapability struct {
	ProviderInstanceID           string            `json:"providerInstanceId"`
	DriverKind                   string            `json:"driverKind"`
	DisplayName                  string            `json:"displayName"`
	Models                       []CapabilityModel `json:"models"`
	CanRunChildTask              bool              `json:"canRunChildTask"`
	CanRunCrossProviderChildTask bool              `json:"canRunCrossProviderChildTask"`
	Constraints                  []string          `json:"constraints"`
}

ProviderCapability describes a provider instance in orchestrator_capabilities.

func FilterEnabledCodingProviders added in v0.9.0

func FilterEnabledCodingProviders(providers []ProviderCapability) []ProviderCapability

FilterEnabledCodingProviders filters out Cassandra, read-only providers, and disabled providers.

type Registry

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

func NewRegistry

func NewRegistry() *Registry

func (*Registry) HandleCall

func (r *Registry) HandleCall(ctx context.Context, tc llm.ToolCall) (string, error)

func (*Registry) RegisterTool

func (r *Registry) RegisterTool(def llm.ToolDef, handler ToolHandler)

func (*Registry) SetDeveloperPrompter added in v0.9.0

func (r *Registry) SetDeveloperPrompter(p DeveloperPrompter)

func (*Registry) SetOmnigentConfig added in v0.9.0

func (r *Registry) SetOmnigentConfig(cfg OmnigentLaunchConfig)

func (*Registry) SetT3Config added in v0.9.0

func (r *Registry) SetT3Config(cfg T3LaunchConfig)

func (*Registry) SetVerdictChangeListener added in v0.8.0

func (r *Registry) SetVerdictChangeListener(l VerdictChangeListener)

func (*Registry) ToTools

func (r *Registry) ToTools() []llm.ToolDef

type T3LaunchConfig added in v0.9.0

type T3LaunchConfig struct {
	PreferredHarnesses []string
	PreferredModel     string
	PromptForHarness   bool
}

T3LaunchConfig specifies launch configuration for T3 Code sessions.

type ThreadLaunchArgs added in v0.8.0

type ThreadLaunchArgs struct {
	Title             string             `json:"title"`
	Message           string             `json:"message,omitempty"`
	ModelSelection    *ModelSelection    `json:"modelSelection,omitempty"`
	WorkspaceStrategy *WorkspaceStrategy `json:"workspaceStrategy,omitempty"`
	RuntimeMode       string             `json:"runtimeMode,omitempty"`
	InteractionMode   string             `json:"interactionMode,omitempty"`
	ProjectID         string             `json:"projectId,omitempty"`
	Scratch           *bool              `json:"scratch,omitempty"`
}

ThreadLaunchArgs represents arguments passed to t3_thread_launch.

type ToolHandler

type ToolHandler func(ctx context.Context, tc llm.ToolCall) (string, error)

type UserNotifier added in v0.6.0

type UserNotifier interface {
	NotifyUser()
}

type VerdictChangeListener added in v0.8.0

type VerdictChangeListener func(ctx context.Context, verdict string, rationale string) error

VerdictChangeListener is invoked whenever the review verdict is updated via update_review_verdict.

type WorkspaceStrategy added in v0.8.0

type WorkspaceStrategy struct {
	Type            string `json:"type"`
	BaseRef         string `json:"baseRef,omitempty"`
	Branch          string `json:"branch,omitempty"`
	StartFromOrigin *bool  `json:"startFromOrigin,omitempty"`
	WorktreePath    string `json:"worktreePath,omitempty"`
}

WorkspaceStrategy specifies workspace configuration for a launched thread.

Directories

Path Synopsis
mcp_servers

Jump to

Keyboard shortcuts

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