backend

Documentation

Overview

Package backend defines the backend-neutral contracts between the router and concrete coding-agent adapters. It contains no backend implementations.

Index

• Constants
• func CompletedOperation(cwd string) <-chan Event
• func IsControlEvent(t string) bool
• func ParseSlashCommand(text string) (command, args string, ok bool)
• type Assembler
• type Backend
• type ComposerCatalog
• type ComposerItem
• type ComposerProvider
• type ErrorPayload
• type Event
• type Forker
• type Model
• type ModelProvider
• type MultiPartAssembler
• type PartDeltaPayload
• type ProcessStartedPayload
• type Renamer
• type Runtime
• type StartRequest
• type Transcript
• type TurnStatusPayload

Constants

const (
	EventProcessStarted = "subprocess.started"
	EventProcessExit    = "subprocess.exit"
	EventError          = "error"
	EventPartDelta      = "part.delta"
	EventTurnStatus     = "turn.status"
	EventRuntime        = "session.runtime"
	EventTurnUser       = "turn.user"
	EventPart           = "part"
)

Functions

func CompletedOperation

func CompletedOperation(cwd string) <-chan Event

CompletedOperation reports a local command that created no model turn.

func IsControlEvent

func IsControlEvent(t string) bool

IsControlEvent reports whether an event is an usher runtime signal rather than a persisted backend transcript record suitable for an Assembler.

func ParseSlashCommand

func ParseSlashCommand(text string) (command, args string, ok bool)

ParseSlashCommand splits a command token in column zero from its arguments. A double slash escapes command handling and remains ordinary prompt text.

The name must be non-empty and free of interior slashes. Backends namespace commands with ':' (codex:rescue, skill:brave-search) and never with '/', so a token like "/home/dev/x.go" is a pasted absolute path opening a prompt about a file — reading it as a command would reject the whole prompt as unknown.

Types

type Assembler

type Assembler interface {
	FeedLine(raw []byte) (completed []core.Turn, part *core.TurnPart)
	Flush() *core.Turn
	Model() string
}

Assembler projects one backend's persisted records into display turns.

type Backend

type Backend struct {
	Runtime    Runtime
	Transcript Transcript
	Forker     Forker
	Renamer    Renamer
	Models     ModelProvider
}

Backend explicitly composes the capabilities registered for one agent CLI. Main constructs these values; there is deliberately no global init registry.

type ComposerCatalog

type ComposerCatalog struct {
	Items     []ComposerItem
	Available bool
}

ComposerCatalog reports whether a backend could provide its authoritative catalog. Items must only be consumed when Available is true.

type ComposerItem

type ComposerItem struct {
	Name        string `json:"name"`
	Kind        string `json:"kind,omitempty"`
	Description string `json:"description,omitempty"`
}

ComposerItem is one completion advertised by a backend. Name is the bare command or skill identity; the frontend derives its / or $ sigil from the response source and Kind.

type ComposerProvider

type ComposerProvider interface {
	ComposerItems(context.Context, string, string) (ComposerCatalog, error)
}

ComposerProvider is an optional runtime capability for cwd-dependent completions. Available is false when discovery deliberately avoids starting a cold backend.

type ErrorPayload

type ErrorPayload struct {
	Message string `json:"message"`
}

type Event

type Event struct {
	Type string
	Raw  json.RawMessage
}

Event is one raw transcript record or synthesized runtime event emitted by a backend. Type identifies the stable usher event vocabulary below.

type Forker

type Forker interface {
	Fork(context.Context, string, string, string) (string, string, error)
}

Forker is an optional capability because backends use materially different branching mechanisms and some may not support it at all.

type Model

type Model struct {
	ID             string   `json:"id"`
	DisplayName    string   `json:"display_name,omitempty"`
	ThinkingLevels []string `json:"thinking_levels,omitempty"`
}

Model is the backend-neutral model-picker projection.

type ModelProvider

type ModelProvider interface {
	Models(context.Context) ([]Model, error)
	ValidateModel(context.Context, string) error
	DefaultEffort(context.Context, string) (string, error)
}

ModelProvider is an optional account-aware model catalog.

type MultiPartAssembler

type MultiPartAssembler interface {
	Assembler
	FeedLineParts(raw []byte) (completed []core.Turn, parts []*core.TurnPart)
}

MultiPartAssembler optionally exposes every display part stored in one record.

type PartDeltaPayload

type PartDeltaPayload struct {
	Delta string `json:"delta"`
}

type ProcessStartedPayload

type ProcessStartedPayload struct {
	Cwd   string `json:"cwd"`
	Fresh bool   `json:"fresh"`
}

Stable payloads for synthesized events. Persisted backend records remain raw because their schemas belong to the concrete transcript implementation.

type Renamer

type Renamer interface {
	Rename(context.Context, string, string, string) error
}

Renamer writes a title to backend-native metadata. path is the transcript.

type Runtime

type Runtime interface {
	Start(context.Context, StartRequest) (string, <-chan Event, error)
	Send(context.Context, string, string, string) (<-chan Event, error)
	Resume(context.Context, string, string) error
	Has(string) bool
	LiveSessions() []string
	Interrupt(string) error
	Kill(string) error
	Shutdown()
}

Runtime owns live workers for one coding-agent backend.

type StartRequest

type StartRequest struct {
	Cwd    string
	Prompt string
	Model  string
}

StartRequest describes the first turn of a new backend session.

type Transcript

type Transcript interface {
	ReadTurns(path string, limit int) ([]core.Turn, int, error)
	NewAssembler() Assembler
	IsTurnComplete(raw []byte) bool
	IsTurnAborted(raw []byte) bool
}

Transcript owns one backend's persisted session format.

type TurnStatusPayload

type TurnStatusPayload struct {
	Status string `json:"status"`
}