runtime

package
v0.5.1 Latest Latest
Warning

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

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

Documentation

Overview

Package runtime defines the runtime-neutral execution boundary for operator-facing Agents.

The package may depend on pkg/agent for the stable Agent definition. Lower protocol packages such as pkg/acp, pkg/llm, and pkg/mcp must not depend on this package or on pkg/agent. Gateway-owned adapters sit above both sides and translate native runtime requests and events into these contracts.

This package owns contracts, not backend lifecycle or transport behavior. Backends remain responsible for their native processes, sessions, checkpoints, and protocol details.

Index

Constants

View Source 
const (
	EventSession           = "session"
	EventDelta             = "delta"
	EventReasoning         = "reasoning"
	EventContent           = "content"
	EventPlan              = "plan"
	EventToolCall          = "tool_call"
	EventUsage             = "usage"
	EventPermission        = "permission"
	EventDone              = "done"
	EventError             = "error"
	EventAvailableCommands = "available_commands"
	EventSessionInfo       = "session_info"
	EventMode              = "mode"
	EventConfigOptions     = "config_options"
)
View Source 
const (
	StopReasonPermissionRequired = "permission_required"
	StopReasonCancelled          = "cancelled"
)
View Source 
const TurnOptionsVersionV1 = "v1"

Variables

View Source 
var (
	ErrAgentNotFound          = &Error{Code: ErrorAgentNotFound}
	ErrAgentDisabled          = &Error{Code: ErrorAgentDisabled}
	ErrRuntimeNotExecutable   = &Error{Code: ErrorRuntimeNotExecutable}
	ErrCapabilityNotSupported = &Error{Code: ErrorCapabilityNotSupported}
	ErrInvalidRequest         = &Error{Code: ErrorInvalidRequest}
	ErrUnsupportedOption      = &Error{Code: ErrorUnsupportedOption}
	ErrSessionNotFound        = &Error{Code: ErrorSessionNotFound}
	ErrSessionBusy            = &Error{Code: ErrorSessionBusy}
	ErrSessionLimitExceeded   = &Error{Code: ErrorSessionLimitExceeded}
	ErrRunNotFound            = &Error{Code: ErrorRunNotFound}
	ErrPermissionRequired     = &Error{Code: ErrorPermissionRequired}
	ErrPermissionNotFound     = &Error{Code: ErrorPermissionNotFound}
	ErrPermissionExpired      = &Error{Code: ErrorPermissionExpired}
	ErrTurnLimitExceeded      = &Error{Code: ErrorTurnLimitExceeded}
	ErrTurnCancelled          = &Error{Code: ErrorTurnCancelled}
	ErrBackendUnavailable     = &Error{Code: ErrorBackendUnavailable}
	ErrBackendTimeout         = &Error{Code: ErrorBackendTimeout}
	ErrTurnFailed             = &Error{Code: ErrorTurnFailed}
)

Functions

func DecodeRuntimeOptions 

func DecodeRuntimeOptions(raw json.RawMessage, dst any) error

DecodeRuntimeOptions strictly decodes the selected backend's opaque v1 object. Unknown or foreign-runtime fields are never ignored.

func HTTPStatus 

func HTTPStatus(err error) int

HTTPStatus maps a normalized runtime error to its pre-stream status.

func IsAgentRetirementCancellation 

func IsAgentRetirementCancellation(ctx context.Context) bool

IsAgentRetirementCancellation reports whether a cancel callback is being invoked by fail-closed Agent deletion/runtime retirement rather than an operator's exact-run request. Backends may use this to durably mark a pre-bind native run for cancellation while preserving retryable exact cancel.

func IsNormalized 

func IsNormalized(err error) bool

func MergeIdentities 

func MergeIdentities(ctx context.Context, overlay Identities) context.Context

MergeIdentities overlays non-empty correlation fields on any identities already in ctx. SegmentIndex is always taken from overlay.

func NewContinuationToken 

func NewContinuationToken() (string, error)

NewContinuationToken returns an unguessable process-local backend lookup key.

