Documentation
¶
Overview ¶
Package agents provides the framework for codefly service agents: gRPC servers that the CLI spawns as subprocesses to handle the service lifecycle (Load → Init → Start → Stop → Destroy) and the build / deploy / code-analysis flows.
Every codefly agent (go-grpc, postgres, vault, redis, nextjs, …) implements a subset of these capabilities by registering server types from sub-packages:
agentv0.AgentServer — identity + capabilities (always required) runtimev0.RuntimeServer — service-process lifecycle builderv0.BuilderServer — Docker build, k8s deploy, scaffolding codev0.CodeServer — file/git/LSP operations toolingv0.ToolingServer — language-specific analysis
The Serve function binds a gRPC listener (default 127.0.0.1:0; override via CODEFLY_AGENT_BIND_ADDR), registers every server the agent declared in its PluginRegistration, exposes a standard grpc.health.v1 endpoint, and prints "<protocol-version>|<port>" on stdout so the parent CLI knows where to dial. SIGTERM/SIGINT trigger a graceful shutdown that fans out through Runtime.Stop before the gRPC server exits.
Sub-packages:
manager — CLI-side. Spawns agent processes, connects, dispatches RPCs. services — base types agents embed (RuntimeServer, BuilderServer, etc). helpers — shared helpers (Docker, code analysis). communicate — interactive Q&A protocol (used by Create flow).
Index ¶
- Constants
- func AddProcessor(processor wool.LogProcessorWithSource)
- func NewAgentLogger(agent *resources.Agent) wool.LogProcessor
- func NewAgentProvider(ctx context.Context, agent *resources.Agent) *wool.Provider
- func NewAgentServiceLogger(identity *resources.ServiceIdentity) wool.LogProcessor
- func NewServiceAgentProvider(ctx context.Context, identity *resources.ServiceIdentity) *wool.Provider
- func NewServiceLogger(identity *resources.ServiceIdentity) wool.LogProcessor
- func NewServiceProvider(ctx context.Context, identity *resources.ServiceIdentity) *wool.Provider
- func ResetRPCStats()
- func Serve(reg PluginRegistration)
- func SnapshotRPCStats() map[string]rpcMethodStats
- type AgentLogger
- type ChannelLog
- type ChannelProcessor
- type LogHandler
- type LogMessage
- type PluginRegistration
Constants ¶
const ProtocolVersion = 1
ProtocolVersion is used for future-proofing the stdout handshake.
Variables ¶
This section is empty.
Functions ¶
func AddProcessor ¶ added in v0.0.55
func AddProcessor(processor wool.LogProcessorWithSource)
func NewAgentLogger ¶
func NewAgentLogger(agent *resources.Agent) wool.LogProcessor
NewAgentLogger creates a log processor for an agent that writes to stderr.
func NewAgentProvider ¶ added in v0.0.55
NewAgentProvider creates a wool provider for an agent.
func NewAgentServiceLogger ¶ added in v0.1.83
func NewAgentServiceLogger(identity *resources.ServiceIdentity) wool.LogProcessor
NewAgentServiceLogger creates a log processor for a service agent.
func NewServiceAgentProvider ¶ added in v0.1.83
func NewServiceAgentProvider(ctx context.Context, identity *resources.ServiceIdentity) *wool.Provider
NewServiceAgentProvider creates a wool provider for a service agent.
func NewServiceLogger ¶
func NewServiceLogger(identity *resources.ServiceIdentity) wool.LogProcessor
NewServiceLogger creates a log processor for a service.
func NewServiceProvider ¶ added in v0.0.55
NewServiceProvider creates a wool provider for a service.
func ResetRPCStats ¶ added in v0.1.155
func ResetRPCStats()
ResetRPCStats clears all counters. Test-only — production agents should never call this (loses telemetry).
func Serve ¶ added in v0.1.155
func Serve(reg PluginRegistration)
Serve starts a gRPC server, registers the plugin's services, signals its endpoint to the CLI via stdout, and blocks until the process is terminated.
Plugin binaries call this from main():
agents.Serve(agents.PluginRegistration{
Agent: svc,
Runtime: NewRuntime(),
Builder: NewBuilder(),
Code: NewCode(),
})
Transport selection (env vars set by the host):
- CODEFLY_AGENT_UDS_PATH=/tmp/codefly/foo.sock — listen on a Unix domain socket at that path. Preferred for performance and for filesystem-permission–based access control. Removes the socket file on graceful shutdown; the host removes stale files before respawn after crashes.
- CODEFLY_AGENT_BIND_ADDR=<host> — TCP fallback bind host (port stays :0). Set when CLI and plugin run in different network namespaces (Docker on Linux without host networking, sidecar deploys). Implies "0.0.0.0" pairs with TLS + auth — both TODO.
- Neither set: TCP on 127.0.0.1:0 (random loopback port).
Handshake on stdout: "<ProtocolVersion>|<endpoint>" where endpoint is either a numeric port (TCP) or "unix:<path>" (UDS). Both forms are accepted by the host loader.
func SnapshotRPCStats ¶ added in v0.1.155
func SnapshotRPCStats() map[string]rpcMethodStats
SnapshotRPCStats returns a deep copy of the current per-method stats. Safe to call concurrently with live RPCs.
Types ¶
type AgentLogger ¶
type AgentLogger struct {
// contains filtered or unexported fields
}
AgentLogger writes structured wool logs to stderr as JSON. The CLI reads these from the spawned process's stderr.
func (*AgentLogger) Process ¶ added in v0.0.55
func (w *AgentLogger) Process(log *wool.Log)
type ChannelLog ¶ added in v0.1.155
type ChannelLog struct {
Source *wool.Identifier
Log *wool.Log
}
ChannelLog carries a structured log with its source through a channel.
type ChannelProcessor ¶ added in v0.1.155
type ChannelProcessor struct {
Ch chan<- ChannelLog
}
ChannelProcessor sends logs to a channel for consumption by a TUI or other event-driven consumer.
func NewChannelProcessor ¶ added in v0.1.155
func NewChannelProcessor(ch chan<- ChannelLog) *ChannelProcessor
NewChannelProcessor creates a processor that sends logs on ch. The channel should be buffered to avoid blocking the log pipeline.
func (*ChannelProcessor) Process ¶ added in v0.1.155
func (p *ChannelProcessor) Process(log *wool.Log)
func (*ChannelProcessor) ProcessWithSource ¶ added in v0.1.155
func (p *ChannelProcessor) ProcessWithSource(source *wool.Identifier, log *wool.Log)
type LogHandler ¶ added in v0.0.55
type LogHandler struct {
// contains filtered or unexported fields
}
LogHandler processes structured logs from agent processes.
func GetLogHandler ¶ added in v0.1.155
func GetLogHandler() *LogHandler
func (*LogHandler) ForwardLogs ¶ added in v0.1.155
func (h *LogHandler) ForwardLogs(r io.Reader)
ForwardLogs reads structured JSON log lines from a reader (typically the stderr of a spawned agent process) and dispatches them to registered log processors. Blocks until the reader is closed.
type LogMessage ¶
type LogMessage struct {
Log *wool.Log `json:"log"`
Source *wool.Identifier `json:"identifier"`
}
LogMessage is the JSON envelope written to stderr.
type PluginRegistration ¶ added in v0.1.155
type PluginRegistration struct {
Agent agentv0.AgentServer
Runtime runtimev0.RuntimeServer
Builder builderv0.BuilderServer
Code codev0.CodeServer // Deprecated: use Tooling/Toolbox for language-specific operations.
Tooling toolingv0.ToolingServer // Transitional: collapses into Toolbox via lang.* convention.
Toolbox toolboxv0.ToolboxServer // The unified callable contract (MCP-shape).
}
PluginRegistration holds the gRPC servers a plugin wants to expose. All registration is handled by core -- plugins never import grpc directly.
Plugins implement the capabilities they need:
- Infrastructure (redis, postgres): Agent + Runtime
- Application (go-grpc, python-fastapi): Agent + Runtime + Builder + Tooling/Toolbox
- Capability toolboxes (git, docker, nix, web, grpc): Agent + Toolbox only
- Tooling-only (go-analyzer): Agent + Tooling
Separation of concerns:
- Runtime: service lifecycle (Load/Init/Start/Stop/Destroy)
- Builder: Docker build + k8s deploy + scaffolding
- Code: file/git/LSP operations (deprecated — use Tooling/Toolbox for language-specific ops)
- Tooling: language-specific typed analysis (LSP, callgraph, fix, deps, build/test/lint). To be collapsed into Toolbox via the conventional `lang.*` tool set; remains for transition while consumers (Mind) migrate to the typed wrapper over CallTool.
- Toolbox: MCP-shape callable surface — Identity / ListTools / CallTool / Resources / Prompts. The unified contract going forward. Capability plugins (git, docker, nix, web, grpc) expose only this; language plugins expose it alongside Tooling until the migration completes.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
helpers
|
|
|
audit
Package audit runs language-specific dependency audits on behalf of codefly Builder agents.
|
Package audit runs language-specific dependency audits on behalf of codefly Builder agents. |
|
upgrade
Package upgrade applies dependency bumps on behalf of codefly Builder agents.
|
Package upgrade applies dependency bumps on behalf of codefly Builder agents. |
|
Package testing provides helpers for agent composition + lifecycle tests.
|
Package testing provides helpers for agent composition + lifecycle tests. |