external

package
v0.10.5 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package external provides an adapter that bridges external agent binaries (discovered via PATH as entire-agent-<name>) to the agent.Agent interface. Communication uses a subcommand-based protocol with JSON over stdin/stdout.

Index

Constants

View Source 
const ProtocolVersion = 1

ProtocolVersion is the current protocol version expected by the CLI.

Variables

This section is empty.

Functions

func DiscoverAndRegister 

func DiscoverAndRegister(ctx context.Context)

DiscoverAndRegister scans $PATH for executables matching "entire-agent-<name>", calls their "info" subcommand, and registers them in the agent registry. Binaries whose name conflicts with an already-registered agent are skipped. Errors during discovery are logged but do not prevent other agents from loading. Discovery is skipped when the external_agents setting is not enabled.

func DiscoverAndRegisterAlways added in v0.5.1 

func DiscoverAndRegisterAlways(ctx context.Context)

DiscoverAndRegisterAlways is like DiscoverAndRegister but bypasses the external_agents settings check. Use this in interactive setup flows where the user explicitly chooses agents.

func DiscoverAndRegisterNamedAlways added in v0.9.0 

func DiscoverAndRegisterNamedAlways(ctx context.Context, name types.AgentName) error

DiscoverAndRegisterNamedAlways discovers and registers only the external agent binary matching name. It bypasses the external_agents setting for explicit, one-invocation selections without executing unrelated plugins.

func IsExternal added in v0.5.1 

func IsExternal(ag agent.Agent) bool

IsExternal reports whether ag is backed by an external agent binary.

func StripExeExt added in v0.6.1 

func StripExeExt(name string) string

StripExeExt removes Windows executable extensions (.exe, .bat, .cmd, .com) from a file name so that the derived name matches on all platforms. On Unix this is effectively a no-op because binaries have no extension.

.com is included because Windows PATHEXT defaults to ".COM;.EXE;.BAT;.CMD;…", so exec.LookPath can resolve a `.com` next to a `.exe`. Without stripping it, a managed-plugin or agent-binary installer would treat foo.exe and foo.com as distinct names while PATHEXT silently picks one.

func Wrap 

func Wrap(ea *Agent) (agent.Agent, error)

Wrap returns the Agent wrapped as an agent.Agent that implements ALL optional interfaces (forwarding to the underlying external agent) plus CapabilityDeclarer. The As* helpers in the agent package use DeclaredCapabilities() to gate access, so callers only see capabilities the external binary actually declared.

Types

type Agent 

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

Agent implements agent.Agent by delegating to an external binary. Each method invokes a subcommand on the binary and parses the JSON response.

func New 

func New(ctx context.Context, binaryPath string) (*Agent, error)

New creates an Agent by calling the binary's "info" subcommand to cache its metadata. Returns an error if the binary cannot be invoked or returns invalid/incompatible protocol data. The provided context bounds the "info" call; pass a context with a deadline to limit how long discovery waits for each binary.

func (*Agent) AreHooksInstalled 

func (e *Agent) AreHooksInstalled(ctx context.Context) (bool, error)

AreHooksInstalled asks the plugin. A plugin that crashes, times out, or prints junk is not a plugin with no hooks, so that is reported as an error rather than collapsed into false — the caller decides what an unknown state means.

func (*Agent) CalculateTokenUsage 

func (e *Agent) CalculateTokenUsage(transcriptData []byte, fromOffset int) (*agent.TokenUsage, error)

func (*Agent) CalculateTotalTokenUsage 

func (e *Agent) CalculateTotalTokenUsage(transcriptData []byte, fromOffset int, subagentsDir string) (*agent.TokenUsage, error)

func (*Agent) ChunkTranscript 

func (e *Agent) ChunkTranscript(ctx context.Context, content []byte, maxSize int) ([][]byte, error)

func (*Agent) CompactTranscript added in v0.5.6 

func (e *Agent) CompactTranscript(ctx context.Context, sessionRef string) (*agent.CompactedTranscript, error)

func (*Agent) Description 

func (e *Agent) Description() string

func (*Agent) DetectPresence 

func (e *Agent) DetectPresence(ctx context.Context) (bool, error)

func (*Agent) ExtractAllModifiedFiles 

func (e *Agent) ExtractAllModifiedFiles(transcriptData []byte, fromOffset int, subagentsDir string) ([]string, error)

func (*Agent) ExtractModifiedFilesFromOffset 

