command

Documentation

Overview

Package command defines user-invoked local routing. Commands are distinct from model-callable tools and durable asynchronous tasks.

Index

• Constants
• Variables
• type Availability
  • func (a Availability) Format(state fmt.State, _ rune)
• type Descriptor
  • func (d Descriptor) Format(state fmt.State, _ rune)
• type Handler
• type Host
• type Invocation
  • func Parse(input string) (Invocation, bool)
  • func (i Invocation) Format(state fmt.State, _ rune)
• type Registry
  • func Builtins(host Host) (*Registry, error)
  • func New(descriptors []Descriptor) (*Registry, error)
  • func (r *Registry) Descriptors(includeHidden bool) []Descriptor
  • func (r *Registry) DescriptorsForSurface(includeHidden, nonInteractive bool) []Descriptor
  • func (r *Registry) Dispatch(ctx context.Context, invocation Invocation, fromModel bool) (Result, error)
  • func (r *Registry) DispatchNonInteractive(ctx context.Context, invocation Invocation, fromModel bool) (Result, error)
  • func (r *Registry) Format(state fmt.State, _ rune)
  • func (r *Registry) HelpText(includeHidden bool) string
• type Result
  • func (r Result) Format(state fmt.State, _ rune)
• type ResultKind
• type Source

Constants

const (
	SourceBuiltin Source     = "builtin"
	ResultLocal   ResultKind = "local"
	ResultPrompt  ResultKind = "prompt"
	ResultExit    ResultKind = "exit"
)

Variables

var (
	ErrUnknown           = errors.New("Unknown command")
	ErrSyntax            = errors.New("Commands are in the form `/command [args]`")
	ErrNonInteractive    = errors.New("command is unavailable in noninteractive mode")
	ErrUnavailable       = errors.New("command is unavailable")
	ErrExecution         = errors.New("command execution failed")
	ErrSource            = errors.New("command is not invocable from this source")
	ErrInvalidDescriptor = errors.New("invalid command descriptor")
	ErrDuplicate         = errors.New("duplicate command name")
)

Types

type Availability

type Availability struct {
	Available bool
	Reason    string
}

func (Availability) Format

func (a Availability) Format(state fmt.State, _ rune)

Format keeps accidental logging and debug formatting from becoming a second command-output surface. Structured consumers should select deliberate fields.

type Descriptor

type Descriptor struct {
	Name                   string
	Aliases                []string
	Description            string
	ArgumentHint           string
	Source                 Source
	Hidden                 bool
	Sensitive              bool
	UserInvocable          bool
	ModelInvocable         bool
	SupportsNonInteractive bool
	RemoteSafe             bool
	Availability           func() Availability
	Handler                Handler
}

func (Descriptor) Format

func (d Descriptor) Format(state fmt.State, _ rune)

Format omits descriptor text and callback identities, either of which may originate in an extension or contain sensitive configuration.

type Handler

type Handler func(context.Context, Invocation) (Result, error)

type Host

type Host interface {
	RunLocalCommand(context.Context, string, []string, string) (Result, error)
}

type Invocation

type Invocation struct {
	Name         string
	Raw          string
	RawArguments string
	Arguments    []string
	HistoryForm  string
	RedactedForm string
}

func Parse

func Parse(input string) (Invocation, bool)

Parse distinguishes a syntactically valid slash command from ordinary model text. Absolute paths and malformed command-like input remain model prompts.

func (Invocation) Format

func (i Invocation) Format(state fmt.State, _ rune)

Format never emits raw command input. RedactedForm remains available as an explicit field for presentation code that has selected that contract.

type Registry

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

func Builtins

func Builtins(host Host) (*Registry, error)

Builtins returns the observable command catalog. A host may report a feature-gated operation as unavailable, but descriptors are not silently omitted simply because an optional service is absent.

func New

func New(descriptors []Descriptor) (*Registry, error)

func (*Registry) Descriptors

func (r *Registry) Descriptors(includeHidden bool) []Descriptor

func (*Registry) DescriptorsForSurface

func (r *Registry) DescriptorsForSurface(includeHidden, nonInteractive bool) []Descriptor

DescriptorsForSurface returns the descriptors that are safe to advertise on the selected surface. Headless and SDK clients must not discover commands that dispatch will later reject as terminal-UI-only operations.

func (*Registry) Dispatch

func (r *Registry) Dispatch(ctx context.Context, invocation Invocation, fromModel bool) (Result, error)

func (*Registry) DispatchNonInteractive

func (r *Registry) DispatchNonInteractive(ctx context.Context, invocation Invocation, fromModel bool) (Result, error)

DispatchNonInteractive enforces the descriptor-owned headless eligibility decision before loading or invoking the command handler.

func (*Registry) Format

func (r *Registry) Format(state fmt.State, _ rune)

Format omits the registry's descriptor callbacks and text.

func (*Registry) HelpText

func (r *Registry) HelpText(includeHidden bool) string

HelpText renders the current interactive command catalog from the same descriptors used for dispatch, so documented names, hints, aliases, and descriptions cannot drift into a separate hand-maintained list.

type Result

type Result struct {
	Kind   ResultKind
	Output string
	Prompt string
}

func (Result) Format

func (r Result) Format(state fmt.State, _ rune)

Format reports shape only; Output and Prompt are deliberate result channels and must not also escape through incidental debug formatting.

type ResultKind

type ResultKind string

type Source

type Source string