func NewError 

func NewError(code ErrorCode, message string) error

func NewRunID 

func NewRunID() (string, error)

NewRunID returns an opaque, process-independent logical execution id.

func NormalizeError 

func NormalizeError(err error) error

NormalizeError preserves an existing runtime error and closes over native failures so transports never need to expose or classify backend details.

func ValidRunID 

func ValidRunID(id string) bool

func WithIdentities 

func WithIdentities(ctx context.Context, ids Identities) context.Context

WithIdentities stores a copy of ids in ctx. Empty fields intentionally remain empty; callers can use MergeIdentities to add run data without discarding trace data already attached by the transport.

func WithPermissionSource 

func WithPermissionSource(ctx context.Context, source string) context.Context

func WrapError 

func WrapError(code ErrorCode, message string, cause error) error

Types

type Backend 

type Backend interface {
	RuntimeType() string
	Capabilities(context.Context, agent.Agent) (Capabilities, error)
	ServeTurn(context.Context, agent.Agent, TurnRequest, EventSink) error
}

Backend is the required turn-first execution contract implemented by every executable Agent runtime.

type CancelCapabilities 

type CancelCapabilities struct {
	Force    bool `json:"force"`
	Graceful bool `json:"graceful"`
}

type CancelMode 

type CancelMode string
const (
	CancelModeForce    CancelMode = "force"
	CancelModeGraceful CancelMode = "graceful"
)

type CancelRequest 

type CancelRequest struct {
	RunID string     `json:"run_id"`
	Mode  CancelMode `json:"mode"`
}

type CancelResult 

type CancelResult struct {
	RunID      string    `json:"run_id"`
	State      RunState  `json:"state"`
	StopReason string    `json:"stop_reason,omitempty"`
	FinishedAt time.Time `json:"finished_at,omitempty"`
}

type Capabilities 

type Capabilities struct {
	Executable   bool                   `json:"executable"`
	Turn         TurnCapabilities       `json:"turn"`
	Sessions     SessionCapabilities    `json:"sessions"`
	Permissions  PermissionCapabilities `json:"permissions"`
	Cancellation CancelCapabilities     `json:"cancellation"`
	Events       []string               `json:"events,omitempty"`
}

Capabilities is the authoritative description of one backend for one Agent definition version.

type ContinuationCursorBackend 

type ContinuationCursorBackend interface {
	LoadContinuationCursor(context.Context, agent.Agent, string) (EventCursor, error)
	StoreContinuationCursor(context.Context, agent.Agent, string, EventCursor) error
}

ContinuationCursorBackend persists the common event cursor beside a backend-owned, process-lifetime continuation. Implementations must not expose native checkpoint state through this interface.

type ContinuationResolver 

type ContinuationResolver interface {
	// ValidateContinuationDecision must be pure. The broker invokes it while
	// holding the claim lock so invalid input cannot consume a one-shot claim.
	ValidateContinuationDecision(string, PendingPermission, PermissionDecision) error
	ResolveContinuation(context.Context, string, PermissionDecision, time.Time) error
	ExpireContinuation(context.Context, string) error
}

ContinuationResolver resolves an opaque token through a backend-owned store. The common broker never retains native waiter/checkpoint state or a per-request callback that closes over such state.

type Error 

type Error struct {
	Code    ErrorCode
	Message string
	Cause   error
}

Error is a normalized Agent runtime failure. Message is safe for public responses; Cause is available to trusted logs through Unwrap.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(target error) bool

Is compares normalized errors by code, allowing errors.Is against the package sentinel values below.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorCode 

