console

Documentation

Overview

Package console runs the terminal client: a view of an agent's record and its events, which sends what the user asks as intents to a controller. It is the one call an embedding program makes: give the client a client.Record of the session, a client.Source of the agent's events and a client.Controller, then Run. For an agent driven through agentturn's control contract (agentkit's Kit.Control in process, agentturn's front/control Dial over a wire), the control is the source and client.Direct the controller:

agent := agentturn.New(kit.Config(), kit.AgentOptions()...)
defer kit.Attach(agent)()
ctl, err := kit.Control(agent)
if err != nil {
	return err
}
rec, err := client.RecordOf(kit.Recorder())
if err != nil {
	return err
}
return console.Run(ctx, rec, ctl, client.Direct(ctl))

A product with intents of its own to handle (answering some questions by rule, recording an answer as a person's, forwarding to an agent elsewhere) writes its own controller, and may hand the rest to Direct.

Run owns the terminal for as long as it runs and does what the agentconsole binary does: it follows the record and the source's live stream into the view, turns an interrupt signal into the same thing ctrl+c is in raw mode (abort a run, quit when idle), and, once the program ends, aborts a run that is still going and waits for it to write its end before it returns, so the store can be closed behind it.

Index

• Constants
• func Run(ctx context.Context, rec client.Record, src client.Source, ...) error
• type Line
• type Option
  • func WithCost(fn client.Cost) Option
  • func WithDrainTimeout(d time.Duration) Option
  • func WithInput(r io.Reader) Option
  • func WithOutput(w io.Writer) Option
  • func WithSubmit(fn func(ctx context.Context, l Line) (Submit, error)) Option
  • func WithToolRenderers(rs toolview.Renderers) Option
  • func WithWarn(fn func(string)) Option
  • func WithWindowSize(width, height int) Option
  • func WithoutSignalHandler() Option
• type Submit

Constants

const DefaultDrainTimeout = 3 * time.Second

DefaultDrainTimeout bounds the wait for an aborted run to write its end, unless WithDrainTimeout says otherwise.

Functions

func Run

func Run(ctx context.Context, rec client.Record, src client.Source, act client.Controller, opts ...Option) error

Run runs the terminal client over the session rec follows and the events src gives, sending what the user asks to act, until the user quits, ctx is done, or the program fails, and returns the program's error. ctx is the context of every intent; with client.Direct a run is under it.

rec must be one the client can follow and read. Run subscribes to src before it starts the program, so no event of the first run is missed. Run does not close anything it did not open. The agent, its store and its recorder are the caller's, and are safe to close once Run returns: the run that went has ended, as src reports, or the drain timeout passed.

A canceled ctx ends the program with an error, as bubbletea's WithContext does.

Types

type Line

type Line struct {
	// Text is what was typed, without the space around it.
	Text string
	// Running is whether a run was going when the line was taken up.
	Running bool
}

Line is a line the user submitted in the client's input.

type Option

type Option func(*config)

Option configures Run.

func WithCost

func WithCost(fn client.Cost) Option

WithCost prices one model call, showing the followed session's cost in the session pane. fn returns a call's cost in US dollars, and reports false for a model it has no price for.

func WithDrainTimeout

func WithDrainTimeout(d time.Duration) Option

WithDrainTimeout bounds how long Run waits, after the program ends, for a run it aborted to write its end. The default is DefaultDrainTimeout. Run waits twice: once for the abort to land, and once more after it cancels the context the run used as the last resort.

func WithInput

func WithInput(r io.Reader) Option

WithInput reads the terminal's input from r instead of the process's standard input. A reader that is not a terminal runs the program without raw mode, which is how a test drives it.

func WithOutput

func WithOutput(w io.Writer) Option

WithOutput renders to w instead of the process's standard output.

func WithSubmit

func WithSubmit(fn func(ctx context.Context, l Line) (Submit, error)) Option

WithSubmit hands each line the user submits to fn, which decides what it is: the program running the client owns its input, so a line can be a command to that program rather than anything the agent sees. fn runs off the program's goroutine, one line at a time in the order they were submitted; a line submitted meanwhile waits, shown over the input. An error fn returns is shown, and the line is given back to the input; so is a prompt while a run goes, which the agent would refuse. Without WithSubmit, a line is a prompt when no run goes and a steer while one does.

func WithToolRenderers

func WithToolRenderers(rs toolview.Renderers) Option

WithToolRenderers draws the calls of the tools named in rs with their renderers, live and from the record alike; a call to any other tool shows its name and its arguments as key=value pairs. A later call replaces the set.

func WithWarn

func WithWarn(fn func(string)) Option

WithWarn sends the one warning Run has, that a run did not end within the drain timeout and the session is closed as it is, to fn instead of to standard error.

func WithWindowSize

func WithWindowSize(width, height int) Option

WithWindowSize tells the program its terminal's size, as the terminal would, for a run whose input and output are not a terminal and report none (the program draws nothing until it knows its size). A terminal reports its own size and overrides it.

func WithoutSignalHandler

func WithoutSignalHandler() Option

WithoutSignalHandler leaves SIGINT and SIGTERM to the embedder. By default Run turns either into an interrupt of the client (the same as ctrl+c); without the handler the embedder's own handling applies, and the program ends only when the user quits or ctx is done.

type Submit

type Submit struct {
	Prompt   []openresponses.Item
	Steer    []openresponses.Item
	FollowUp []openresponses.Item
	Reply    string
}

Submit is what the client does with a submitted line. Prompt starts a run with its items; Steer queues its items into the run that goes, or the next one; FollowUp queues its items for when the run would stop, or the next one; Reply is shown over the input until the next line is submitted, and is not on the record. A reply may come with any one of a prompt, a steer and a follow-up; a Submit with more than one is refused, and an empty one does nothing.