shell

Documentation

Index

• func ToolSummary(toolName string, args map[string]any) string
• func TruncateRunes(s string, max int) string
• type CommandDesc
• type Config
• type Notification
• type NotificationKind
• type QueueMode
• type Response
• type ResponseKind
• type Shell
  • func New(ctx context.Context, cfg Config) *Shell
  • func (s *Shell) Abort()
  • func (s *Shell) AbortWithMarker(reason string)
  • func (s *Shell) Agent() *core.Agent
  • func (s *Shell) App() *ext.App
  • func (s *Shell) BackgroundTasks() []string
  • func (s *Shell) BgEventChannel() <-chan core.Event
  • func (s *Shell) BgEventChannels() map[string]<-chan core.Event
  • func (s *Shell) CommandInfos() []CommandDesc
  • func (s *Shell) Commands() map[string]*ext.Command
  • func (s *Shell) DrainActions()
  • func (s *Shell) EnqueueResult(action ext.Action)
  • func (s *Shell) EventChannel() <-chan core.Event
  • func (s *Shell) IsRunning() bool
  • func (s *Shell) Messages() []core.Message
  • func (s *Shell) Notifications() []Notification
  • func (s *Shell) ProcessBgEvent(name string, evt core.Event) (done bool)
  • func (s *Shell) ProcessEvent(evt core.Event) (done bool)
  • func (s *Shell) QueueMode() QueueMode
  • func (s *Shell) QueueSize() int
  • func (s *Shell) Quitting() bool
  • func (s *Shell) Session() *session.Session
  • func (s *Shell) SetAgent(agent *core.Agent, opts ...ext.BindOption)
  • func (s *Shell) SetQueueMode(mode QueueMode)
  • func (s *Shell) SetSession(sess *session.Session)
  • func (s *Shell) StartBackgroundNamed(name, prompt string) error
  • func (s *Shell) Steer(content string) ext.SteerDisposition
  • func (s *Shell) StopBackground()
  • func (s *Shell) StopBackgroundNamed(name string)
  • func (s *Shell) Submit(input string) Response
  • func (s *Shell) SubmitWithImage(input string, img *core.ImageContent) Response

Functions

func ToolSummary

func ToolSummary(toolName string, args map[string]any) string

ToolSummary returns a concise display string for a tool call. Format: "toolname: detail" or just "toolname" if no meaningful detail.

func TruncateRunes

func TruncateRunes(s string, max int) string

TruncateRunes truncates s to max runes, appending "…" (U+2026) if truncated.

Types

type CommandDesc

type CommandDesc struct {
	Name        string
	Description string
}

CommandDesc holds a command name and its one-line description for autocomplete.

type Config

type Config struct {
	App      *ext.App
	Agent    *core.Agent      // may be nil (deferred setup)
	Session  *session.Session // may be nil (persistence disabled)
	Settings *config.Settings
}

Config holds everything Shell needs to start.

type Notification

type Notification struct {
	Kind   NotificationKind
	Text   string     // for Message, Warn, Error, SessionTitle
	Key    string     // for Status, Widget, Overlay
	Action ext.Action // raw action for rich frontends (may be nil)
}

Notification is a frontend-relevant side-effect from Shell processing. Simple frontends switch on Kind and use Text/Key. Rich frontends (TUI) type-assert Action for full details.

type NotificationKind

type NotificationKind int

NotificationKind discriminates notification types.

const (
	NotifyMessage      NotificationKind = iota // text message to display
	NotifyWarn                                 // warning-level message
	NotifyError                                // error-level message
	NotifyStatus                               // status bar update (key + text)
	NotifySessionSwap                          // session was swapped
	NotifyQuit                                 // frontend should exit
	NotifyPicker                               // modal picker request
	NotifyImage                                // image attach/detach
	NotifyWidget                               // widget set/clear
	NotifyOverlay                              // overlay show/close
	NotifyExec                                 // hand terminal to external process
	NotifySendMessage                          // content should be submitted as user input
	NotifySessionTitle                         // session title changed
	NotifyClearDisplay                         // frontend should clear conversation display
	NotifyQueuedSubmit                         // queued user message was submitted to agent
	NotifyMouseMode                            // TUI mouse capture toggled
	NotifySetInputText                         // prefill editor text
	NotifyAskUser                              // blocking ask-user dialog
)

type QueueMode

type QueueMode int

QueueMode controls how the shell drains its input queue on EventAgentEnd.

const (
	// QueueDrainAll processes all queued items at once, merging prompts
	// into a single turn. This is the default.
	QueueDrainAll QueueMode = iota

	// QueueSingleStep processes one item from the queue per agent turn.
	// Remaining items stay queued for the next EventAgentEnd.
	QueueSingleStep
)

type Response

type Response struct {
	Kind   ResponseKind
	Events <-chan core.Event // non-nil only when Kind == ResponseAgentStarted
	Error  error             // non-nil only when Kind == ResponseError
}

Response is returned by Submit.

type ResponseKind

type ResponseKind int

ResponseKind discriminates what Submit produced.

const (
	// ResponseAgentStarted — agent loop started. Consume Response.Events.
	ResponseAgentStarted ResponseKind = iota

	// ResponseQueued — input was queued because agent is already running.
	ResponseQueued

	// ResponseCommand — slash command executed synchronously.
	ResponseCommand

	// ResponseHandled — input transformer consumed the input entirely.
	ResponseHandled

	// ResponseNotReady — agent not yet available (deferred setup).
	ResponseNotReady

	// ResponseError — something failed before the agent could start.
	ResponseError
)

type Shell

type Shell struct {
	// contains filtered or unexported fields
}

Shell manages the agent lifecycle on behalf of any frontend. It is a concrete struct — adding methods is non-breaking for all consumers.

