ports

type Block ¶

type Block struct {
	Kind BlockKind

	// BlockText
	Text string

	// BlockToolCall
	ToolCallID string
	ToolName   string
	ToolInput  []byte // raw JSON args, accumulated from streamed deltas

	// BlockToolResult
	ToolResultForID string
	ToolResultText  string
	ToolResultError bool

	// BlockImage
	ImageMIME string
	ImageData []byte
}

Block is one neutral unit of message content.

type BlockKind ¶

type BlockKind int

BlockKind identifies the kind of content carried by a Block.

const (
	BlockText BlockKind = iota
	BlockToolCall
	BlockToolResult
	BlockThinking
	BlockImage
)

type Budgeter ¶

type Budgeter interface {
	Fit(budget int, msgs []Message) []Message
}

Budgeter decides what fits in the context window (ADR-0008).

type Checkpointer ¶

type Checkpointer interface {
	ShouldCheckpoint(used int) bool
	Save(state string) error
	Load() (string, error)
}

Checkpointer snapshots and restores session state (ADR-0008).

type Diagnostic ¶

type Diagnostic struct {
	Path     string // file the problem is in, relative to the project root
	Line     int    // 1-based
	Column   int    // 1-based
	Severity Severity
	Message  string
	Source   string // which tool produced it ("compiler", "vet", …); may be empty
}

Diagnostic is one problem reported in a file: a compiler error, a vet warning, a linter hint.

type Embedder ¶

type Embedder interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
	Dim() int
}

Embedder turns text into vectors (ADR-0004).

type Event ¶

type Event struct {
	Kind  EventKind
	Text  string
	Call  *ToolCall
	Usage *Usage
	Err   error
}

Event is one streamed unit from a Provider. TextDelta carries Text; ToolCallStart/ToolArgsDelta carry partial tool-call state the adapter accumulates internally, surfaced to the caller only as a completed ToolCall on the turn's TurnEnd event (see Turn.ToolCalls in loop.go).

type EventKind ¶

type EventKind int

EventKind identifies the kind of a streamed Event.

const (
	EventTextDelta EventKind = iota
	EventToolCallStart
	EventToolArgsDelta
	EventTurnEnd
	EventUsage
	EventError
	EventThinkingDelta
)

type FakeBudgeter ¶

type FakeBudgeter struct{}

FakeBudgeter passes every message through.

func (FakeBudgeter) Fit(_ int, msgs []Message) []Message

type FakeCheckpointer ¶

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

FakeCheckpointer stores one state string in memory and never asks to checkpoint.

func (c *FakeCheckpointer) Load() (string, error)

func (c *FakeCheckpointer) Save(state string) error

func (*FakeCheckpointer) ShouldCheckpoint(int) bool

type FakeEmbedder ¶

type FakeEmbedder struct {
	Dimension int
}

FakeEmbedder returns deterministic vectors of a fixed dimension.

func (f FakeEmbedder) Dim() int

func (f FakeEmbedder) Embed(_ context.Context, texts []string) ([][]float32, error)

type FakeLanguageService ¶

type FakeLanguageService struct {
	Diags     []Diagnostic
	HoverText string
	Locs      []Location
	Syms      []Symbol
}

FakeLanguageService returns canned answers. It lets tests exercise LSP-dependent code without spawning a language server.

func (f FakeLanguageService) Definition(context.Context, string, int, int) ([]Location, error)

func (f FakeLanguageService) Diagnostics(context.Context, string) ([]Diagnostic, error)

func (f FakeLanguageService) DocumentSymbols(context.Context, string) ([]Symbol, error)

func (f FakeLanguageService) Hover(context.Context, string, int, int) (string, error)

func (f FakeLanguageService) References(context.Context, string, int, int) ([]Location, error)

func (f FakeLanguageService) Shutdown(context.Context) error

type FakeMemoryStore ¶

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

FakeMemoryStore is an in-memory substring-matching store.

func (m *FakeMemoryStore) Search(_ context.Context, query string, k int) ([]string, error)

func (m *FakeMemoryStore) Write(_ context.Context, text, _ string) (int64, error)

type FakePolicyGate ¶

type FakePolicyGate struct {
	DenyAll bool
}

FakePolicyGate allows everything unless DenyAll is set.

func (f FakePolicyGate) Permit(context.Context, ToolCall) (bool, error)

type FakeProvider ¶

type FakeProvider struct{}

FakeProvider streams a single TurnEnd.

func (FakeProvider) Stream(ctx context.Context, _ Request) (<-chan Event, error)

type FakeSkillIndex ¶

type FakeSkillIndex struct {
	Names []string
}

FakeSkillIndex matches skills by substring.

func (f FakeSkillIndex) Find(name string) (string, bool)

func (f FakeSkillIndex) Rank(query string, k int) []string

type FakeTokenizer ¶

type FakeTokenizer struct{}

FakeTokenizer counts whitespace-separated words.

func (FakeTokenizer) Count(text string) int

type FakeTool ¶

type FakeTool struct {
	ToolName string
	Result   string
}

FakeTool returns a canned result.

func (f FakeTool) Description() string

func (f FakeTool) Execute(context.Context, json.RawMessage) (string, error)

func (f FakeTool) Name() string

func (f FakeTool) Schema() json.RawMessage

type FakeWorkflow ¶

