client

package
v0.1.0-preview.7 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package client defines the transport-neutral public contract used by Spice Agent clients and distribution adapters.

The package deliberately contains no transport, daemon discovery, protocol, kernel, or presentation implementation. A Connector owns authentication and transport details outside these values, negotiates one Session, and translates its remote representation into the immutable types in this package.

Session implementations must enforce stable-client ownership and must reject stale epochs. Event streams replay strictly after the supplied acknowledged Cursor and then remain sequence-contiguous. Interaction streams deliver one complete snapshot before revision-contiguous changes. Successful stream controls remain explicit frames rather than being inferred from end-of-stream. Callers own every context supplied to remote operations and decide when an event is durable enough to acknowledge. Close methods are local, context-free, nonblocking, and idempotent.

Index

Constants

View Source 
const (
	// MaximumTextBytes bounds user-visible text crossing the client boundary.
	MaximumTextBytes = 1 << 20
	// MaximumSnapshotPayloadBytes is the maximum safe kernel snapshot payload.
	MaximumSnapshotPayloadBytes = 16 << 20
	// MaximumSnapshotEnvelopeOverheadBytes is the exact deterministic Protobuf
	// overhead for the current maximum-width engine/v1 signed envelope shape.
	MaximumSnapshotEnvelopeOverheadBytes = 295
	// MaximumSnapshotEnvelopeBytes bounds one complete opaque signed snapshot
	// transfer, including its deterministic Protobuf envelope.
	MaximumSnapshotEnvelopeBytes = MaximumSnapshotPayloadBytes + MaximumSnapshotEnvelopeOverheadBytes
	// MaximumSnapshotBytes is retained as the public compatibility spelling for
	// the complete opaque transfer bound.
	MaximumSnapshotBytes = MaximumSnapshotEnvelopeBytes
	// MaximumCapabilities bounds negotiated capability cardinality.
	MaximumCapabilities = 1024
)
View Source 
const (
	// InitializationAttemptIDBytes is the exact protocol wire width of an
	// initialization attempt identity.
	InitializationAttemptIDBytes = 16
)
View Source 
const MaximumModelDeltaBytes = 256 << 10

MaximumModelDeltaBytes matches one kernel model stream delta.

View Source 
const MaximumStructuredValueBytes = 512 << 10

MaximumStructuredValueBytes bounds interaction schemas and responses.

Variables

View Source 
var ErrClosed = errors.New("client handle is closed")

ErrClosed is returned by future operations after a local Session or stream handle closes. Close must also unblock active stream reads with ErrClosed.

Functions

This section is empty.

Types

type Build 

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

Build identifies one client or server build without containing credentials.

func NewBuild 

func NewBuild(component, version, commit, goVersion string) (Build, error)

NewBuild constructs validated non-secret build provenance.

func (Build) Commit 

func (build Build) Commit() string

func (Build) Component 

func (build Build) Component() string

func (Build) GoVersion 

func (build Build) GoVersion() string

func (Build) Validate 

func (build Build) Validate() error

Validate rejects a zero or corrupted Build.

func (Build) Version 

func (build Build) Version() string

type CancelRequest 

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

CancelRequest is one idempotent cooperative cancellation mutation.

func NewCancelRequest 

func NewCancelRequest(run RunRef, operation OperationID, reason string) (CancelRequest, error)

func (CancelRequest) Operation 

func (request CancelRequest) Operation() OperationID

func (CancelRequest) Reason 

func (request CancelRequest) Reason() string

func (CancelRequest) Run 

func (request CancelRequest) Run() RunRef

type CancelResult 

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

CancelResult reports an idempotent cooperative cancellation outcome.

func NewCancelResult 

func NewCancelResult(requested, alreadyTerminal bool, terminalSequence uint64) (CancelResult, error)

func (CancelResult) AlreadyTerminal 

func (result CancelResult) AlreadyTerminal() bool

func (CancelResult) Requested 

func (result CancelResult) Requested() bool

func (CancelResult) TerminalSequence 

func (result CancelResult) TerminalSequence() uint64

type CapabilityMismatchError 

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

CapabilityMismatchError reports the exact required capabilities unavailable from a server. All slices are canonical and defensively copied.

func NewCapabilityMismatchError 

func NewCapabilityMismatchError(
	facts ErrorFacts,
	required, available, missing []string,
) (*CapabilityMismatchError, error)

func (*CapabilityMismatchError) Available 

func (current *CapabilityMismatchError) Available() []string

func (*CapabilityMismatchError) Error 

func (current *CapabilityMismatchError) Error() string

func (*CapabilityMismatchError) Facts 

func (current *CapabilityMismatchError) Facts() ErrorFacts

func (*CapabilityMismatchError) Missing 

func (current *CapabilityMismatchError) Missing() []string

func (*CapabilityMismatchError) Operation 

func (current *CapabilityMismatchError) Operation() (OperationID, bool)

func (*CapabilityMismatchError) Required 

func (current *CapabilityMismatchError) Required() []string

func (*CapabilityMismatchError) Retryable 

func (current *CapabilityMismatchError) Retryable() bool

type Catalog 

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

Catalog is a canonical immutable generated definition set.

func NewCatalog 

func NewCatalog(revision string, definitions []Definition, limits Limits) (Catalog, error)

NewCatalog validates and sorts definitions within negotiated collection limits.

func (Catalog) Definitions 

func (catalog Catalog) Definitions() []Definition

func (Catalog) Find 

func (catalog Catalog) Find(reference DefinitionRef) (Definition, bool)

Find returns the exact definition, if present.

func (Catalog) Revision 

func (catalog Catalog) Revision() string

func (Catalog) Validate 

func (catalog Catalog) Validate(limits Limits) error

type Connection 

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

Connection is an immutable negotiated session contract.

func NewConnection 

func NewConnection(spec ConnectionSpec) (Connection, error)

NewConnection constructs one complete negotiated session contract.

func (Connection) Capabilities 

func (connection Connection) Capabilities() []string

func (Connection) Catalog 

func (connection Connection) Catalog() Catalog

func (Connection) ClientID 

func (connection Connection) ClientID() string

func (Connection) Health 

func (connection Connection) Health() Health

func (Connection) Limits 

func (connection Connection) Limits() Limits

func (Connection) OwnershipEpoch 

func (connection Connection) OwnershipEpoch() uint64

func (Connection) Protocol 

func (connection Connection) Protocol() ProtocolVersion

func (Connection) Server 

func (connection Connection) Server() Build

func (Connection) Validate 

func (connection Connection) Validate() error