func (e *Agent) ExtractModifiedFilesFromOffset(path string, startOffset int) ([]string, int, error)

func (*Agent) ExtractPrompts 

func (e *Agent) ExtractPrompts(sessionRef string, fromOffset int) ([]string, error)

func (*Agent) ExtractSummary 

func (e *Agent) ExtractSummary(sessionRef string) (string, error)

func (*Agent) FormatResumeCommand 

func (e *Agent) FormatResumeCommand(sessionID string) string

func (*Agent) GenerateText 

func (e *Agent) GenerateText(ctx context.Context, prompt string, model string) (string, error)

func (*Agent) GetSessionDir 

func (e *Agent) GetSessionDir(repoPath string) (string, error)

func (*Agent) GetSessionID 

func (e *Agent) GetSessionID(input *agent.HookInput) string

func (*Agent) GetTranscriptPosition 

func (e *Agent) GetTranscriptPosition(path string) (int, error)

func (*Agent) HookNames 

func (e *Agent) HookNames() []string

func (*Agent) Info 

func (e *Agent) Info() *InfoResponse

Info returns the cached info response.

func (*Agent) InstallHooks 

func (e *Agent) InstallHooks(ctx context.Context, force bool) (int, error)

InstallHooks invokes the external agent's install-hooks subcommand.

The protocol's optional --local-dev flag is never sent: it asked the agent to point hooks at a build inside the working tree, which is exactly the shape that let repository content run from installed hooks. External agents may still accept the flag, but nothing here requests it.

func (*Agent) IsPreview 

func (e *Agent) IsPreview() bool

func (*Agent) Name 

func (e *Agent) Name() types.AgentName

func (*Agent) ParseHookEvent 

func (e *Agent) ParseHookEvent(ctx context.Context, hookName string, stdin io.Reader) (*agent.Event, error)

func (*Agent) PrepareTranscript 

func (e *Agent) PrepareTranscript(ctx context.Context, sessionRef string) error

func (*Agent) ProtectedDirs 

func (e *Agent) ProtectedDirs() []string

func (*Agent) ProtectedFiles added in v0.5.6 

func (e *Agent) ProtectedFiles() []string

func (*Agent) ReadSession 

func (e *Agent) ReadSession(input *agent.HookInput) (*agent.AgentSession, error)

func (*Agent) ReadTranscript 

func (e *Agent) ReadTranscript(sessionRef string) ([]byte, error)

func (*Agent) ReassembleTranscript 

func (e *Agent) ReassembleTranscript(chunks [][]byte) ([]byte, error)

func (*Agent) ResolveSessionFile 

func (e *Agent) ResolveSessionFile(sessionDir, agentSessionID string) string

func (*Agent) Type 

func (e *Agent) Type() types.AgentType

func (*Agent) UninstallHooks 

func (e *Agent) UninstallHooks(ctx context.Context) error

func (*Agent) WriteHookResponse 

func (e *Agent) WriteHookResponse(message string) error

func (*Agent) WriteSession 

func (e *Agent) WriteSession(ctx context.Context, session *agent.AgentSession) error

type AgentSessionJSON 

type AgentSessionJSON struct {
	SessionID     string   `json:"session_id"`
	AgentName     string   `json:"agent_name"`
	RepoPath      string   `json:"repo_path"`
	SessionRef    string   `json:"session_ref"`
	StartTime     string   `json:"start_time"`
	NativeData    []byte   `json:"native_data"`
	ModifiedFiles []string `json:"modified_files"`
	NewFiles      []string `json:"new_files"`
	DeletedFiles  []string `json:"deleted_files"`
}

AgentSessionJSON is the JSON representation of agent.AgentSession for stdin/stdout transfer.

type AreHooksInstalledResponse 

type AreHooksInstalledResponse struct {
	Installed bool `json:"installed"`
}

AreHooksInstalledResponse is the JSON returned by the "are-hooks-installed" subcommand.

type ChunkResponse 

type ChunkResponse struct {
	Chunks [][]byte `json:"chunks"`
}

ChunkResponse is the JSON returned by the "chunk-transcript" subcommand.

type CompactTranscriptAssetResponse added in v0.5.6 

type CompactTranscriptAssetResponse struct {
	Name      string `json:"name"`
	MediaType string `json:"media_type"`
	Data      string `json:"data"`
}

CompactTranscriptAssetResponse describes one extracted binary asset.

