external

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2026 License: MIT Imports: 18 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.

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

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) 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, localDev bool, force bool) (int, error)

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) 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 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"`
	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.