frontend

package
v0.1.0-p8a.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package frontend defines the transport-neutral projection consumed by coding frontends. It is deliberately separate from both the agent runtime and any terminal framework.

Index

Constants

View Source 
const ProtocolVersion = "mintclaw.coding.frontend.v1"

Variables

View Source 
var (
	ErrRevisionGap         = errors.New("coding frontend revision gap")
	ErrRevisionUnavailable = errors.New("coding frontend revision is no longer available")
	ErrThreadMismatch      = errors.New("coding frontend thread mismatch")
)

Functions

This section is empty.

Types

type Activity 

type Activity string
const (
	ActivityIdle         Activity = "idle"
	ActivityRunning      Activity = "running"
	ActivityInterrupting Activity = "interrupting"
	ActivityCompacting   Activity = "compacting"
	ActivityFailed       Activity = "failed"
)

type CommandSink 

type CommandSink interface {
	Submit(context.Context, string) error
	Interrupt(context.Context) error
	HardCancel(context.Context) error
	Compact(context.Context) error
	Rename(context.Context, string) error
	NewThread(context.Context) error
	Close(context.Context) error
}

CommandSink is the write side of the frontend controller boundary. Runtime implementations own turn and persistence semantics; a TUI never calls agent internals directly.

type ContextUsage 

type ContextUsage struct {
	UsedTokens  int `json:"used_tokens,omitempty"`
	LimitTokens int `json:"limit_tokens,omitempty"`
}

type Controller 

type Controller interface {
	SnapshotSource
	CommandSink
}

type Delta 

type Delta struct {
	ProtocolVersion  string           `json:"protocol_version"`
	ThreadID         string           `json:"thread_id"`
	PreviousRevision Revision         `json:"previous_revision"`
	Revision         Revision         `json:"revision"`
	Kind             DeltaKind        `json:"kind"`
	Entry            *TranscriptEntry `json:"entry,omitempty"`
	Tool             *ToolState       `json:"tool,omitempty"`
	ContextUsage     *ContextUsage    `json:"context_usage,omitempty"`
	Activity         Activity         `json:"activity,omitempty"`
	Status           string           `json:"status,omitempty"`
	RequiresSnapshot bool             `json:"requires_snapshot,omitempty"`
}

Delta contains a complete bounded replacement for the entity it changes. PreviousRevision makes missing or reordered progress detectable.

type DeltaKind 

type DeltaKind string
const (
	DeltaThreadOpened       DeltaKind = "thread_opened"
	DeltaThreadResumed      DeltaKind = "thread_resumed"
	DeltaTurnStarted        DeltaKind = "turn_started"
	DeltaAssistant          DeltaKind = "assistant_delta"
	DeltaReasoning          DeltaKind = "reasoning_delta"
	DeltaToolStarted        DeltaKind = "tool_started"
	DeltaToolOutput         DeltaKind = "tool_output"
	DeltaToolCompleted      DeltaKind = "tool_completed"
	DeltaContextUsage       DeltaKind = "context_usage_updated"
	DeltaCompactionStarted  DeltaKind = "compaction_started"
	DeltaCompactionComplete DeltaKind = "compaction_completed"
	DeltaCompactionFailed   DeltaKind = "compaction_failed"
	DeltaTurnCompleted      DeltaKind = "turn_completed"
	DeltaTurnFailed         DeltaKind = "turn_failed"
	DeltaInterruptRequested DeltaKind = "interrupt_requested"
	DeltaTurnInterrupted    DeltaKind = "turn_interrupted"
)

type EntryKind 

type EntryKind string
const (
	EntryUser      EntryKind = "user"
	EntryAssistant EntryKind = "assistant"
	EntryReasoning EntryKind = "reasoning"
	EntryWarning   EntryKind = "warning"
	EntryError     EntryKind = "error"
)

type ProjectionLimits 

type ProjectionLimits struct {
	Entries   int
	Tools     int
	Deltas    int
	TextBytes int
}

type Projector 

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

Projector owns a bounded UI projection. Canonical transcript and tool audit persistence remain outside this type.

func NewProjector 

func NewProjector(threadID string, limits ProjectionLimits) (*Projector, error)

func (*Projector) AssistantAccumulated 

func (p *Projector) AssistantAccumulated(turnID, content string, complete bool) Delta

func (*Projector) ChangesSince 

func (p *Projector) ChangesSince(ctx context.Context, revision Revision) ([]Delta, error)

func (*Projector) CompactionCompleted 

func (p *Projector) CompactionCompleted(status string) Delta

func (*Projector) CompactionFailed 

func (p *Projector) CompactionFailed(status string) Delta

func (*Projector) CompactionStarted 

func (p *Projector) CompactionStarted() Delta

func (*Projector) ContextUsage 

func (p *Projector) ContextUsage(used, limit int) Delta

func (*Projector) InterruptRequested 

func (p *Projector) InterruptRequested() Delta

func (*Projector) Open 

func (p *Projector) Open(resumed bool) Delta

func (*Projector) ReasoningAccumulated 

func (p *Projector) ReasoningAccumulated(turnID, content string, complete bool) Delta

func (*Projector) Snapshot 