type ConnectionSpec 

type ConnectionSpec struct {
	Protocol       ProtocolVersion
	Server         Build
	Capabilities   []string
	Limits         Limits
	Health         Health
	ClientID       string
	OwnershipEpoch uint64
	Catalog        Catalog
}

ConnectionSpec contains non-secret inputs used to construct Connection. Slice fields are defensively copied by NewConnection.

type Connector 

type Connector interface {
	Initialize(context.Context, InitializeRequest) (Session, error)
}

Connector initializes one authenticated transport session. Endpoint discovery and authentication material belong to the implementation and are intentionally absent from InitializeRequest. The initialization context owns negotiation only and never becomes the Session lifetime.

type Cursor 

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

Cursor is a caller-acknowledged run position. A zero sequence means no event has been acknowledged yet.

func NewCursor 

func NewCursor(run RunRef, afterSequence uint64) (Cursor, error)

func (Cursor) AfterSequence 

func (cursor Cursor) AfterSequence() uint64

func (Cursor) Run 

func (cursor Cursor) Run() RunRef

func (Cursor) Validate 

func (cursor Cursor) Validate() error

type CursorGapError 

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

CursorGapError reports that acknowledged history is no longer retained. RecoverySequence is the explicit server-selected cursor for resynchronizing.

func NewCursorGapError 

func NewCursorGapError(
	facts ErrorFacts,
	run RunRef,
	requested, earliest, latest, recovery uint64,
) (*CursorGapError, error)

func (*CursorGapError) EarliestSequence 

func (current *CursorGapError) EarliestSequence() uint64

func (*CursorGapError) Error 

func (current *CursorGapError) Error() string

func (*CursorGapError) Facts 

func (current *CursorGapError) Facts() ErrorFacts

func (*CursorGapError) LatestSequence 

func (current *CursorGapError) LatestSequence() uint64

func (*CursorGapError) Operation 

func (current *CursorGapError) Operation() (OperationID, bool)

func (*CursorGapError) RecoverySequence 

func (current *CursorGapError) RecoverySequence() uint64

func (*CursorGapError) RequestedAfterSequence 

func (current *CursorGapError) RequestedAfterSequence() uint64

func (*CursorGapError) Retryable 

func (current *CursorGapError) Retryable() bool

func (*CursorGapError) Run 

func (current *CursorGapError) Run() RunRef

type Definition 

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

Definition is one immutable server-owned generated agent definition.

func NewDefinition 

func NewDefinition(reference DefinitionRef, model string, maxTurns uint32) (Definition, error)

NewDefinition constructs one definition advertised by a server.

func (Definition) MaxTurns 

func (definition Definition) MaxTurns() uint32

func (Definition) Model 

func (definition Definition) Model() string

func (Definition) Ref 

func (definition Definition) Ref() DefinitionRef

func (Definition) Validate 

func (definition Definition) Validate() error

type DefinitionRef 

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

DefinitionRef identifies one exact generated agent definition.

func NewDefinitionRef 

func NewDefinitionRef(id, revision string) (DefinitionRef, error)

NewDefinitionRef constructs an exact definition reference.

func (DefinitionRef) ID 

func (reference DefinitionRef) ID() string

func (DefinitionRef) Revision 

func (reference DefinitionRef) Revision() string

func (DefinitionRef) Validate 

func (reference DefinitionRef) Validate() error

type ErrorCode 

type ErrorCode string

ErrorCode identifies a stable generic failure without exposing transport status types. Failures with structured recovery facts use dedicated errors. 

const (
	ErrorInvalidArgument  ErrorCode = "invalid-argument"
	ErrorUnauthenticated  ErrorCode = "unauthenticated"
	ErrorNotFound         ErrorCode = "not-found"
	ErrorUnavailable      ErrorCode = "unavailable"
	ErrorCancelled        ErrorCode = "cancelled"
	ErrorDeadlineExceeded ErrorCode = "deadline-exceeded"
	ErrorConflict         ErrorCode = "conflict"
	ErrorInternal         ErrorCode = "internal"
)

type ErrorFacts 

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

ErrorFacts are the common, safe fields carried by every failed protocol status. Values are immutable and contain no protocol or transport types. Message is server-declared safe text and must never contain StructuredValue application data.

func NewErrorFacts 

func NewErrorFacts(message string, retryable bool, operation *OperationID) (ErrorFacts, error)

NewErrorFacts validates and defensively copies common failed-status fields.

func (ErrorFacts) Message 

func (facts ErrorFacts) Message() string

func (ErrorFacts) Operation 

func (facts ErrorFacts) Operation() (OperationID, bool)

func (ErrorFacts) Retryable 

func (facts ErrorFacts) Retryable() bool

func (ErrorFacts) Validate 

func (facts ErrorFacts) Validate() error

type Event 

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

Event is one strictly sequenced immutable client event.

func NewEvent 

func NewEvent(run RunRef, sequence uint64, at time.Time, kind EventKind, detail EventDetail) (Event, error)

func (Event) At 

func (current Event) At() time.Time

func (Event) Cursor 

func (current Event) Cursor() Cursor

Cursor returns an acknowledgment candidate for this event. The caller must persist it only after processing the event successfully.

func (Event) Detail 

func (current Event) Detail() EventDetail

func (Event) Kind 

func (current Event) Kind() EventKind

func (Event) Run 

func (current Event) Run() RunRef

func (Event) Sequence 

func (current Event) Sequence() uint64

func (Event) Terminal 

func (current Event) Terminal() bool

type EventControl 

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

EventControl describes one captured replay page and live-tail position.

func NewEventControl 

func NewEventControl(
	earliest,
	latest,
	lastDelivered,
	pageLast uint64,
	hasMore,
	tailing bool,
) (EventControl, error)

NewEventControl constructs the current explicit-page control form.

func NewLegacyEventControl 

func NewLegacyEventControl(earliest, latest, lastDelivered uint64) (EventControl, error)

NewLegacyEventControl constructs the compatibility control form without an explicit page cursor. Legacy controls cannot page or tail.

func (EventControl) EarliestSequence 

func (control EventControl) EarliestSequence() uint64

func (EventControl) HasMore 

func (control EventControl) HasMore() bool

func (EventControl) LastDeliveredSequence 

func (control EventControl) LastDeliveredSequence() uint64

func (EventControl) LatestSequence 

func (control EventControl) LatestSequence() uint64

func (EventControl) PageLastSequence 

func (control EventControl) PageLastSequence() (uint64, bool)

func (EventControl) Tailing 

func (control EventControl) Tailing() bool

