agentd

README

agentd

Helpers for local-scoped agent daemons.

Install

go get github.com/brandonkramer/agentd

Usage

Resolve the daemon home (from AGENTD_HOME or ~/.agentd):

home, err := agentd.Agentd.Resolve()
if err != nil {
    return err
}

Mark child processes with run metadata:

env := agentd.ChildEnv(home, runID, map[string]string{
    "WORK_DIR": workDir,
})

Prepare a headless run (built-in harnesses: generic-command, claude-code):

h, err := harness.Get("generic-command")
if err != nil {
    return err
}

prep, err := h.Prepare(&harness.WorkInput{
    RunDir:          runDir,
    WorkDir:         workDir,
    CommandTemplate: "claude -p < {prompt}",
    PromptContent:   prompt,
})
if err != nil {
    return err
}
// prep.Command, prep.ExecPath, prep.ExecArgs, prep.PromptPath

Load managed agents from ~/agents.toml and project .agentd/agents.toml:

managed.SetDriverValidator(func(name string) error {
    _, err := harness.Get(name)
    return err
})

specs, err := managed.LoadMergedSpecs(home, projectRoot, managed.DefaultStore)
if err != nil {
    return err
}

mgr, err := managed.NewReconcilerManager(home, projectRoot, engine, managed.DefaultStore)
if err != nil {
    return err
}

Development

make check

Documentation

Overview

Package agentd provides domain helpers for user-scoped agent daemons: home layout defaults, run environment keys, harness registry, and managed-agent reconciliation.

Generic local JSON-RPC daemon plumbing lives in github.com/brandonkramer/locdaemon. Import locdaemon subpackages directly for client dial/call, runtime loop, and observe topic names:

import (
    locclient "github.com/brandonkramer/locdaemon/client"
    loclayout "github.com/brandonkramer/locdaemon/layout"
    locruntime "github.com/brandonkramer/locdaemon/runtime"
    locobserve "github.com/brandonkramer/locdaemon/observe"
    "github.com/brandonkramer/agentd"
)

Subpackages: harness (named run implementations), managed (catalog, state, reconciler). Root exports daemon home layout (Default, Agentd) and run env helpers (ChildEnv, VerifyRunID).

Shared libraries: github.com/brandonkramer/locdaemon, github.com/brandonkramer/catalogfile, github.com/brandonkramer/ipc, github.com/brandonkramer/message, github.com/brandonkramer/poll, github.com/brandonkramer/reconciler, github.com/brandonkramer/jsonfile, github.com/brandonkramer/filelock, github.com/brandonkramer/registry, github.com/brandonkramer/svcroot, github.com/brandonkramer/procenv, github.com/brandonkramer/shellquote.

Index

• Constants
• Variables
• func ChildEnv(home, runID string, extra map[string]string) []string
• func VerifyRunID(runID string, pid int, alive func(int) bool, fallback *proctree.Spec) bool
• type Layout
• type Service

Constants

const (
	// EnvRunID marks a child process with its run id.
	EnvRunID = "AGENTD_RUN_ID"
	// EnvHome marks a child process with its daemon home.
	EnvHome = "AGENTD_HOME"
)

Variables

var Agentd = Service{
	EnvVar:     "AGENTD_HOME",
	DefaultDir: ".agentd",
	Layout:     Default,
}

Agentd configures home resolution for the agentd daemon.

var Default = Layout{
	SessionsDir:       "sessions",
	SocketName:        "daemon.sock",
	ObserveSocketName: "observe.sock",
	LockName:          "daemon.lock",
	PipePrefix:        "agentd",
}

Default is the conventional agentd layout: home/sessions/{daemon.sock,daemon.lock}.

var Work = Service{
	EnvVar:       "AGENTD_HOME",
	DefaultDir:   ".agentd-work",
	Layout:       WorkLayout,
	RegistryFile: "sessions/known-daemons.json",
}

Work configures home resolution for the agentd-work CLI/daemon.

var WorkLayout = func() Layout {
	l := Default
	l.PipePrefix = "agentd-work"
	return l
}()

WorkLayout is the on-disk layout for agentd-work homes (~/.agentd-work).

Functions

func ChildEnv

func ChildEnv(home, runID string, extra map[string]string) []string

ChildEnv returns os.Environ plus AGENTD_RUN_ID, AGENTD_HOME, and extra keys.

func VerifyRunID

func VerifyRunID(runID string, pid int, alive func(int) bool, fallback *proctree.Spec) bool

VerifyRunID reports whether pid refers to runID, using env markers or fallback spec.

Types

type Layout

type Layout = svcroot.Layout

Layout names files under a daemon home directory.

type Service

type Service = svcroot.Service

Service bundles home resolution and layout defaults.