type CompactTranscriptResponse added in v0.5.6 

type CompactTranscriptResponse struct {
	Transcript string                           `json:"transcript"`
	Assets     []CompactTranscriptAssetResponse `json:"assets,omitempty"`
}

CompactTranscriptResponse is the JSON returned by the "compact-transcript" subcommand.

type DetectResponse 

type DetectResponse struct {
	Present bool `json:"present"`
}

DetectResponse is the JSON returned by the "detect" subcommand.

type ExtractFilesResponse 

type ExtractFilesResponse struct {
	Files           []string `json:"files"`
	CurrentPosition int      `json:"current_position"`
}

ExtractFilesResponse is the JSON returned by file-extraction subcommands.

type ExtractPromptsResponse 

type ExtractPromptsResponse struct {
	Prompts []string `json:"prompts"`
}

ExtractPromptsResponse is the JSON returned by the "extract-prompts" subcommand.

type ExtractSummaryResponse 

type ExtractSummaryResponse struct {
	Summary    string `json:"summary"`
	HasSummary bool   `json:"has_summary"`
}

ExtractSummaryResponse is the JSON returned by the "extract-summary" subcommand.

type GenerateTextResponse 

type GenerateTextResponse struct {
	Text string `json:"text"`
}

GenerateTextResponse is the JSON returned by the "generate-text" subcommand.

type HookInputJSON 

type HookInputJSON struct {
	HookType   string                 `json:"hook_type"`
	SessionID  string                 `json:"session_id"`
	SessionRef string                 `json:"session_ref"`
	Timestamp  string                 `json:"timestamp"`
	UserPrompt string                 `json:"user_prompt,omitempty"`
	ToolName   string                 `json:"tool_name,omitempty"`
	ToolUseID  string                 `json:"tool_use_id,omitempty"`
	ToolInput  json.RawMessage        `json:"tool_input,omitempty"`
	RawData    map[string]interface{} `json:"raw_data,omitempty"`
}

HookInputJSON is the JSON representation of agent.HookInput for stdin/stdout transfer.

type HooksInstalledCountResponse 

type HooksInstalledCountResponse struct {
	HooksInstalled int `json:"hooks_installed"`
}

HooksInstalledCountResponse is the JSON returned by the "install-hooks" subcommand.

type InfoResponse 

type InfoResponse struct {
	ProtocolVersion int                `json:"protocol_version"`
	Name            string             `json:"name"`
	Type            string             `json:"type"`
	Description     string             `json:"description"`
	IsPreview       bool               `json:"is_preview"`
	ProtectedDirs   []string           `json:"protected_dirs"`
	ProtectedFiles  []string           `json:"protected_files"`
	HookNames       []string           `json:"hook_names"`
	Capabilities    agent.DeclaredCaps `json:"capabilities"`
}

InfoResponse is the JSON returned by the "info" subcommand.

type ResumeCommandResponse 

type ResumeCommandResponse struct {
	Command string `json:"command"`
}

ResumeCommandResponse is the JSON returned by the "format-resume-command" subcommand.

type SessionDirResponse 

type SessionDirResponse struct {
	SessionDir string `json:"session_dir"`
}

SessionDirResponse is the JSON returned by the "get-session-dir" subcommand.

type SessionFileResponse 

type SessionFileResponse struct {
	SessionFile string `json:"session_file"`
}

SessionFileResponse is the JSON returned by the "resolve-session-file" subcommand.

type SessionIDResponse 

type SessionIDResponse struct {
	SessionID string `json:"session_id"`
}

SessionIDResponse is the JSON returned by the "get-session-id" subcommand.

type TokenUsageResponse 

type TokenUsageResponse struct {
	InputTokens         int                 `json:"input_tokens"`
	CacheCreationTokens int                 `json:"cache_creation_tokens"`
	CacheReadTokens     int                 `json:"cache_read_tokens"`
	OutputTokens        int                 `json:"output_tokens"`
	APICallCount        int                 `json:"api_call_count"`
	SubagentTokens      *TokenUsageResponse `json:"subagent_tokens,omitempty"`
}

TokenUsageResponse is the JSON returned by token calculation subcommands.

type TranscriptPositionResponse 

type TranscriptPositionResponse struct {
	Position int `json:"position"`
}

TranscriptPositionResponse is the JSON returned by the "get-transcript-position" subcommand.

Source Files

View all Source files

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.