func (EventControl) Validate 

func (control EventControl) Validate() error

type EventDetail 

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

EventDetail is a closed immutable union that faithfully represents every current provider-neutral kernel event payload.

func NewInteractionStartedDetail 

func NewInteractionStartedDetail(id, kind string) (EventDetail, error)

func NewInteractionTerminalDetail 

func NewInteractionTerminalDetail(id, problem string) (EventDetail, error)

func NewModelCompletedDetail 

func NewModelCompletedDetail(usage Usage) EventDetail

func NewModelFailedDetail 

func NewModelFailedDetail(failure ModelFailure) (EventDetail, error)

func NewModelStartedDetail 

func NewModelStartedDetail(turn uint32, operationID string) (EventDetail, error)

func NewRunStartedDetail 

func NewRunStartedDetail(definition string) (EventDetail, error)

func NewStatusDetail 

func NewStatusDetail(message string) (EventDetail, error)

func NewTextDetail 

func NewTextDetail(text string) (EventDetail, error)

func NewToolProgressDetail 

func NewToolProgressDetail(callID, message string) (EventDetail, error)

func NewToolStartedDetail 

func NewToolStartedDetail(callID, name string) (EventDetail, error)

func NewToolTerminalDetail 

func NewToolTerminalDetail(terminal ToolTerminal) (EventDetail, error)

func NewTurnDetail 

func NewTurnDetail(turn uint32) (EventDetail, error)

func NoEventDetail 

func NoEventDetail() EventDetail

func (EventDetail) Definition 

func (detail EventDetail) Definition() (string, bool)

func (EventDetail) InteractionStart 

func (detail EventDetail) InteractionStart() (string, string, bool)

func (EventDetail) InteractionTerminal 

func (detail EventDetail) InteractionTerminal() (string, string, bool)

func (EventDetail) Kind 

func (detail EventDetail) Kind() EventDetailKind

func (EventDetail) ModelFailure 

func (detail EventDetail) ModelFailure() (ModelFailure, bool)

func (EventDetail) ModelStart 

func (detail EventDetail) ModelStart() (uint32, string, bool)

func (EventDetail) Status 

func (detail EventDetail) Status() (string, bool)

func (EventDetail) Text 

func (detail EventDetail) Text() (string, bool)

func (EventDetail) ToolProgress 

func (detail EventDetail) ToolProgress() (string, string, bool)

func (EventDetail) ToolStart 

func (detail EventDetail) ToolStart() (string, string, bool)

func (EventDetail) ToolTerminal 

func (detail EventDetail) ToolTerminal() (ToolTerminal, bool)

func (EventDetail) Turn 

func (detail EventDetail) Turn() (uint32, bool)

func (EventDetail) Usage 

func (detail EventDetail) Usage() (Usage, bool)

type EventDetailKind 

type EventDetailKind string

EventDetailKind identifies the active typed detail in EventDetail. 

const (
	EventDetailNone                EventDetailKind = "none"
	EventDetailRunStarted          EventDetailKind = "run-started"
	EventDetailTurn                EventDetailKind = "turn"
	EventDetailModelStarted        EventDetailKind = "model-started"
	EventDetailText                EventDetailKind = "text"
	EventDetailModelCompleted      EventDetailKind = "model-completed"
	EventDetailModelFailed         EventDetailKind = "model-failed"
	EventDetailToolStarted         EventDetailKind = "tool-started"
	EventDetailToolProgress        EventDetailKind = "tool-progress"
	EventDetailToolTerminal        EventDetailKind = "tool-terminal"
	EventDetailInteractionStarted  EventDetailKind = "interaction-started"
	EventDetailInteractionTerminal EventDetailKind = "interaction-terminal"
	EventDetailStatus              EventDetailKind = "status"
)

type EventFrame 

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

EventFrame is a closed union of one event or one successful control record. Error controls are translated into typed client errors by the adapter.

func NewEventControlFrame 

func NewEventControlFrame(control EventControl) (EventFrame, error)

func NewEventFrame 

func NewEventFrame(event Event) (EventFrame, error)

func (EventFrame) Control 

func (frame EventFrame) Control() (EventControl, bool)

func (EventFrame) Event 

func (frame EventFrame) Event() (Event, bool)

func (EventFrame) Kind 

func (frame EventFrame) Kind() EventFrameKind

type EventFrameKind 

type EventFrameKind string

EventFrameKind identifies the active event-stream payload. 

const (
	EventFrameEvent   EventFrameKind = "event"
	EventFrameControl EventFrameKind = "control"
)

type EventKind 

type EventKind string

EventKind identifies one stable provider-neutral run occurrence. 

const (
	EventRunStarted           EventKind = "run.started"
	EventRunCompleted         EventKind = "run.completed"
	EventRunFailed            EventKind = "run.failed"
	EventRunCancelled         EventKind = "run.cancelled"
	EventTurnStarted          EventKind = "turn.started"
	EventTurnCompleted        EventKind = "turn.completed"
	EventTurnFailed           EventKind = "turn.failed"
	EventModelStarted         EventKind = "model.started"
	EventModelDelta           EventKind = "model.delta"
	EventModelCompleted       EventKind = "model.completed"
	EventModelFailed          EventKind = "model.failed"
	EventToolStarted          EventKind = "tool.started"
	EventToolProgress         EventKind = "tool.progress"
	EventToolCompleted        EventKind = "tool.completed"
	EventToolFailed           EventKind = "tool.failed"
	EventInteractionStarted   EventKind = "interaction.started"
	EventInteractionCompleted EventKind = "interaction.completed"
	EventInteractionFailed    EventKind = "interaction.failed"
	EventInteractionCancelled EventKind = "interaction.cancelled"
)

type EventStream 

type EventStream interface {
	Next(context.Context) (EventFrame, error)
	Close() error
}

EventStream is a local handle to a replay/tail operation. Next is single-reader and must honor its caller-owned context. Close is local, nonblocking, idempotent, may race with Next, unblocks an active Next, and causes future Next calls to return ErrClosed.

type EventStreamOptions 

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

EventStreamOptions bounds one replay page and chooses whether to tail.

func NewEventStreamOptions 

func NewEventStreamOptions(replayLimit uint32, tail bool, limits Limits) (EventStreamOptions, error)

func (EventStreamOptions) ReplayLimit 

func (options EventStreamOptions) ReplayLimit() uint32

func (EventStreamOptions) Tail 

func (options EventStreamOptions) Tail() bool

func (EventStreamOptions) Validate 

func (options EventStreamOptions) Validate(limits Limits) error