func (p *Projector) Snapshot(ctx context.Context) (ThreadSnapshot, error)

func (*Projector) ToolCompleted 

func (p *Projector) ToolCompleted(callID, name, output string, duration time.Duration, failed bool) Delta

func (*Projector) ToolOutput 

func (p *Projector) ToolOutput(callID, output string) Delta

func (*Projector) ToolStarted 

func (p *Projector) ToolStarted(callID, name, arguments string) Delta

func (*Projector) TurnCompleted 

func (p *Projector) TurnCompleted(status string) Delta

func (*Projector) TurnFailed 

func (p *Projector) TurnFailed(status string) Delta

func (*Projector) TurnInterrupted 

func (p *Projector) TurnInterrupted(status string) Delta

func (*Projector) TurnStarted 

func (p *Projector) TurnStarted(turnID, userMessage string) Delta

func (*Projector) Watch 

func (p *Projector) Watch(ctx context.Context, revision Revision) (<-chan Delta, error)

Watch atomically queues retained changes after revision and then publishes live deltas. Delivery is bounded and non-blocking: a slow consumer detects a revision gap and resynchronizes from Snapshot instead of blocking a turn.

type Reducer 

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

Reducer is frontend-local state. It can recover only through SnapshotSource, which keeps runtime internals out of terminal models and future IPC clients.

func NewReducer 

func NewReducer(snapshot ThreadSnapshot) (*Reducer, error)

func (*Reducer) Apply 

func (r *Reducer) Apply(delta Delta) error

func (*Reducer) ApplyOrResync 

func (r *Reducer) ApplyOrResync(ctx context.Context, source SnapshotSource, delta Delta) error

ApplyOrResync applies a live delta. A gap or explicit bounded-window reset is recovered from an authoritative snapshot without consulting runtime state.

func (*Reducer) ApplySnapshot 

func (r *Reducer) ApplySnapshot(snapshot ThreadSnapshot) error

func (*Reducer) CatchUp 

func (r *Reducer) CatchUp(ctx context.Context, source SnapshotSource) error

CatchUp applies the retained bounded delta window and falls back to a fresh snapshot when the requested revision has already fallen out of that window.

func (*Reducer) State 

func (r *Reducer) State() ThreadSnapshot

type Revision 

type Revision uint64

type SnapshotSource 

type SnapshotSource interface {
	Snapshot(context.Context) (ThreadSnapshot, error)
	ChangesSince(context.Context, Revision) ([]Delta, error)
	Watch(context.Context, Revision) (<-chan Delta, error)
}

SnapshotSource is the read side of the frontend controller boundary. ChangesSince returns ErrRevisionUnavailable when its bounded delta window no longer covers the requested revision; callers must then request Snapshot.

type StreamDelegate 

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

StreamDelegate projects the existing accumulated-content streaming seam. It does not alter provider or turn behavior and can be installed on the dedicated coding message bus by the future coding runtime.

func NewStreamDelegate 

func NewStreamDelegate(projector *Projector, threadID string) *StreamDelegate

func (*StreamDelegate) GetStreamer 

func (d *StreamDelegate) GetStreamer(
	_ context.Context,
	_, _, sessionKey, _ string,
	traceScope runtimeevents.TraceScope,
) (bus.Streamer, bool)

type ThreadSnapshot 

type ThreadSnapshot struct {
	ProtocolVersion string            `json:"protocol_version"`
	ThreadID        string            `json:"thread_id"`
	Revision        Revision          `json:"revision"`
	Activity        Activity          `json:"activity"`
	Entries         []TranscriptEntry `json:"entries,omitempty"`
	Tools           []ToolState       `json:"tools,omitempty"`
	ContextUsage    ContextUsage      `json:"context_usage,omitempty"`
	Status          string            `json:"status,omitempty"`
	HasOlderEntries bool              `json:"has_older_entries,omitempty"`
}

ThreadSnapshot is the authoritative, bounded frontend projection. It is not the canonical coding transcript and may omit old entries and large output.

type ToolState 

type ToolState struct {
	CallID          string        `json:"call_id"`
	Name            string        `json:"name"`
	Arguments       string        `json:"arguments,omitempty"`
	Output          string        `json:"output,omitempty"`
	Status          ToolStatus    `json:"status"`
	Duration        time.Duration `json:"duration,omitempty"`
	OutputTruncated bool          `json:"output_truncated,omitempty"`
}

type ToolStatus 

type ToolStatus string
const (
	ToolRunning     ToolStatus = "running"
	ToolSucceeded   ToolStatus = "succeeded"
	ToolFailed      ToolStatus = "failed"
	ToolInterrupted ToolStatus = "interrupted"
	ToolUnknown     ToolStatus = "unknown"
)

type TranscriptEntry 

type TranscriptEntry struct {
	ID        string    `json:"id"`
	TurnID    string    `json:"turn_id"`
	Kind      EntryKind `json:"kind"`
	Text      string    `json:"text"`
	Complete  bool      `json:"complete"`
	Truncated bool      `json:"truncated,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package agentadapter projects stable observations from the shared agent runtime into the coding frontend protocol.
 Package agentadapter projects stable observations from the shared agent runtime into the coding frontend protocol.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.