Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrStdinClosed = errors.New("clihelper: stdin closed")
ErrStdinClosed is returned from StdinController.Write when the subprocess stdin has already been closed (either because the subprocess exited or because an earlier write failed). Callers treat this as an abort signal for any pending HITL flow.
Functions ¶
This section is empty.
Types ¶
type ChunkObserver ¶
ChunkObserver is the adapter-supplied callback invoked once per raw chunk read from stdout or stderr.
Semantics:
- stream is either "stdout" or "stderr".
- chunk may not be a complete line; adapters are responsible for any line buffering.
- helper emits the RunEventChunk event BEFORE invoking Observe so that downstream consumers can still correlate the raw event with any transcript item the adapter subsequently emits.
- Returning a non-nil error aborts the run with that error.
type CommandRequest ¶
type CommandRequest struct {
Command string
Args []string
CWD string
Env []driver.EnvBinding
Prompt string
// Observe is optional. When set, the helper calls it for every raw chunk
// it reads from stdout/stderr. The helper itself never parses or
// interprets the chunk bytes.
Observe ChunkObserver
// Stdin controls how the subprocess stdin is fed.
//
// - Stdin == nil (default): the helper writes
// Prompt once and closes stdin immediately. Use this for one-shot
// prompt pipelines.
// - Stdin != nil: the helper enables long-lived stdin. Prompt (if
// non-empty) is written as the first frame, then the helper
// forwards every frame arriving via Stdin.Write until either
// Stdin.Close is called, ctx is cancelled, or the subprocess
// exits.
//
// Helper owns the lifecycle after Run returns: stdin is always closed
// on the way out.
Stdin StdinController
}
type CommandResult ¶
type CommandResult struct {
RawStreams driver.RawStreams
ExitCode int
Signal string
TimedOut bool
}
func Run ¶
func Run(ctx context.Context, req CommandRequest, sink driver.EventSink) (CommandResult, error)
Run executes the requested command and streams raw stdout/stderr chunks to sink and (optionally) the Observe callback. The returned CommandResult always contains the full captured RawStreams, regardless of exit status. Once a process starts, a non-zero exit, signal, or context-driven process termination is represented in CommandResult rather than returned as an error. This lets the Driver parse the complete provider protocol first; the common invocation boundary supplies a structured fallback when the provider protocol offers no more specific failure. Returned errors are reserved for launch, pipe, observation, and other helper failures.
type StdinController ¶
StdinController lets an adapter drive the subprocess stdin throughout the run instead of using the default one-shot prompt lifecycle.
Intended for HITL-interactive adapters (for example Claude's bidirectional stream-json mode) that need to inject user tool_result frames after the CLI emits a tool_use event.
Concurrency:
- Write is safe to call from the parser goroutine (clihelper serialises writes internally).
- The caller does NOT need to call Close; the helper closes stdin when the run ends (subprocess exit or ctx cancel). Close is provided for adapters that want to signal "no more input" earlier than that.
func NewStdinController ¶
func NewStdinController() StdinController
NewStdinController returns a new StdinController tied to a single subprocess. It is populated by clihelper.Run when the caller sets CommandRequest.Stdin to this value; callers create it up front so they can start a goroutine that writes frames as soon as the subprocess spawns.
ctrl := clihelper.NewStdinController()
go func() {
ctrl.Write([]byte(`{"type":"user",...}` + "\n"))
// … react to parser events, write more frames …
}()
clihelper.Run(ctx, CommandRequest{Stdin: ctrl, …}, sink)
Source Files