type Health 

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

Health is an immutable non-secret daemon readiness summary.

func NewHealth 

func NewHealth(state HealthState, reasons []string, activeRuns uint64, limits Limits) (Health, error)

NewHealth validates and canonicalizes one readiness summary.

func (Health) ActiveRuns 

func (health Health) ActiveRuns() uint64

func (Health) Limits 

func (health Health) Limits() Limits

func (Health) Reasons 

func (health Health) Reasons() []string

func (Health) State 

func (health Health) State() HealthState

func (Health) Validate 

func (health Health) Validate() error

type HealthState 

type HealthState string

HealthState is the bounded readiness state visible to a local client. 

const (
	HealthStarting HealthState = "starting"
	HealthReady    HealthState = "ready"
	HealthDegraded HealthState = "degraded"
	HealthStopping HealthState = "stopping"
)

type ImportRequest 

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

ImportRequest is one idempotent authenticated snapshot import.

func NewImportRequest 

func NewImportRequest(operation OperationID, snapshot Snapshot) (ImportRequest, error)

func (ImportRequest) Operation 

func (request ImportRequest) Operation() OperationID

func (ImportRequest) Snapshot 

func (request ImportRequest) Snapshot() Snapshot

type ImportResult 

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

ImportResult reports an authenticated snapshot import.

func NewImportResult 

func NewImportResult(run RunRef, nextSequence uint64, duplicate bool) (ImportResult, error)

func (ImportResult) DuplicateOperation 

func (result ImportResult) DuplicateOperation() bool

func (ImportResult) NextSequence 

func (result ImportResult) NextSequence() uint64

func (ImportResult) Run 

func (result ImportResult) Run() RunRef

type InitializationAttemptID 

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

InitializationAttemptID is one immutable, comparable 128-bit identity for an exact initialization intent. Its canonical text form is 32 lowercase hexadecimal characters without separators.

func NewInitializationAttemptID 

func NewInitializationAttemptID() (InitializationAttemptID, error)

NewInitializationAttemptID securely generates a nonzero initialization attempt identity. Callers own the returned identity and may reuse it only to replay the exact same InitializeRequest.

func ParseInitializationAttemptID 

func ParseInitializationAttemptID(encoded string) (InitializationAttemptID, error)

ParseInitializationAttemptID parses the canonical lowercase hexadecimal representation of an initialization attempt identity.

func (InitializationAttemptID) Bytes 

func (id InitializationAttemptID) Bytes() [initializationAttemptBytes]byte

Bytes returns the exact immutable wire representation by value.

func (InitializationAttemptID) MarshalText 