type ErrorCode string
const (
	ErrorAgentNotFound          ErrorCode = "agent_not_found"
	ErrorAgentDisabled          ErrorCode = "agent_disabled"
	ErrorRuntimeNotExecutable   ErrorCode = "runtime_not_executable"
	ErrorCapabilityNotSupported ErrorCode = "capability_not_supported"
	ErrorInvalidRequest         ErrorCode = "invalid_request"
	ErrorUnsupportedOption      ErrorCode = "unsupported_option"
	ErrorSessionNotFound        ErrorCode = "session_not_found"
	ErrorSessionBusy            ErrorCode = "session_busy"
	ErrorSessionLimitExceeded   ErrorCode = "session_limit_exceeded"
	ErrorRunNotFound            ErrorCode = "run_not_found"
	ErrorPermissionRequired     ErrorCode = "permission_required"
	ErrorPermissionNotFound     ErrorCode = "permission_not_found"
	ErrorPermissionExpired      ErrorCode = "permission_expired"
	ErrorTurnLimitExceeded      ErrorCode = "turn_limit_exceeded"
	ErrorTurnCancelled          ErrorCode = "turn_cancelled"
	ErrorBackendUnavailable     ErrorCode = "backend_unavailable"
	ErrorBackendTimeout         ErrorCode = "backend_timeout"
	ErrorTurnFailed             ErrorCode = "turn_failed"
)

func ErrorCodeOf 

func ErrorCodeOf(err error) (ErrorCode, bool)

type EventCursor 

type EventCursor struct {
	RunID        string `json:"run_id"`
	NextSequence uint64 `json:"next_sequence"`
	NextSegment  uint32 `json:"next_segment"`
}

EventCursor is the process-lifetime sequencing state stored beside a suspended backend continuation. NextSequence starts at 1 for a new run.

type EventSink 

type EventSink func(TurnEvent) error

EventSink receives turn events in emission order.

type ExecutionOptions 

type ExecutionOptions struct {
	LogicalExecutionKey string
}

ExecutionOptions carries trusted caller metadata. A validated upper-layer Workflow Activity may supply the logical execution key through an authenticated adapter; it is never accepted from ordinary turn JSON.

type Health 

type Health struct {
	Healthy   bool            `json:"healthy"`
	State     RuntimeState    `json:"state"`
	CheckedAt time.Time       `json:"checked_at"`
	Message   string          `json:"message,omitempty"`
	Details   json.RawMessage `json:"details,omitempty"`
}

type HealthChecker 

type HealthChecker interface {
	Health(context.Context, agent.Agent) (Health, error)
}

HealthChecker reports bounded, side-effect-free health. Implementations must not start a process, materialize a graph, create a session, or execute a turn.

type Identities 

type Identities struct {
	AgentID      string
	RuntimeType  string
	RunID        string
	SessionID    string
	RequestID    string
	TraceID      string
	SpanID       string
	ParentSpanID string
	SegmentIndex uint32
}

Identities contains the runtime-neutral correlation data carried through a logical Agent run. Trace fields describe one transport/execution segment; RunID remains stable when a later segment gets a new trace.

func IdentitiesFromContext 

func IdentitiesFromContext(ctx context.Context) (Identities, bool)

type ListSessionsRequest 

type ListSessionsRequest struct {
	CWD    string `json:"cwd,omitempty"`
	Cursor string `json:"cursor,omitempty"`
}

type ListSessionsResponse 

type ListSessionsResponse struct {
	Sessions   []Session `json:"sessions"`
	NextCursor string    `json:"next_cursor,omitempty"`
}

type OptionalCapabilities 

type OptionalCapabilities struct {
	SessionList       bool
	Transcript        bool
	PermissionResolve bool
	RunCancel         bool
	RuntimeInspect    bool
	HealthCheck       bool
}

OptionalCapabilities reports which narrow optional interfaces a backend actually implements. It describes Go-level support, not the per-Agent capability values returned by Backend.Capabilities.

func DetectOptionalCapabilities 

func DetectOptionalCapabilities(backend Backend) OptionalCapabilities

type PendingPermission 

type PendingPermission struct {
	RequestID   string               `json:"request_id"`
	AgentID     string               `json:"agent_id"`
	RuntimeType string               `json:"runtime_type"`
	RunID       string               `json:"run_id"`
	SessionID   string               `json:"session_id,omitempty"`
	CreatedAt   time.Time            `json:"created_at"`
	ExpiresAt   time.Time            `json:"expires_at"`
	Actions     []PermissionAction   `json:"actions,omitempty"`
	Options     []PermissionOption   `json:"options,omitempty"`
	ResumeMode  PermissionResumeMode `json:"resume_mode"`
	// TTL is an internal registration hint. When ExpiresAt is omitted, the
	// broker derives it from its injectable clock and this duration.
	TTL time.Duration `json:"-"`
}

