interaction

Documentation

Overview

Package interaction owns UI-neutral request, response, and broker SPIs.

@import { NamedInterface } from "github.com/spice-framework/spice/annotation/modulith" @NamedInterface("interaction")

Index

• Constants
• type Broker
• type ID
• type Request
  • func NewRequest(id ID, kind, prompt string, schema json.RawMessage) (Request, error)
  • func (request Request) Clone() Request
  • func (request Request) ID() ID
  • func (request Request) Kind() string
  • func (request Request) Prompt() string
  • func (request Request) Schema() json.RawMessage
  • func (request Request) Validate() error
• type Requester
• type Response
  • func NewResponse(id ID, value json.RawMessage) (Response, error)
  • func (response Response) Clone() Response
  • func (response Response) ID() ID
  • func (response Response) Validate() error
  • func (response Response) Value() json.RawMessage
• type Scope
  • func NewScope(runID string) (Scope, error)
  • func (scope Scope) RunID() string
  • func (scope Scope) Validate() error
• type UnavailableBroker
  • func (UnavailableBroker) Request(context.Context, Scope, Request) (Response, error)
• type UnavailableRequester
  • func (UnavailableRequester) Request(context.Context, Request) (Response, error)

Constants

const MaximumPayloadBytes = 512 << 10

Types

type Broker

type Broker interface {
	Request(context.Context, Scope, Request) (Response, error)
}

Broker is the UI-neutral user-interaction port injected into the engine. Implementations must be concurrent-safe and cooperatively honor context.

type ID

type ID string

ID identifies one interaction lifecycle.

type Request

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

Request asks an injected broker for typed user input.

func NewRequest

func NewRequest(id ID, kind, prompt string, schema json.RawMessage) (Request, error)

NewRequest validates and defensively copies one interaction request.

func (Request) Clone

func (request Request) Clone() Request

func (Request) ID

func (request Request) ID() ID

func (Request) Kind

func (request Request) Kind() string

func (Request) Prompt

func (request Request) Prompt() string

func (Request) Schema

func (request Request) Schema() json.RawMessage

func (Request) Validate

func (request Request) Validate() error

type Requester

type Requester interface {
	Request(context.Context, Request) (Response, error)
}

Requester is a run-bound interaction lifecycle capability. Unlike Broker it accepts no caller-supplied Scope; the owner fixes run authority at binding.

type Response

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

Response completes one interaction with structured user input.

func NewResponse

func NewResponse(id ID, value json.RawMessage) (Response, error)

NewResponse validates and defensively copies one response.

func (Response) Clone

func (response Response) Clone() Response

func (Response) ID

func (response Response) ID() ID

func (Response) Validate

func (response Response) Validate() error

func (Response) Value

func (response Response) Value() json.RawMessage

type Scope

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

Scope identifies the immutable run authority that owns an interaction. Brokers use it to route pending requests without depending on agent internals.

func NewScope

func NewScope(runID string) (Scope, error)

NewScope constructs a validated interaction scope.

func (Scope) RunID

func (scope Scope) RunID() string

RunID returns the stable run that owns the interaction.

func (Scope) Validate

func (scope Scope) Validate() error

Validate rejects a zero or malformed scope.

type UnavailableBroker

type UnavailableBroker struct{}

UnavailableBroker is the fail-closed fallback when no client owns prompts.

func (UnavailableBroker) Request

func (UnavailableBroker) Request(context.Context, Scope, Request) (Response, error)

type UnavailableRequester

type UnavailableRequester struct{}

UnavailableRequester is a fail-closed capability for direct dispatcher tests and embeddings that deliberately provide no run interaction lifecycle.

func (UnavailableRequester) Request

func (UnavailableRequester) Request(context.Context, Request) (Response, error)

Request always fails without observing request payload data.