Documentation
¶
Overview ¶
Package agent invokes the user's own coding-agent CLI for one-shot prompted tasks — the inference seam behind features like lesson distillation. Seamark never holds credentials and never speaks a model API: it shells out to a CLI the user already has and has already authenticated, the same trust boundary as `gh` for review mining. An absent or failing CLI degrades to an error the caller surfaces as a note, never a broken feature.
Callers use a shared Invoker interface. This package provides the Claude preset; internal/integration registers other clients through CommandSpec. Custom argv supports additional CLIs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CommandSpec ¶ added in v0.7.0
type CommandSpec struct {
// Name identifies the client for provenance ("distilled by …").
Name string
// Argv is the command and its arguments, prompt delivered on stdin.
Argv []string
// Dir is the working directory for the process. Empty inherits the
// caller's directory, which is the legacy custom-argv behavior.
Dir string
// Diagnostic selects error output; the default keeps the first non-empty line.
Diagnostic Diagnostic
}
CommandSpec is the exact process one client invocation runs. It is a value, not a running invoker: callers disclose it in dry runs and diagnostics before any process starts, so it must not require the binary on PATH or any credential.
func ClaudeCommand ¶ added in v0.7.0
func ClaudeCommand() CommandSpec
ClaudeCommand returns the Claude Code one-shot preset as a spec. The compatibility resolver and the client registry share this one value, so the two paths cannot drift.
func ResolveCommand ¶ added in v0.7.0
func ResolveCommand(cfg *Config) (CommandSpec, error)
ResolveCommand resolves this package's presets without checking PATH. Custom argv takes precedence, uses the name "custom", and inherits the caller's directory. The default preset is Claude. The client registry resolves additional clients separately.
func (CommandSpec) Validate ¶ added in v0.7.0
func (s CommandSpec) Validate() error
Validate requires a name, executable, and known diagnostic rule. It does not check PATH.
type Config ¶
type Config struct {
Agent struct {
// CLI names a preset ("claude"). Ignored when Argv is set.
CLI string `yaml:"cli"`
// Argv is the escape hatch for any other agent: the exact
// command to run, prompt delivered on stdin.
Argv []string `yaml:"argv"`
} `yaml:"agent"`
}
Config selects the agent CLI (`agent:` in .seamark/config.yaml — committed, like every seamark overlay, so a team shares one choice). An absent section means the claude preset.
func LoadConfig ¶
LoadConfig reads the agent section of <root>/.seamark/config.yaml. The file is shared with the indexing options; each package reads its own section. A missing file yields defaults; a malformed one is an error (the same contract as everywhere else: a typo'd config must not be silently ignored).
func ParseConfig ¶ added in v0.8.0
ParseConfig decodes the agent section from the bytes of config.yaml. LoadConfig calls it, so both entry points report the same error text. The settings editor calls it to validate planned bytes before a write. Empty input yields the defaults, the same as an absent file.
type Diagnostic ¶ added in v0.7.0
type Diagnostic string
Diagnostic selects which output Invoke includes in an error. Claude prints errors first; Codex prints them after a banner. Each client chooses a rule for the shared invoker to apply.
const ( // DiagnosticFirstLine keeps the first non-empty line, preserving legacy behavior. DiagnosticFirstLine Diagnostic = "" // DiagnosticTail keeps the last few non-empty lines, oldest first. DiagnosticTail Diagnostic = "tail" )
type Invoker ¶
type Invoker interface {
// Invoke sends prompt on the agent's stdin and returns its text
// reply. The context bounds the run: a distillation batch is worth
// minutes, not hours.
Invoke(ctx context.Context, prompt string) (string, error)
// Name identifies the adapter for provenance ("distilled by …").
Name() string
}
Invoker runs one prompted task against the configured agent CLI.
func New ¶
New wraps ResolveCommand and NewCommand for this package's presets. Invalid configuration or a missing executable fails before invocation.
func NewCommand ¶ added in v0.7.0
func NewCommand(spec CommandSpec) (Invoker, error)
NewCommand validates the spec and checks PATH before returning an Invoker. It neither starts the client nor accesses credentials.
func NewGroupCommand ¶ added in v0.8.0
func NewGroupCommand(spec CommandSpec) (Invoker, error)
NewGroupCommand is NewCommand for a caller that no terminal interrupt reaches, such as the full-screen console in raw mode. Each run starts the client in a new process group. Cancellation then kills the whole group, so a wrapper script or a launcher cannot leave its model call running. The end of each run kills the group too, so no descendant outlives the call. The commands keep NewCommand: a terminal interrupt stops them only while the client shares their process group.
The new group is not the foreground group of the terminal, so no terminal signal reaches the client, a hangup included. The caller must turn such a signal into a cancellation of the context.
Source Files