PendingPermission is the runtime-neutral, claimable operator record. The opaque token is deliberately absent; native continuation identity remains in the selected backend's private store.

type PermissionAction 

type PermissionAction struct {
	ActionID string `json:"action_id"`
	Name     string `json:"name,omitempty"`
}

type PermissionActionDecision 

type PermissionActionDecision struct {
	ActionID string `json:"action_id"`
	Outcome  string `json:"outcome"`
}

type PermissionAudit 

type PermissionAudit struct {
	RequestID   string    `json:"request_id"`
	AgentID     string    `json:"agent_id"`
	RuntimeType string    `json:"runtime_type,omitempty"`
	RunID       string    `json:"run_id,omitempty"`
	SessionID   string    `json:"session_id,omitempty"`
	Source      string    `json:"source"`
	Result      string    `json:"result"`
	At          time.Time `json:"at"`
}

type PermissionBroker 

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

PermissionBroker is the sole owner of pending/claimable permission state. Claim removes the entry before invoking backend code, so errors are terminal.

func NewPermissionBroker 

func NewPermissionBroker() *PermissionBroker

func (*PermissionBroker) Audits 

func (b *PermissionBroker) Audits(agentID string) []PermissionAudit

func (*PermissionBroker) ClaimAgent 

func (b *PermissionBroker) ClaimAgent(agentID string) func(context.Context) int

ClaimAgent atomically removes an Agent's pending permissions from the claimable set and returns their external continuation cleanup. Claiming is bounded and in-memory, so definition commits can make permission retirement visible before publishing a new generation without holding the snapshot lock across backend I/O.

func (*PermissionBroker) Close 

func (b *PermissionBroker) Close(ctx context.Context)

Close rejects late publications, stops expiry scheduling, and drains all records through the same fail-closed continuation path. It is idempotent.

func (*PermissionBroker) DrainAgent 

func (b *PermissionBroker) DrainAgent(ctx context.Context, agentID string) int

func (*PermissionBroker) DrainAll 

func (b *PermissionBroker) DrainAll(ctx context.Context) int

DrainAll claims every pending permission and invokes its backend cleanup.

func (*PermissionBroker) DrainRun 

func (b *PermissionBroker) DrainRun(ctx context.Context, agentID, runID string) int

DrainRun claims every permission for a run and fails each continuation closed.

func (*PermissionBroker) Expire 

func (b *PermissionBroker) Expire(ctx context.Context, agentID, requestID string) error

func (*PermissionBroker) List 

func (b *PermissionBroker) List(agentID string) []PendingPermission

func (*PermissionBroker) LookupPermission 

func (b *PermissionBroker) LookupPermission(requestID string) (PermissionCorrelation, bool)

LookupPermission returns common correlation for a pending or recently claimed opaque request id. Retaining only non-secret identity lets audit paths keep run/session attribution after an atomic winner removes the continuation from the pending set.

func (*PermissionBroker) RecordContinuationLost 

func (b *PermissionBroker) RecordContinuationLost(ctx context.Context, agentID, requestID string)

RecordContinuationLost records that a previously claimed backend continuation could no longer be resumed. It does not recreate claim state.

func (*PermissionBroker) Register 

func (b *PermissionBroker) Register(info PendingPermission, token string, resolver ContinuationResolver) (string, error)

Register publishes a backend continuation that was already stored under token. resolver is retained once per runtime type, never in the claimable record. A failed publication leaves removal of the pre-stored backend token to the caller.

func (*PermissionBroker) Resolve 

func (b *PermissionBroker) Resolve(ctx context.Context, agentID string, decision PermissionDecision) error

type PermissionCapabilities 