type FakeWorkflow struct {
	PhaseNames []string
}

FakeWorkflow reports named phases and honors cancellation.

func (f FakeWorkflow) Phases() []string

func (f FakeWorkflow) Run(ctx context.Context) error

type LanguageService ¶

type LanguageService interface {
	// Diagnostics reports the current problems in one file. It returns the
	// latest known set; an implementation backed by a push-notification
	// protocol serves what the server last published.
	Diagnostics(ctx context.Context, path string) ([]Diagnostic, error)

	// Hover describes the symbol at a position — typically its signature and
	// doc comment, rendered as text.
	Hover(ctx context.Context, path string, line, col int) (string, error)

	// Definition locates where the symbol at a position is defined.
	Definition(ctx context.Context, path string, line, col int) ([]Location, error)

	// DocumentSymbols lists the symbols declared in one file.
	DocumentSymbols(ctx context.Context, path string) ([]Symbol, error)

	// References finds the uses of the symbol at a position.
	References(ctx context.Context, path string, line, col int) ([]Location, error)

	// Shutdown stops every language server this service started. It is
	// idempotent so a deferred call after an error path is safe.
	Shutdown(ctx context.Context) error
}

LanguageService is the code-intelligence seam (ADR-0017, change 0026): the eleventh port. It answers read-only questions about source code — what is broken, what a symbol means, where it is defined, and who uses it.

Every surface is read-only. Mutating surfaces (code actions, rename, apply-edit) are deliberately absent: they need a gating story of their own.

Neutrality rule (hard rule, ADR-0017): no LSP wire type may appear in this interface or in any type it returns. The concrete adapter in internal/lsp/ converts protocol values to the neutral types below at its boundary, exactly as internal/provider converts provider wire types to the neutral model. The regression guard internal/ports/lsp_leak_guard_test.go fails the build if a go.lsp.dev type reaches this package.

Positions are 1-based line and column numbers — what a human reads in an editor and what a compiler prints. The adapter converts from LSP's 0-based UTF-16 positions.

type Location ¶

type Location struct {
	Path   string // relative to the project root
	Line   int    // 1-based
	Column int    // 1-based
}

Location points at a span of source — where something is defined, or one place it is used.

type MemoryStore ¶

type MemoryStore interface {
	Write(ctx context.Context, text, source string) (int64, error)
	Search(ctx context.Context, query string, k int) ([]string, error)
}

MemoryStore persists and retrieves memory chunks (ADR-0003).

type Message ¶

type Message struct {
	Role   Role
	Blocks []Block
}

Message is one neutral turn in the conversation.

type PolicyGate ¶

type PolicyGate interface {
	Permit(ctx context.Context, call ToolCall) (bool, error)
}

PolicyGate authorizes tool calls (ADR-0007).

type Provider ¶

type Provider interface {
	// Stream sends req and returns a channel of Events. The channel is
	// closed when the turn ends (after an EventTurnEnd) or ctx is done.
	Stream(ctx context.Context, req Request) (<-chan Event, error)
}

Provider is the single port the agent loop depends on. Every model backend — Anthropic, OpenAI-compatible, or a test fake — implements this.

type Request ¶

type Request struct {
	Model    string // "<provider>/<model>", e.g. "anthropic/claude-…" or "local/qwen2.5-coder"
	System   string
	Messages []Message
	Tools    []ToolSchema
	Thinking bool
}

Request is a provider-neutral request for one turn.

type Role ¶

type Role string

Role is the neutral message role.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type Severity ¶

type Severity int

Severity ranks a diagnostic. The zero value is SeverityError, so a diagnostic that loses its severity in translation is surfaced rather than silently demoted to a hint.

const (
	SeverityError Severity = iota
	SeverityWarning
	SeverityInformation
	SeverityHint
)

func (s Severity) String() string

type SkillIndex ¶

type SkillIndex interface {
	Rank(query string, k int) []string
	Find(name string) (string, bool)
}

SkillIndex discovers and ranks skills (ADR-0002).

type Symbol ¶

type Symbol struct {
	Name string
	Kind string // "func", "type", "var", … (the adapter maps LSP's numeric kinds)
	Path string
	Line int // 1-based
}

Symbol is one declaration in a file.

type Tokenizer ¶

type Tokenizer interface {
	Count(text string) int
}

Tokenizer estimates token cost (ADR-0008).

type Tool ¶

type Tool interface {
	Name() string
	Description() string
	Schema() json.RawMessage
	Execute(ctx context.Context, input json.RawMessage) (string, error)
}

Tool is one callable capability exposed to the model.

type ToolCall ¶

type ToolCall struct {
	ID    string
	Name  string
	Input []byte // fully accumulated JSON args
}

ToolCall is a completed, neutral tool call parsed from a provider stream.

type ToolSchema ¶

type ToolSchema struct {
	Name        string
	Description string
	InputSchema []byte // raw JSON Schema
}

ToolSchema describes a tool the model may call, in neutral form. Each adapter maps this to its native shape (Anthropic input_schema, OpenAI-compatible function.parameters).

type Usage ¶

type Usage struct {
	InputTokens  int
	OutputTokens int
}

Usage is neutral token accounting.

type Workflow ¶

type Workflow interface {
	Phases() []string
	Run(ctx context.Context) error
}

Workflow runs an ordered set of phases (ADR-0006).