func New

func New(ctx context.Context, cfg Config) *Shell

New creates a Shell. The agent may be nil and set later via SetAgent.

func (*Shell) Abort

func (s *Shell) Abort()

Abort cancels the current agent run without blocking. The agent goroutine finishes asynchronously and emits EventAgentEnd, which the frontend uses to transition out of the streaming state. No marker is inserted — the LLM does not see the interruption.

func (*Shell) AbortWithMarker

func (s *Shell) AbortWithMarker(reason string)

AbortWithMarker cancels the current agent run and persists a marker message to the session so the LLM sees the interruption context on the next run. Use for programmatic cancellations (e.g. plan-mode transitions) where the model needs to know the prior run was interrupted.

func (*Shell) Agent

func (s *Shell) Agent() *core.Agent

Agent returns the current agent, or nil if not yet set.

func (*Shell) App

func (s *Shell) App() *ext.App

App returns the ext.App.

func (*Shell) BackgroundTasks

func (s *Shell) BackgroundTasks() []string

BackgroundTasks returns the names of all active background tasks.

func (*Shell) BgEventChannel

func (s *Shell) BgEventChannel() <-chan core.Event

BgEventChannel returns the first active background task's event channel, or nil. Kept for backward compatibility with frontends that handle only one bg task.

func (*Shell) BgEventChannels

func (s *Shell) BgEventChannels() map[string]<-chan core.Event

BgEventChannels returns all active background task event channels keyed by name.

func (*Shell) CommandInfos

func (s *Shell) CommandInfos() []CommandDesc

CommandInfos returns a sorted list of registered commands with their descriptions.

func (*Shell) Commands

func (s *Shell) Commands() map[string]*ext.Command

Commands returns all registered slash commands.

func (*Shell) DrainActions

func (s *Shell) DrainActions()

DrainActions processes pending ext.App actions. Public for cases where frontends trigger actions outside the normal event flow (shortcuts, modal callbacks, async action results).

func (*Shell) EnqueueResult

func (s *Shell) EnqueueResult(action ext.Action)

EnqueueResult re-enqueues an action result from an async execution. Used by frontends that run ActionRunAsync outside ProcessEvent.

func (*Shell) EventChannel

func (s *Shell) EventChannel() <-chan core.Event

EventChannel returns the current main agent event channel, or nil. Used by frontends to detect when ProcessEvent restarted the agent.

func (*Shell) IsRunning

func (s *Shell) IsRunning() bool

IsRunning returns true if an agent loop is currently active.

func (*Shell) Messages

func (s *Shell) Messages() []core.Message

Messages returns the conversation history snapshot.

func (*Shell) Notifications

func (s *Shell) Notifications() []Notification

Notifications returns and clears all pending notifications. Call after each ProcessEvent or Submit.

func (*Shell) ProcessBgEvent

func (s *Shell) ProcessBgEvent(name string, evt core.Event) (done bool)

ProcessBgEvent handles one background agent event for the given task name.

func (*Shell) ProcessEvent

func (s *Shell) ProcessEvent(evt core.Event) (done bool)

ProcessEvent handles one agent event. The frontend calls this for each event received from the Response.Events channel.

Shell performs: event dispatch, session persistence, action drain, queue drain on EventAgentEnd, steering on EventToolEnd.

Returns true if the agent run is complete (EventAgentEnd received and no queued input restarted it).

func (*Shell) QueueMode

func (s *Shell) QueueMode() QueueMode

QueueMode returns the current queue processing mode.

func (*Shell) QueueSize

func (s *Shell) QueueSize() int

QueueSize returns the number of pending queued inputs.

func (*Shell) Quitting

func (s *Shell) Quitting() bool

Quitting returns true if a quit action was processed.

func (*Shell) Session

func (s *Shell) Session() *session.Session

Session returns the current session, or nil.

func (*Shell) SetAgent

func (s *Shell) SetAgent(agent *core.Agent, opts ...ext.BindOption)

SetAgent wires the agent after deferred setup completes. Calls ext.App.Bind internally with background agent callbacks.

func (*Shell) SetQueueMode

func (s *Shell) SetQueueMode(mode QueueMode)

SetQueueMode switches between DrainAll and SingleStep queue processing.

func (*Shell) SetSession

func (s *Shell) SetSession(sess *session.Session)

SetSession swaps the active session. Used when ActionSwapSession is handled externally (by a frontend that needs to update display state).

func (*Shell) StartBackgroundNamed

func (s *Shell) StartBackgroundNamed(name, prompt string) error

StartBackgroundNamed starts a named background agent with the given prompt.

func (*Shell) Steer

func (s *Shell) Steer(content string) ext.SteerDisposition

Steer injects a steering message into the running agent turn. Returns the disposition: delivered (active run), queued (idle), or dropped (no agent).

func (*Shell) StopBackground

func (s *Shell) StopBackground()

StopBackground cancels all running background tasks.

func (*Shell) StopBackgroundNamed

func (s *Shell) StopBackgroundNamed(name string)

StopBackgroundNamed cancels a specific named background task.

func (*Shell) Submit

func (s *Shell) Submit(input string) Response

Submit processes user input. It handles:

• Slash command dispatch (returns ResponseCommand)
• Input transformer pipeline
• Message hook execution
• Session persistence of user message
• Agent start (returns ResponseAgentStarted with event channel)
• Queueing if agent is already running (returns ResponseQueued)
• Agent-not-ready guard (returns ResponseNotReady)

func (*Shell) SubmitWithImage

func (s *Shell) SubmitWithImage(input string, img *core.ImageContent) Response

SubmitWithImage is like Submit but attaches an image to the user message.