type PermissionCapabilities struct {
	Interactive bool                 `json:"interactive"`
	ResumeMode  PermissionResumeMode `json:"resume_mode,omitempty"`
}

type PermissionCorrelation 

type PermissionCorrelation struct {
	RequestID   string
	AgentID     string
	RuntimeType string
	RunID       string
	SessionID   string
}

PermissionCorrelation is the durable, non-secret identity retained while a permission is pending and for the bounded claimed tombstone lifetime.

type PermissionDecision 

type PermissionDecision struct {
	RequestID string                     `json:"request_id"`
	Outcome   string                     `json:"outcome,omitempty"`
	OptionID  string                     `json:"option_id,omitempty"`
	Decisions []PermissionActionDecision `json:"decisions,omitempty"`
}

type PermissionOption 

type PermissionOption struct {
	OptionID string `json:"option_id"`
	Kind     string `json:"kind,omitempty"`
	Name     string `json:"name,omitempty"`
}

type PermissionResolver 

type PermissionResolver interface {
	ResolvePermission(context.Context, agent.Agent, PermissionDecision) error
}

PermissionResolver resolves a permission through the common one-shot broker introduced in M3. Native continuation state never crosses this interface.

type PermissionResumeMode 

type PermissionResumeMode string
const (
	PermissionResumeActiveStream PermissionResumeMode = "active_stream"
	PermissionResumeNewStream    PermissionResumeMode = "new_stream"
)

type PublicErrorPayload 

type PublicErrorPayload struct {
	ErrorType ErrorCode `json:"error_type"`
	Message   string    `json:"message"`
}

func PublicError 

func PublicError(err error) PublicErrorPayload

PublicError returns a fixed safe message for external JSON/SSE responses. Causes and caller-provided normalized messages are deliberately excluded.

type Registry 

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

Registry owns the runtime-type to backend mapping for one AgentGateway. Registrations are expected during bootstrap; lookups are safe concurrently.

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Has 

func (r *Registry) Has(runtimeType string) bool

func (*Registry) Register 

func (r *Registry) Register(backend Backend) error

func (*Registry) RegisterAll 

func (r *Registry) RegisterAll(backends ...Backend) error

RegisterAll validates the whole batch before modifying the registry.

func (*Registry) Resolve 

func (r *Registry) Resolve(runtimeType string) (Backend, error)

Resolve returns the backend registered for runtimeType. Unknown or malformed runtime types fail closed with runtime_not_executable.

func (*Registry) RuntimeTypes 

func (r *Registry) RuntimeTypes() []string

func (*Registry) ValidateRequired 

func (r *Registry) ValidateRequired(runtimeTypes ...string) error

ValidateRequired verifies that every runtime type expected by a caller has a registered backend without requiring all manageable Agent types to be executable.

type RunCanceller 

type RunCanceller interface {
	CancelRun(context.Context, agent.Agent, CancelRequest) (CancelResult, error)
}

RunCanceller performs exact-run cancellation. Unsupported modes must fail with capability_not_supported and must never be silently converted.

type RunInfo 

type RunInfo struct {
	AgentID     string    `json:"agent_id"`
	RuntimeType string    `json:"runtime_type"`
	RunID       string    `json:"run_id"`
	SessionID   string    `json:"session_id,omitempty"`
	State       RunState  `json:"state"`
	StartedAt   time.Time `json:"started_at"`
	FinishedAt  time.Time `json:"finished_at,omitempty"`
	StopReason  string    `json:"stop_reason,omitempty"`
}

RunInfo is the process-local operator view of one Agent run.

type RunRegistry 

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

RunRegistry owns exact-run cancellation and bounded terminal tombstones. It is intentionally process-local; durable business history belongs to an upper-layer workflow engine and correlates its Activity with these run IDs.

func NewRunRegistry 

func NewRunRegistry() *RunRegistry

func (*RunRegistry) Begin 

func (r *RunRegistry) Begin(agentID, runtimeType, runID, sessionID string, cancel func(context.Context, CancelMode) error) error

