interaction

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

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

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

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

type CompletionDecision struct {
	// Accepted permits completion with the proposed final semantic output.
	Accepted bool
	// Feedback explains a rejection to the model and is empty when accepted.
	Feedback string
}

type CompletionSource string

type CompletionValidator func(candidate CompletionCandidate) (CompletionDecision, error)

type ConcurrentTool interface {
	// ConcurrencyKey classifies one exact JSON argument document before any Tool
	// in the batch executes. concurrent=false requires exclusive execution;
	// concurrent=true with the same non-empty key serializes calls to that
	// resource. The method must be deterministic, bounded, side-effect-free, and
	// must not retain arguments.
	ConcurrencyKey(invocation tool.Invocation) (key string, concurrent bool)
}

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

type DefinitionConfig struct {
	// Name is the stable qualified Definition name.
	Name string

	// Description states the managed behavior for discovery.
	Description string

	// MaxModelCalls bounds model Effects in one Interaction. It must be positive.
	MaxModelCalls uint32

	// Delegates is the frozen model-visible manifest of exact child
	// Deployments. Names must be unique within this slice and must not collide
	// with ordinary Tools bound by the Dispatcher.
	Delegates []Delegate

	// CompletionValidator optionally verifies a proposed final semantic output
	// against the current WorkingContext and accumulated typed Delegate
	// Artifacts. It is a pure Strategy callback whose identity must be covered by
	// the Deployment's ConfigurationDigest. Nil accepts every otherwise valid
	// completion.
	CompletionValidator CompletionValidator
}

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

type DelegateConfig struct {
	// Name is the provider-compatible model Tool name.
	Name string

	// Description tells the model when and why to delegate this work.
	Description string

	// Deployment is the exact child behavior binding. The Delegate retains only
	// its immutable reference and Descriptor schemas.
	Deployment agent.Deployment

	// Budget is permanently allocated from the parent for each invocation.
	Budget agent.Budget

	// Capabilities is the attenuated authority set granted to each child.
	Capabilities agent.CapabilitySet
}

type DirectResultTool interface {
	// ReturnsDirectResult declares whether a successful invocation can terminate
	// Interaction with the ToolResult itself. The answer is read and frozen at
	// Dispatcher construction and therefore must not depend on mutable state or
	// perform I/O.
	ReturnsDirectResult() bool
}

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

type DispatcherConfig struct {
	// Client provides complete and optional streaming model calls.
	Client ModelClient

	// Tools is the frozen ordinary model-visible and executable Tool manifest.
	// Managed Delegate definitions come from the bound Definition.
	Tools []tool.Tool

	// DeferredTools is the frozen ordinary executable Tool set omitted from the
	// initial model manifest. An executing Tool may make exact names visible on
	// later model calls through AdvertiseTools; authority never changes.
	DeferredTools []tool.Tool

	// MaxConcurrentToolCalls bounds calls that explicitly declare safe overlap.
	// Zero preserves serial execution; negative values are invalid. Undeclared
	// calls and calls with the same non-empty concurrency key remain serial.
	MaxConcurrentToolCalls int

	// StreamModelResponses selects Client.Stream and publishes each validated
	// response chunk as a best-effort ModelResponseDelta. False uses Client.Call.
	StreamModelResponses bool

	// Observer receives exact settled Interaction facts. It is intentionally
	// separate from Engine Events/Deltas: those describe execution mechanics,
	// while this boundary exposes typed model and Tool semantics.
	Observer ExecutionObserver

	// ModelContextReducer optionally replaces only the provider-neutral message
	// context at the last safe boundary before each model call. The Dispatcher
	// installs the effective messages back into Interaction recovery state when
	// the call settles, so later calls and checkpoints cannot regrow a reduced
	// context from the pre-reduction Effect payload.
	ModelContextReducer ModelContextReducer
}

type ExecutionObserver interface {
	// OnModelResponse receives the complete provider-neutral response after the
	// model boundary settles and before later Interaction work is observed. The
	// response is detached and may be mutated by the observer. Panics are
	// isolated and the callback has no control authority.
	OnModelResponse(ctx context.Context, invocation ModelInvocation, response *chat.Response)
	// OnToolStarted marks the actual external Tool-call boundary; it is not
	// emitted for calls rejected before execution. Concurrently authorized Tool
	// calls may invoke this method in parallel.
	OnToolStarted(ctx context.Context, invocation ToolInvocation)
	// OnToolSettled receives exactly one conclusive or unknown host-boundary
	// outcome for a started Tool call. The ToolResult, when present, is detached;
	// the callback cannot alter the value committed to Interaction state.
	OnToolSettled(ctx context.Context, invocation ToolInvocation, settlement ToolSettlement)
}

type Input struct {
	// Messages is the initial provider-neutral WorkingContext.
	Messages []chat.Message `json:"messages"`

	// Options contains request-specific generation overrides.
	Options chat.Options `json:"options,omitzero"`
}

type ModelClient interface {
	// Call invokes the configured model for one complete response.
	Call(ctx context.Context, request *chat.Request) (*chat.Response, error)
	// Stream invokes the configured model as a lazy response sequence.
	Stream(ctx context.Context, request *chat.Request) iter.Seq2[*chat.Response, error]
}

type ModelContextReducer interface {
	// ReduceModelContext returns the complete messages for the attributed model
	// invocation. The result must be non-empty, valid, and independently owned.
	ReduceModelContext(
		ctx context.Context,
		invocation ModelInvocation,
		request *chat.Request,
	) ([]chat.Message, error)
}

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

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

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

type Output struct {
	// Source identifies which mutually exclusive result field is authoritative.
	Source CompletionSource `json:"source"`

	// ModelResponse is the authoritative accumulated response when Source is
	// CompletionSourceModelResponse.
	ModelResponse *chat.Response `json:"model_response,omitempty"`

	// DirectToolResults preserves model ToolCall order when Source is
	// CompletionSourceDirectToolResults.
	DirectToolResults []chat.ToolResult `json:"direct_tool_results,omitempty"`

	// ModelCalls is the number of model Effects issued by this Interaction.
	ModelCalls uint32 `json:"model_calls"`
}

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

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

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

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

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

type ToolSettlement struct {
	// Result is the exact ordinary Tool result fed back to the model.
	Result *chat.ToolResult
	// InputRequired reports that the Tool paused before producing Result.
	InputRequired bool
	// Failure describes a host or cancellation failure that produced no Result.
	Failure string
	// Unknown reports that the external Tool settlement could not be determined.
	Unknown bool
}