func (id InitializationAttemptID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler using the canonical form.

func (InitializationAttemptID) String 

func (id InitializationAttemptID) String() string

String returns the canonical lowercase hexadecimal representation.

func (InitializationAttemptID) Validate 

func (id InitializationAttemptID) Validate() error

Validate rejects the zero or corrupted initialization attempt identity.

type InitializationReplayError 

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

InitializationReplayError reports a protocol-1.3 initialization whose response was not observed after the request may have committed. Recovery is safe only by replaying the same immutable request carrying AttemptID; callers must never create a replacement attempt for this outcome.

func NewInitializationReplayError 

func NewInitializationReplayError(
	facts ErrorFacts,
	attempt InitializationAttemptID,
) (*InitializationReplayError, error)

NewInitializationReplayError constructs one constrained initialization recovery result.

func (*InitializationReplayError) AttemptID 

func (current *InitializationReplayError) AttemptID() InitializationAttemptID

AttemptID returns the exact caller-owned identity that must be reused.

func (*InitializationReplayError) Error 

func (current *InitializationReplayError) Error() string

func (*InitializationReplayError) Facts 

func (current *InitializationReplayError) Facts() ErrorFacts

func (*InitializationReplayError) Operation 

func (current *InitializationReplayError) Operation() (OperationID, bool)

func (*InitializationReplayError) Retryable 

func (current *InitializationReplayError) Retryable() bool

type InitializeRequest 

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

InitializeRequest is the immutable, non-secret client negotiation request.

func NewInitializeRequest deprecated 

func NewInitializeRequest(protocol ProtocolRange, client Build, supported, required []string, limits Limits) (InitializeRequest, error)

NewInitializeRequest constructs a legacy fresh-owner initialization request. It deliberately negotiates at most protocol 1.2 and therefore cannot be retried safely after an uncertain transport outcome. New code that supports protocol 1.3 should use NewInitializeRequestWithAttempt.

Deprecated: use NewInitializeRequestWithAttempt for protocol 1.3 clients.

func NewInitializeRequestWithAttempt 

func NewInitializeRequestWithAttempt(
	protocol ProtocolRange,
	client Build,
	supported, required []string,
	limits Limits,
	attempt InitializationAttemptID,
) (InitializeRequest, error)

NewInitializeRequestWithAttempt constructs a protocol-1.3-only fresh-owner request with one caller-owned exact replay identity.

func NewLegacyInitializeRequest 

func NewLegacyInitializeRequest(protocol ProtocolRange, client Build, supported, required []string, limits Limits) (InitializeRequest, error)

NewLegacyInitializeRequest constructs a protocol-1.0-through-1.2 fresh-owner request whose ambiguous transport failures must never be retried.

func NewLegacyReconnectRequest 

func NewLegacyReconnectRequest(protocol ProtocolRange, client Build, supported, required []string, limits Limits, claim ReconnectClaim) (InitializeRequest, error)

NewLegacyReconnectRequest constructs a protocol-1.0-through-1.2 reconnect request whose ambiguous ownership-CAS transport failures must never be retried.

func NewReconnectRequest deprecated 

func NewReconnectRequest(protocol ProtocolRange, client Build, supported, required []string, limits Limits, claim ReconnectClaim) (InitializeRequest, error)

NewReconnectRequest constructs an initialization request that atomically reclaims one stable client identity at its expected ownership epoch using legacy protocol semantics. It negotiates at most protocol 1.2 and is never retried automatically after an uncertain transport outcome.

Deprecated: use NewReconnectRequestWithAttempt for protocol 1.3 clients.

func NewReconnectRequestWithAttempt 

func NewReconnectRequestWithAttempt(
	protocol ProtocolRange,
	client Build,
	supported, required []string,
	limits Limits,
	claim ReconnectClaim,
	attempt InitializationAttemptID,
) (InitializeRequest, error)

NewReconnectRequestWithAttempt constructs a protocol-1.3-only reconnect request with one caller-owned exact replay identity.

func (InitializeRequest) AttemptID 

func (request InitializeRequest) AttemptID() (InitializationAttemptID, bool)

AttemptID returns the caller-owned exact replay identity when this is a protocol-1.3 initialization request.

func (InitializeRequest) Client 

func (request InitializeRequest) Client() Build

func (InitializeRequest) Protocol 

func (request InitializeRequest) Protocol() ProtocolRange

func (InitializeRequest) Reconnect 

func (request InitializeRequest) Reconnect() (ReconnectClaim, bool)

func (InitializeRequest) RequestedLimits 

func (request InitializeRequest) RequestedLimits() Limits

func (InitializeRequest) RequiredCapabilities 

func (request InitializeRequest) RequiredCapabilities() []string

func (InitializeRequest) SupportedCapabilities 

func (request InitializeRequest) SupportedCapabilities() []string

func (InitializeRequest) Validate 

func (request InitializeRequest) Validate() error

type Input 

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

Input is the bounded initial user text for an architecture-proof run. Rich content is intentionally deferred so it can be added as typed variants.

func NewInput 

func NewInput(messageID, text string) (Input, error)

NewInput constructs one initial user text message.

func (Input) MessageID 

func (input Input) MessageID() string

func (Input) Text 

func (input Input) Text() string

func (Input) Validate 

func (input Input) Validate() error

type InteractionControl 

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

InteractionControl describes one complete-snapshot/change page and tail.

func NewInteractionControl 

func NewInteractionControl(latestRevision, pageLastRevision uint64, hasMore, tailing bool) (InteractionControl, error)

func (InteractionControl) HasMore 

func (control InteractionControl) HasMore() bool

func (InteractionControl) LatestRevision 

func (control InteractionControl) LatestRevision() uint64

func (InteractionControl) PageLastRevision 

func (control InteractionControl) PageLastRevision() uint64

func (InteractionControl) Tailing 

func (control InteractionControl) Tailing() bool

func (InteractionControl) Validate 

func (control InteractionControl) Validate() error

type InteractionFrame 

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

InteractionFrame is a closed union of a snapshot/change or successful control record. A valid stream begins with a snapshot update.

func NewInteractionControlFrame 

func NewInteractionControlFrame(control InteractionControl) (InteractionFrame, error)

func NewInteractionFrame 

func NewInteractionFrame(update InteractionUpdate) (InteractionFrame, error)

func (InteractionFrame) Control 

func (frame InteractionFrame) Control() (InteractionControl, bool)

func (InteractionFrame) Kind 

func (frame InteractionFrame) Kind() InteractionFrameKind

func (InteractionFrame) Update 

func (frame InteractionFrame) Update() (InteractionUpdate, bool)

type InteractionFrameKind 

type InteractionFrameKind string

InteractionFrameKind identifies the active interaction-stream payload. 

const (
	InteractionFrameUpdate  InteractionFrameKind = "update"
	InteractionFrameControl InteractionFrameKind = "control"
)

type InteractionResponse 

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

InteractionResponse is one bounded structured response to a pending prompt.

func NewInteractionResponse 

func NewInteractionResponse(id string, value StructuredValue) (InteractionResponse, error)

func (InteractionResponse) ID 

func (response InteractionResponse) ID() string

func (InteractionResponse) Validate 

func (response InteractionResponse) Validate() error

func (InteractionResponse) Value 

func (response InteractionResponse) Value() StructuredValue

type InteractionStream 

type InteractionStream interface {
	Next(context.Context) (InteractionFrame, error)
	Close() error
}

InteractionStream yields a complete pending snapshot first and then strictly revision-contiguous changes and explicit controls. Next is single-reader and must honor its caller-owned context. Close is local, nonblocking, idempotent, may race with Next, unblocks an active Next, and causes future Next calls to return ErrClosed.

type InteractionStreamOptions 

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

InteractionStreamOptions chooses whether to tail future changes after the mandatory complete snapshot and captured control. Reconnect always starts from a fresh snapshot, so interaction streams have no historical replay cursor or limit.

func NewInteractionStreamOptions 

func NewInteractionStreamOptions(tail bool) InteractionStreamOptions

func (InteractionStreamOptions) Tail 

func (options InteractionStreamOptions) Tail() bool

func (InteractionStreamOptions) Validate 

func (InteractionStreamOptions) Validate() error

type InteractionUpdate 

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

InteractionUpdate is a closed immutable union. Every stream begins with a complete snapshot; subsequent opened/closed revisions are contiguous.

func NewInteractionChange 

func NewInteractionChange(kind InteractionUpdateKind, revision uint64, item PendingInteraction) (InteractionUpdate, error)

func NewInteractionSnapshot 

func NewInteractionSnapshot(revision uint64, pending []PendingInteraction, limits Limits) (InteractionUpdate, error)

func (InteractionUpdate) Item 

func (update InteractionUpdate) Item() (PendingInteraction, bool)

func (InteractionUpdate) Kind 

func (update InteractionUpdate) Kind() InteractionUpdateKind

func (InteractionUpdate) Revision 

func (update InteractionUpdate) Revision() uint64

func (InteractionUpdate) Snapshot 

func (update InteractionUpdate) Snapshot() ([]PendingInteraction, bool)

type InteractionUpdateKind 

type InteractionUpdateKind string

InteractionUpdateKind identifies the active stream payload. 

const (
	InteractionSnapshot InteractionUpdateKind = "snapshot"
	InteractionOpened   InteractionUpdateKind = "opened"
	InteractionClosed   InteractionUpdateKind = "closed"
)

type Limits 

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

Limits are the negotiated upper bounds for one client session.

func NewLimits 

func NewLimits(messageBytes uint64, collectionItems, replayEvents uint32, replayBytes uint64, concurrentStreams, activeRuns uint32) (Limits, error)

NewLimits constructs internally consistent positive session limits.

func (Limits) ActiveRuns 

func (limits Limits) ActiveRuns() uint32

func (Limits) CollectionItems 

func (limits Limits) CollectionItems() uint32

func (Limits) ConcurrentStreams 

func (limits Limits) ConcurrentStreams() uint32

func (Limits) MessageBytes 

func (limits Limits) MessageBytes() uint64

func (Limits) ReplayBytes 

func (limits Limits) ReplayBytes() uint64

func (Limits) ReplayEvents 

func (limits Limits) ReplayEvents() uint32

func (Limits) Validate 

func (limits Limits) Validate() error

type ModelFailure 

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

ModelFailure is a portable model failure without provider metadata.

func NewModelFailure 

func NewModelFailure(code, message string, retryable, beforeStream bool) (ModelFailure, error)

func (ModelFailure) BeforeStream 

func (failure ModelFailure) BeforeStream() bool

func (ModelFailure) Code 

func (failure ModelFailure) Code() string

func (ModelFailure) Message 

func (failure ModelFailure) Message() string

func (ModelFailure) Retryable 

func (failure ModelFailure) Retryable() bool

type OperationID 

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

OperationID is a caller-generated idempotency identity for one mutation.

func NewOperationID 

func NewOperationID(value string) (OperationID, error)

NewOperationID constructs a bounded mutation identity.

func (OperationID) String 

func (id OperationID) String() string

func (OperationID) Validate 

func (id OperationID) Validate() error

type OverloadError 

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

OverloadError reports one exceeded bounded resource.

func NewOverloadError 

func NewOverloadError(facts ErrorFacts, resource string, limit, observed uint64) (*OverloadError, error)

func (*OverloadError) Error 

func (current *OverloadError) Error() string

func (*OverloadError) Facts 

func (current *OverloadError) Facts() ErrorFacts

func (*OverloadError) Limit 

func (current *OverloadError) Limit() uint64

func (*OverloadError) Observed 

func (current *OverloadError) Observed() uint64

func (*OverloadError) Operation 

func (current *OverloadError) Operation() (OperationID, bool)

func (*OverloadError) Resource 

func (current *OverloadError) Resource() string

func (*OverloadError) Retryable 

func (current *OverloadError) Retryable() bool

type PendingInteraction 

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

PendingInteraction is one immutable UI-neutral prompt with a portable structured schema.

func NewPendingInteraction 

func NewPendingInteraction(run RunRef, id, kind, prompt string, schema StructuredValue) (PendingInteraction, error)

func (PendingInteraction) ID 

func (pending PendingInteraction) ID() string

func (PendingInteraction) Kind 

func (pending PendingInteraction) Kind() string

func (PendingInteraction) Prompt 

func (pending PendingInteraction) Prompt() string

func (PendingInteraction) Run 

func (pending PendingInteraction) Run() RunRef

func (PendingInteraction) Schema 

func (pending PendingInteraction) Schema() StructuredValue

func (PendingInteraction) Validate 

func (pending PendingInteraction) Validate() error

type ProtocolRange 

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

ProtocolRange is one inclusive single-major compatibility range.

func NewProtocolRange 

func NewProtocolRange(minimum, maximum ProtocolVersion) (ProtocolRange, error)

NewProtocolRange constructs a non-inverted, single-major range.

func (ProtocolRange) Maximum 

func (current ProtocolRange) Maximum() ProtocolVersion

func (ProtocolRange) Minimum 

func (current ProtocolRange) Minimum() ProtocolVersion

func (ProtocolRange) Validate 

func (current ProtocolRange) Validate() error

type ProtocolVersion 

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

ProtocolVersion is one negotiated semantic protocol version.

func NewProtocolVersion 

func NewProtocolVersion(major, minor, patch uint32) (ProtocolVersion, error)

NewProtocolVersion constructs a version with a positive major.

func (ProtocolVersion) Major 

func (version ProtocolVersion) Major() uint32

func (ProtocolVersion) Minor 

func (version ProtocolVersion) Minor() uint32

func (ProtocolVersion) Patch 

func (version ProtocolVersion) Patch() uint32

func (ProtocolVersion) Validate 

func (version ProtocolVersion) Validate() error

type ReconnectClaim 

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

ReconnectClaim requests an atomic ownership-epoch compare-and-swap for a stable client identity. It is not an authentication credential.

func NewReconnectClaim 

func NewReconnectClaim(clientID string, expectedEpoch uint64) (ReconnectClaim, error)

NewReconnectClaim constructs a reconnect ownership claim.

func (ReconnectClaim) ClientID 

func (claim ReconnectClaim) ClientID() string

func (ReconnectClaim) ExpectedEpoch 

func (claim ReconnectClaim) ExpectedEpoch() uint64

func (ReconnectClaim) NextOwnershipEpoch 

func (claim ReconnectClaim) NextOwnershipEpoch() uint64

func (ReconnectClaim) Validate 

func (claim ReconnectClaim) Validate() error

type RespondRequest 

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

RespondRequest is one idempotent response mutation correlated to a run.

func NewRespondRequest 

func NewRespondRequest(run RunRef, operation OperationID, response InteractionResponse) (RespondRequest, error)

func (RespondRequest) Operation 

func (request RespondRequest) Operation() OperationID

func (RespondRequest) Response 

func (request RespondRequest) Response() InteractionResponse

func (RespondRequest) Run 

func (request RespondRequest) Run() RunRef

type RespondResult 

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

RespondResult reports whether an idempotent response operation was accepted.

func NewRespondResult 

func NewRespondResult(accepted, duplicate bool) (RespondResult, error)

func (RespondResult) Accepted 

func (result RespondResult) Accepted() bool

func (RespondResult) DuplicateOperation 

func (result RespondResult) DuplicateOperation() bool

type ResumeResult 

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

ResumeResult reports a local suspended run's continuation sequence.

func NewResumeResult 

func NewResumeResult(resumed bool, nextSequence uint64, duplicate bool) (ResumeResult, error)

func (ResumeResult) DuplicateOperation 

func (result ResumeResult) DuplicateOperation() bool

func (ResumeResult) NextSequence 

func (result ResumeResult) NextSequence() uint64

func (ResumeResult) Resumed 

func (result ResumeResult) Resumed() bool

type RunMutation 

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

RunMutation is an idempotent suspend or resume request.

func NewRunMutation 

func NewRunMutation(run RunRef, operation OperationID) (RunMutation, error)

func (RunMutation) Operation 

func (request RunMutation) Operation() OperationID

func (RunMutation) Run 

func (request RunMutation) Run() RunRef

type RunRef 

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

RunRef is one validated stable run identity. It carries no hidden session or network state and may be reconstructed when reconnecting to a known run.

func NewRunRef 

func NewRunRef(id string) (RunRef, error)

NewRunRef constructs a stable run reference.

func (RunRef) ID 

func (run RunRef) ID() string

func (RunRef) Validate 

func (run RunRef) Validate() error

type Session 

type Session interface {
	Connection() Connection
	Start(context.Context, StartRequest) (StartResult, error)
	Events(context.Context, Cursor, EventStreamOptions) (EventStream, error)
	Interactions(context.Context, InteractionStreamOptions) (InteractionStream, error)
	Cancel(context.Context, CancelRequest) (CancelResult, error)
	Respond(context.Context, RespondRequest) (RespondResult, error)
	Suspend(context.Context, RunMutation) (SuspendResult, error)
	Resume(context.Context, RunMutation) (ResumeResult, error)
	Export(context.Context, RunRef) (Snapshot, error)
	Import(context.Context, ImportRequest) (ImportResult, error)
	Health(context.Context) (Health, error)
	Close() error
}

Session is one negotiated stable-client ownership epoch. All methods are safe for concurrent use, including simultaneous streams, mutations, and health calls. Implementations must not retry mutations automatically: an unknown commit outcome is returned as UncertainOperationError for explicit caller recovery. Close is local, nonblocking, idempotent, may race with any method, unblocks active streams, and makes future context-taking operations return ErrClosed. Connection remains an immutable local snapshot callable after Close.

type Snapshot 

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

Snapshot is a bounded opaque authenticated snapshot envelope. Its contents are deliberately not interpreted by clients; an authorized Session exports and imports the bytes atomically.

func ParseSnapshot 

func ParseSnapshot(encoded []byte) (Snapshot, error)

ParseSnapshot constructs an opaque transfer value from persisted bytes. Cryptographic and lifecycle verification remains the importing authority's responsibility and must occur before state mutation.

func (Snapshot) MarshalBinary 

func (snapshot Snapshot) MarshalBinary() ([]byte, error)

MarshalBinary returns a defensive copy suitable for persistence or transfer.

func (Snapshot) SizeBytes 

func (snapshot Snapshot) SizeBytes() int

type SnapshotVersionMismatchError 

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

SnapshotVersionMismatchError reports incompatible safe snapshot formats.

func NewSnapshotVersionMismatchError 

func NewSnapshotVersionMismatchError(
	facts ErrorFacts,
	expected, observed string,
) (*SnapshotVersionMismatchError, error)

func (*SnapshotVersionMismatchError) Error 

func (current *SnapshotVersionMismatchError) Error() string

func (*SnapshotVersionMismatchError) Expected 

func (current *SnapshotVersionMismatchError) Expected() string

func (*SnapshotVersionMismatchError) Facts 

func (current *SnapshotVersionMismatchError) Facts() ErrorFacts

func (*SnapshotVersionMismatchError) Observed 

func (current *SnapshotVersionMismatchError) Observed() string

func (*SnapshotVersionMismatchError) Operation 

func (current *SnapshotVersionMismatchError) Operation() (OperationID, bool)

func (*SnapshotVersionMismatchError) Retryable 

func (current *SnapshotVersionMismatchError) Retryable() bool

type StaleSessionError 

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

StaleSessionError reports a lost stable-client ownership epoch. The caller may reconnect using the expected epoch only after reconciling ownership.

func NewStaleSessionError 

func NewStaleSessionError(facts ErrorFacts, expected, observed uint64) (*StaleSessionError, error)

func (*StaleSessionError) Error 

func (current *StaleSessionError) Error() string

func (*StaleSessionError) ExpectedEpoch 

func (current *StaleSessionError) ExpectedEpoch() uint64

func (*StaleSessionError) Facts 

func (current *StaleSessionError) Facts() ErrorFacts

func (*StaleSessionError) ObservedEpoch 

func (current *StaleSessionError) ObservedEpoch() uint64

func (*StaleSessionError) Operation 

func (current *StaleSessionError) Operation() (OperationID, bool)

func (*StaleSessionError) Retryable 

func (current *StaleSessionError) Retryable() bool

type StartRequest 

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

StartRequest is one idempotent generated-definition run request.

func NewStartRequest 

func NewStartRequest(operation OperationID, definition DefinitionRef, input Input) (StartRequest, error)

func (StartRequest) Definition 

func (request StartRequest) Definition() DefinitionRef

func (StartRequest) Input 

func (request StartRequest) Input() Input

func (StartRequest) Operation 

func (request StartRequest) Operation() OperationID

func (StartRequest) Validate 

func (request StartRequest) Validate() error

type StartResult 

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

StartResult identifies the server-selected immutable plan and first sequence.

func NewStartResult 

func NewStartResult(run RunRef, initialSequence uint64, planID string, duplicate bool) (StartResult, error)

func (StartResult) DuplicateOperation 

func (result StartResult) DuplicateOperation() bool

func (StartResult) InitialSequence 

func (result StartResult) InitialSequence() uint64

func (StartResult) PlanID 

func (result StartResult) PlanID() string

func (StartResult) Run 

func (result StartResult) Run() RunRef

type StatusError 

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

StatusError is one immutable generic application failure.

func NewStatusError 

func NewStatusError(code ErrorCode, facts ErrorFacts) (*StatusError, error)

func (*StatusError) Code 

func (current *StatusError) Code() ErrorCode

func (*StatusError) Error 

func (current *StatusError) Error() string

func (*StatusError) Facts 

func (current *StatusError) Facts() ErrorFacts

func (*StatusError) Operation 

func (current *StatusError) Operation() (OperationID, bool)

func (*StatusError) Retryable 

func (current *StatusError) Retryable() bool

type StatusFailure 

type StatusFailure interface {
	error
	Facts() ErrorFacts
	Retryable() bool
	Operation() (OperationID, bool)
}

StatusFailure is implemented by every typed client status error. It exposes the common safe fields without duplicating transport-specific status values.

type StructuredKind 

type StructuredKind string

StructuredKind identifies the top-level JSON value without exposing a raw protocol or map representation. 

const (
	StructuredNull   StructuredKind = "null"
	StructuredBool   StructuredKind = "boolean"
	StructuredNumber StructuredKind = "number"
	StructuredText   StructuredKind = "text"
	StructuredArray  StructuredKind = "array"
	StructuredObject StructuredKind = "object"
)

type StructuredValue 

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

StructuredValue is immutable bounded JSON used for portable interaction schemas and responses. It may contain secret-bearing application data and must never be copied into logs, events, status messages, or diagnostics. Default formatting, structured logging, and JSON encoding are redacted.

func NewStructuredBool 

func NewStructuredBool(value bool) StructuredValue

NewStructuredBool constructs a JSON Boolean value.

func NewStructuredNull 

func NewStructuredNull() StructuredValue

NewStructuredNull constructs the valid JSON null value.

func NewStructuredText 

func NewStructuredText(value string) (StructuredValue, error)

NewStructuredText constructs a JSON string value.

func ParseStructuredValue 

func ParseStructuredValue(encoded []byte) (StructuredValue, error)

ParseStructuredValue validates and defensively copies one arbitrary JSON value. Empty input is invalid; the JSON literal null is valid.

func (StructuredValue) Bool 

func (value StructuredValue) Bool() (bool, bool)

Bool returns the decoded Boolean when this is a JSON Boolean.

func (StructuredValue) EncodeTransfer 

func (value StructuredValue) EncodeTransfer() ([]byte, error)

EncodeTransfer returns a defensive copy of the exact validated, potentially sensitive JSON for an explicit adapter transfer. Callers must not use it for logs, events, errors, status, or diagnostics.

func (StructuredValue) GoString 

func (value StructuredValue) GoString() string

GoString redacts application data under Go-syntax formatting.

func (StructuredValue) IsNull 

func (value StructuredValue) IsNull() bool

func (StructuredValue) Kind 

func (value StructuredValue) Kind() StructuredKind

func (StructuredValue) LogValue 

func (value StructuredValue) LogValue() slog.Value

LogValue redacts application data under structured logging.

func (StructuredValue) String 

func (value StructuredValue) String() string

String redacts application data under ordinary formatting.

func (StructuredValue) Text 

func (value StructuredValue) Text() (string, bool)

Text returns the decoded string when this is a JSON string.

func (StructuredValue) Validate 

func (value StructuredValue) Validate() error

type SuspendResult 

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

SuspendResult reports an idempotent safe-boundary suspension.

func NewSuspendResult 

func NewSuspendResult(suspended bool, boundarySequence uint64, duplicate bool) (SuspendResult, error)

func (SuspendResult) BoundarySequence 

func (result SuspendResult) BoundarySequence() uint64

func (SuspendResult) DuplicateOperation 

func (result SuspendResult) DuplicateOperation() bool

func (SuspendResult) Suspended 

func (result SuspendResult) Suspended() bool

type TerminalError 

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

TerminalError reports that a requested mutation targets an already-terminal run. It preserves the full common status alongside the stable run detail.

func NewTerminalError 

func NewTerminalError(facts ErrorFacts, run RunRef) (*TerminalError, error)

func (*TerminalError) Error 

func (current *TerminalError) Error() string

func (*TerminalError) Facts 

func (current *TerminalError) Facts() ErrorFacts

func (*TerminalError) Operation 

func (current *TerminalError) Operation() (OperationID, bool)

func (*TerminalError) Retryable 

func (current *TerminalError) Retryable() bool

func (*TerminalError) Run 

func (current *TerminalError) Run() RunRef

type ToolOutcome 

type ToolOutcome string

ToolOutcome identifies whether a failed tool operation definitely committed no external mutation or has an uncertain external outcome. 

const (
	ToolOutcomeDefinitive ToolOutcome = "definitive"
	ToolOutcomeUncertain  ToolOutcome = "uncertain"
)

type ToolRetry 

type ToolRetry string

ToolRetry is portable deliberate-retry advice. 

const (
	ToolRetryNever   ToolRetry = "never"
	ToolRetryAllowed ToolRetry = "allowed"
)

type ToolTerminal 

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

ToolTerminal is one compiled-tool completion or failure payload.

func NewToolTerminal 

func NewToolTerminal(callID, name, problem string, outcome ToolOutcome, retry ToolRetry) (ToolTerminal, error)

func (ToolTerminal) CallID 

func (terminal ToolTerminal) CallID() string

func (ToolTerminal) Name 

func (terminal ToolTerminal) Name() string

func (ToolTerminal) Outcome 

func (terminal ToolTerminal) Outcome() ToolOutcome

func (ToolTerminal) Problem 

func (terminal ToolTerminal) Problem() string

func (ToolTerminal) Retry 

func (terminal ToolTerminal) Retry() ToolRetry

type UncertainOperationError 

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

UncertainOperationError reports a mutation whose commit outcome cannot be determined safely. Callers must inspect authoritative state before deciding whether a new operation is safe; implementations never replay it implicitly.

func NewUncertainOperationError 

func NewUncertainOperationError(
	facts ErrorFacts,
	uncertainOperation OperationID,
	kind string,
) (*UncertainOperationError, error)

func (*UncertainOperationError) Error 

func (current *UncertainOperationError) Error() string

func (*UncertainOperationError) Facts 

func (current *UncertainOperationError) Facts() ErrorFacts

func (*UncertainOperationError) Kind 

func (current *UncertainOperationError) Kind() string

func (*UncertainOperationError) Operation 

func (current *UncertainOperationError) Operation() (OperationID, bool)

func (*UncertainOperationError) Retryable 

func (current *UncertainOperationError) Retryable() bool

func (*UncertainOperationError) UncertainOperation 

func (current *UncertainOperationError) UncertainOperation() OperationID

type Usage 

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

Usage is portable model token accounting. Provider metadata is deliberately omitted from the public client contract.

func NewUsage 

func NewUsage(inputTokens, outputTokens uint64) Usage

func (Usage) InputTokens 

func (usage Usage) InputTokens() uint64

func (Usage) OutputTokens 

func (usage Usage) OutputTokens() uint64

type VersionMismatchError 

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

VersionMismatchError reports two valid protocol ranges that do not overlap.

func NewVersionMismatchError 

func NewVersionMismatchError(
	facts ErrorFacts,
	client, server ProtocolRange,
) (*VersionMismatchError, error)

func (*VersionMismatchError) Client 

func (current *VersionMismatchError) Client() ProtocolRange

func (*VersionMismatchError) Error 

func (current *VersionMismatchError) Error() string

func (*VersionMismatchError) Facts 

func (current *VersionMismatchError) Facts() ErrorFacts

func (*VersionMismatchError) Operation 

func (current *VersionMismatchError) Operation() (OperationID, bool)

func (*VersionMismatchError) Retryable 

func (current *VersionMismatchError) Retryable() bool

func (*VersionMismatchError) Server 

func (current *VersionMismatchError) Server() ProtocolRange

Source Files

View all Source files

Directories

Path Synopsis
Package grpcclient adapts the engine/v1 gRPC protocol to the transport-neutral client contracts.
 Package grpcclient adapts the engine/v1 gRPC protocol to the transport-neutral client contracts.
Package localclient binds secure daemon endpoint discovery and local IPC to the transport-neutral client contracts.
 Package localclient binds secure daemon endpoint discovery and local IPC to the transport-neutral client contracts.
Package managed coordinates attach-or-start behavior while retaining exact ownership of only the daemon candidate it launches.
 Package managed coordinates attach-or-start behavior while retaining exact ownership of only the daemon candidate it launches.

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.