Begin publishes one active run and its exact backend cancellation binding. A duplicate active or retained run id is rejected fail-closed. Callers that retry one logical execution must allocate a distinct attempt run_id while a prior attempt's tombstone is retained; a durable logical execution key must not be reused as this process-local cancellation identity.

func (*RunRegistry) Cancel 

func (r *RunRegistry) Cancel(ctx context.Context, agentID string, req CancelRequest) (CancelResult, error)

Cancel invokes only the exact active run binding. Retained terminal runs are returned unchanged, making repeated cancellation idempotent.

func (*RunRegistry) CancelAgent 

func (r *RunRegistry) CancelAgent(ctx context.Context, agentID string) error

func (*RunRegistry) Complete 

func (r *RunRegistry) Complete(agentID, runID string, state RunState, stopReason string)

Complete atomically retires an active cancel binding into a terminal tombstone.

func (*RunRegistry) List 

func (r *RunRegistry) List(agentID string) []RunInfo

func (*RunRegistry) Rebind 

func (r *RunRegistry) Rebind(agentID, runtimeType, runID, sessionID string, cancel func(context.Context, CancelMode) error) error

Rebind replaces the native cancel handle when a suspended logical run starts its next transport segment. It never creates a missing or terminal run.

func (*RunRegistry) SetSession 

func (r *RunRegistry) SetSession(agentID, runID, sessionID string)

SetSession records a backend-assigned session id without changing run state.

type RunSequencer 

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

RunSequencer owns ordering across every stream segment of one logical run. Its emission lock deliberately covers the downstream sink call so concurrent backend producers cannot reorder events after sequence allocation.

func NewRunSequencer 

func NewRunSequencer(agentID, runtimeType string) (*RunSequencer, error)

func NewTurnSequencer 

func NewTurnSequencer(ctx context.Context, backend Backend, a agent.Agent, req TurnRequest) (*RunSequencer, error)

NewTurnSequencer creates a fresh run sequencer or restores the cursor owned by a permission continuation. Resume requests fail closed when the selected backend does not own the referenced continuation.

func RestoreRunSequencer 

func RestoreRunSequencer(agentID, runtimeType string, cursor EventCursor) (*RunSequencer, error)

func (*RunSequencer) Cursor 

func (r *RunSequencer) Cursor() EventCursor

func (*RunSequencer) RunID 

func (r *RunSequencer) RunID() string

func (*RunSequencer) ServeSegment 

func (r *RunSequencer) ServeSegment(ctx context.Context, backend Backend, a agent.Agent, req TurnRequest, sink EventSink) (SegmentResult, error)

ServeSegment invokes one backend stream. Backend validation failures before the first event are returned without starting a stream. Once a stream has started, this method guarantees exactly one terminal event.

type RunState 

type RunState string
const (
	RunStateRunning   RunState = "running"
	RunStateCompleted RunState = "completed"
	RunStateCancelled RunState = "cancelled"
	RunStateFailed    RunState = "failed"
)

type RuntimeInspector 

type RuntimeInspector interface {
	RuntimeSummary(context.Context, agent.Agent) (RuntimeSummary, error)
}

type RuntimeState 

type RuntimeState string
const (
	RuntimeStateUnknown       RuntimeState = "unknown"
	RuntimeStateDisabled      RuntimeState = "disabled"
	RuntimeStateNotExecutable RuntimeState = "not_executable"
	RuntimeStateStarting      RuntimeState = "starting"
	RuntimeStateReady         RuntimeState = "ready"
	RuntimeStateDegraded      RuntimeState = "degraded"
	RuntimeStateUnhealthy     RuntimeState = "unhealthy"
)

type RuntimeSummary 

type RuntimeSummary struct {
	Type               string          `json:"type"`
	Executable         bool            `json:"executable"`
	Healthy            bool            `json:"healthy"`
	State              RuntimeState    `json:"state"`
	ActiveRuns         int             `json:"active_runs"`
	PendingPermissions int             `json:"pending_permissions"`
	SessionCount       int             `json:"session_count"`
	LastActivityAt     *time.Time      `json:"last_activity_at,omitempty"`
	Details            json.RawMessage `json:"details,omitempty"`
}

