slash

Documentation

Overview

Package slash provides a slash command registry for intercepting and handling user messages before they enter the LLM inference pipeline.

The Registry implements junk.Interceptor and is wired into a junk.Manager via junk.WithInterceptor(). Commands are bound with Bind(name, description, handler) and matched when a UserMessageEvent content starts with "/<name>". Matched commands are consumed (no LLM processing); unmatched text passes through unchanged.

Index

• func Fields(input string) []string
• type Command
  • func NewCommandForTest(name, input string, stream *junk.Stream) Command
  • func (c Command) Stream() *junk.Stream
• type Handler
• type Registry
  • func NewRegistry() Registry
• type Result

Functions

func Fields

func Fields(input string) []string

Fields is a convenience helper that splits the raw command input on whitespace. Callers can bring their own parser (e.g. cobra, shlex) when custom argument parsing is needed.

Types

type Command

type Command struct {
	Name  string // e.g. "help" (no leading slash)
	Input string // everything after the command, raw and unmodified
	// contains filtered or unexported fields
}

Command represents a parsed slash command invocation.

func NewCommandForTest

func NewCommandForTest(name, input string, stream *junk.Stream) Command

NewCommandForTest builds a slash.Command with a populated stream field. It exists solely to let external test packages (e.g. x/tool/set_model) exercise handlers that depend on Command.Stream() without forcing the test to plumb a real junk.Manager through the registry's Intercept path.

This function is not part of the public API. External test code that uses it should accept that the signature may change in lockstep with the Command struct itself. The "ForTest" suffix is the convention to flag this.

Production code must never call this — the registry's Intercept is the only legitimate constructor of a non-nil Command.stream.

func (Command) Stream

func (c Command) Stream() *junk.Stream

Stream returns the junk.Stream that owns the in-flight event the slash command was parsed from. It is nil for Command values that were not produced by a junk.Interceptor (e.g. hand-constructed in tests). Handlers that mutate thread state via SetMetadata must check for nil before dereferencing.

type Handler

type Handler func(ctx context.Context, emitter loop.Emitter, cmd Command) (Result, error)

Handler is a slash command handler. It receives the parsed command and a loop.Emitter for signaling activity. It returns a Result and an error.

Error handling: a non-nil error from a handler is intercepted at the registry boundary and converted into a Notice{Severity: SeverityError} carrying the error's message. The error is also logged via slog.Debug for telemetry consumers. Intercept always returns nil in that case so conduits see the failure as a user-visible notice rather than having it silently dropped.

If a handler sets Result.Notice and also returns a non-nil error, the explicit Notice takes precedence — handlers can customise error presentation by populating Notice themselves.

type Registry

type Registry interface {
	Bind(name string, description string, handler Handler)
	Intercept(ctx context.Context, event junk.Event, stream *junk.Stream, emitter loop.Emitter) (junk.InterceptResult, error)
}

Registry is the slash command registry interface.

func NewRegistry

func NewRegistry() Registry

NewRegistry creates a new slash command registry with an auto-registered /help command that lists all bound commands and their descriptions.

type Result

type Result struct {
	Replace junk.Event  // nil = consume, non-nil = continue with this event
	Notice  loop.Notice // single ephemeral UI message, not persisted
}

Result is the return value from a slash command handler.

Notice carries an ephemeral, user-visible message that the slash interceptor emits as a loop.NoticeEvent. The Severity lets conduits pick a rendering style (Success, Info, Warn, Error). A zero-value Notice means "no notice to emit"; an empty Content is also skipped.