type SegmentResult 

type SegmentResult struct {
	Started  bool
	Terminal bool
}

SegmentResult tells transports whether event emission was attempted and whether terminal emission was attempted. A caller maps Err to a pre-stream HTTP response only when Started is false; once Started is true, the common sequencer owns terminal SSE behavior.

type Session 

type Session struct {
	SessionID string          `json:"session_id"`
	Title     string          `json:"title,omitempty"`
	UpdatedAt *time.Time      `json:"updated_at,omitempty"`
	Details   json.RawMessage `json:"details,omitempty"`
}

type SessionCapabilities 

type SessionCapabilities struct {
	Resume     bool `json:"resume"`
	List       bool `json:"list"`
	Transcript bool `json:"transcript"`
	Durable    bool `json:"durable"`
}

type SessionLister 

type SessionLister interface {
	ListSessions(context.Context, agent.Agent, ListSessionsRequest) (ListSessionsResponse, error)
}

SessionLister is implemented only by backends with an explicit, bounded session-list contract.

type TranscriptLoader 

type TranscriptLoader interface {
	LoadTranscript(context.Context, agent.Agent, TranscriptRequest) (TranscriptResponse, error)
}

TranscriptLoader is implemented only when a backend exposes transcript replay with explicit visibility and bounded response semantics.

type TranscriptMessage 

type TranscriptMessage struct {
	Role string `json:"role"`
	Text string `json:"text"`
}

type TranscriptRequest 

type TranscriptRequest struct {
	SessionID string `json:"session_id"`
	CWD       string `json:"cwd,omitempty"`
}

type TranscriptResponse 

type TranscriptResponse struct {
	SessionID string              `json:"session_id"`
	Messages  []TranscriptMessage `json:"messages"`
}

type TurnCapabilities 

type TurnCapabilities struct {
	Streaming bool `json:"streaming"`
}

type TurnEvent 

type TurnEvent struct {
	Event        string          `json:"-"`
	AgentID      string          `json:"agent_id"`
	RunID        string          `json:"run_id"`
	SessionID    string          `json:"session_id,omitempty"`
	RequestID    string          `json:"request_id,omitempty"`
	Sequence     uint64          `json:"sequence"`
	SegmentIndex uint32          `json:"segment_index"`
	Text         string          `json:"text,omitempty"`
	Data         json.RawMessage `json:"data,omitempty"`
}

TurnEvent is the common event envelope. Event-specific fields, including done/error stop_reason and message values, live in Data rather than parallel envelope fields. The common event sequencer added in M1 owns Sequence and SegmentIndex; backends must not allocate them.

type TurnOptions 

type TurnOptions struct {
	Version   string           `json:"version,omitempty"`
	Runtime   json.RawMessage  `json:"runtime,omitempty"`
	Execution ExecutionOptions `json:"-"`
}

TurnOptions is the versioned options envelope. Execution is trusted, gateway-only metadata and is never decoded from northbound JSON.

type TurnRequest 

type TurnRequest struct {
	RunID      string              `json:"run_id,omitempty"`
	Input      string              `json:"input,omitempty"`
	SessionID  string              `json:"session_id,omitempty"`
	Permission *PermissionDecision `json:"permission,omitempty"`
	Options    TurnOptions         `json:"options,omitempty"`
}

TurnRequest contains only runtime-neutral turn semantics. Runtime-specific northbound options live in Options.Runtime and are decoded strictly by the selected backend.

func DecodeTurnRequest 

func DecodeTurnRequest(r io.Reader) (TurnRequest, error)

DecodeTurnRequest strictly decodes the common northbound turn envelope. Runtime remains opaque until the selected backend decodes it.

Source Files

View all Source files

Directories

Path Synopsis
Package runtimetest provides reusable fake runtime backends for dispatcher and Admin contract tests.
 Package runtimetest provides reusable fake runtime backends for dispatcher and Admin contract tests.

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.