agentruntime

type AcquireExecutionRequest struct {
	Execution  OperationExecutionRecord
	Transition OperationExecutionTransition
}

type AcquireExecutionResult struct {
	Execution   OperationExecutionRecord
	Disposition ExecutionAcquireDisposition
}

type ApprovalDecision struct {
	ID       string `json:"id,omitempty"`
	Approved bool   `json:"approved"`
	Pending  bool   `json:"pending,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

type ApprovalRequest struct {
	Operation   OperationRequest
	Reason      string
	ResponseID  string
	ModelOutput []ModelOutputItem
	Preview     json.RawMessage
}

type ApprovalResume struct {
	ID          string
	ExecutionID string
	Operation   string
	Call        ToolCall
	ResponseID  string
	ModelOutput []ModelOutputItem
	Preview     json.RawMessage
	Pending     bool
	Approved    bool
	Reason      string
}

type ApprovalResumer interface {
	ResumeApproval(ctx context.Context, runID string) (*ApprovalResume, error)
}

type Approver interface {
	RequestApproval(ctx context.Context, req ApprovalRequest) (ApprovalDecision, error)
}

type ApproverFunc func(ctx context.Context, req ApprovalRequest) (ApprovalDecision, error)

type BeginRunRequest struct {
	Run      RunRecord
	LeaseID  string
	LeaseTTL time.Duration
}

type BeginRunResult struct {
	Handle  RunHandle
	Session *SessionState
}

type ConfirmationMode string

type ConfirmationSpec struct {
	Mode        ConfirmationMode `json:"mode"`
	Description string           `json:"description,omitempty"`
}

type ContextCheckpoint struct {
	Version               int            `json:"version"`
	Summary               ContextSummary `json:"summary"`
	CompactedItemCount    int            `json:"compacted_item_count"`
	SourceSessionRevision uint64         `json:"source_session_revision"`
	UpdatedAt             time.Time      `json:"updated_at"`
}

type ContextCompactionRequest struct {
	Checkpoint            *ContextCheckpoint `json:"checkpoint,omitempty"`
	Items                 []ModelInputItem   `json:"items"`
	SourceSessionRevision uint64             `json:"source_session_revision"`
	MaxCheckpointTokens   int                `json:"max_checkpoint_tokens"`
}

type ContextCompactor interface {
	Compact(ctx context.Context, request ContextCompactionRequest) (ContextSummary, error)
}

type ContextSummary struct {
	Summary     string   `json:"summary"`
	Facts       []string `json:"facts,omitempty"`
	Decisions   []string `json:"decisions,omitempty"`
	Constraints []string `json:"constraints,omitempty"`
	OpenItems   []string `json:"open_items,omitempty"`
}

type ContextWindowConfig struct {
	MaxContextTokens        int
	ReservedOutputTokens    int
	CompactionTriggerTokens int
	CompactionTargetTokens  int
	MaxCheckpointTokens     int
	PreserveRecentTurns     int
	TokenCounter            TokenCounter
	ContextCompactor        ContextCompactor
}

type Event struct {
	Type            EventType         `json:"type"`
	RunID           string            `json:"run_id"`
	SessionID       string            `json:"session_id,omitempty"`
	MCPServer       string            `json:"mcp_server,omitempty"`
	MCPVersion      string            `json:"mcp_version,omitempty"`
	MCPProtocol     string            `json:"mcp_protocol,omitempty"`
	MCPToolCount    int               `json:"mcp_tool_count,omitempty"`
	Operation       string            `json:"operation,omitempty"`
	ModelCallID     string            `json:"model_call_id,omitempty"`
	RequestID       string            `json:"request_id,omitempty"`
	PlanBatch       uint64            `json:"plan_batch"`
	CallID          string            `json:"call_id,omitempty"`
	ExecutionID     string            `json:"execution_id,omitempty"`
	ApprovalID      string            `json:"approval_id,omitempty"`
	ApprovalPreview json.RawMessage   `json:"approval_preview,omitempty"`
	AttemptID       string            `json:"attempt_id,omitempty"`
	ResponseID      string            `json:"response_id,omitempty"`
	Text            string            `json:"text,omitempty"`
	InputTokens     int               `json:"input_tokens,omitempty"`
	CompactedItems  int               `json:"compacted_items,omitempty"`
	Chunk           *ModelStreamEvent `json:"chunk,omitempty"`
	// Data is trusted audit payload and never crosses the default JSON boundary.
	Data      json.RawMessage `json:"-"`
	ErrorCode string          `json:"error_code,omitempty"`
	Error     string          `json:"-"`
}

type EventSink func(Event)

type EventType string

type ExecutionAcquireDisposition string

type ExecutionStore interface {
	ReservePlanBatch(ctx context.Context, batch OperationPlanBatch) (PlanBatchReservation, error)
	SealPlan(ctx context.Context, seal OperationPlanSeal) (PlanSealResult, error)
	AcquireExecution(ctx context.Context, request AcquireExecutionRequest) (AcquireExecutionResult, error)
	ValidateExecutionAttempt(ctx context.Context, executionID, attemptID string) error
	TransitionExecution(ctx context.Context, transition OperationExecutionTransition) (OperationExecutionRecord, error)
	GetExecution(ctx context.Context, executionID string) (OperationExecutionRecord, error)
	ListExecutionTransitions(ctx context.Context, executionID string) ([]OperationExecutionTransition, error)
}

type FinishRunRequest struct {
	Handle          RunHandle
	Run             RunRecord
	Session         *SessionState
	PendingApproval *PendingApprovalCommit
}

type ImageAttachmentResolver interface {
	// Retryable infrastructure failures must wrap ErrRunInterrupted. Confirmed
	// expiry or deletion must wrap ErrImageAttachmentUnavailable.
	ResolveImageAttachment(ctx context.Context, attachment ModelInputAttachment) (ModelInputAttachment, error)
}

type ImageAttachmentResolverFunc func(context.Context, ModelInputAttachment) (ModelInputAttachment, error)

type Input struct {
	// RunID is an optional trusted host-assigned identifier. Durable hosts that
	// enqueue work before execution use it to keep the HTTP, queue, store, and
	// event identities aligned. It is intentionally excluded from JSON input so
	// callers cannot smuggle an arbitrary run identity through an API payload.
	RunID     string `json:"-"`
	User      string `json:"user"`
	SessionID string `json:"session_id,omitempty"`
	// IdempotencyKey identifies one logical user request. Callers must reuse it
	// when retrying a request that may execute write operations.
	IdempotencyKey string `json:"idempotency_key,omitempty"`
	// IdempotencyScope isolates stateless write keys by trusted tenant or
	// principal. It is required for write operations without a SessionID.
	IdempotencyScope string                 `json:"idempotency_scope,omitempty"`
	Attachments      []ModelInputAttachment `json:"attachments,omitempty"`
	Metadata         map[string]any         `json:"metadata,omitempty"`
	// ImageAttachmentResolver is a trusted, Run-scoped dependency used to
	// materialize transient URLs for historical image attachments. It is never
	// accepted from callers or persisted with the Run input.
	ImageAttachmentResolver ImageAttachmentResolver `json:"-"`
	// TrustedContext is host-authored, current external state that must be
	// available to the model for this Run but must not be accepted from API
	// callers or persisted as a user-authored transcript message.
	TrustedContext string `json:"-"`
}

type ItemRecord struct {
	ID             string
	RunID          string
	SessionID      string
	Type           ItemType
	ModelCallID    string
	ResponseID     string
	ProviderItemID string
	RequestID      string
	PlanBatch      uint64
	CallID         string
	ExecutionID    string
	AttemptID      string
	Name           string
	Data           json.RawMessage
	Error          string
	CreatedAt      time.Time
}

type ItemType string

type MCPServerInfo struct {
	Name            string
	Version         string
	ProtocolVersion string
}

type Model interface {
	Complete(ctx context.Context, req ModelRequest) (*ModelResponse, error)
}

type ModelInputAttachment struct {
	Kind       ModelInputAttachmentKind `json:"kind"`
	ID         string                   `json:"id"`
	Filename   string                   `json:"filename"`
	MIMEType   string                   `json:"mime_type"`
	StorageKey string                   `json:"storage_key,omitempty"`
	ExpiresAt  time.Time                `json:"expires_at,omitzero"`
	// URL is materialized for one model request and must never be persisted in
	// a Session transcript. Durable hosts provide StorageKey and ExpiresAt so a
	// later Run can resolve a fresh URL or explicitly retire unavailable history.
	URL string `json:"-"`
	// CurrentRun is set by Runtime on the current user turn. Persisted history
	// always clears it so unavailable history can be handled without weakening
	// fail-fast semantics for the user's current attachment choice.
	CurrentRun bool   `json:"-"`
	Text       string `json:"text,omitempty"`
}

type ModelInputAttachmentKind string

type ModelInputItem struct {
	Type        ModelInputItemType     `json:"type"`
	Text        string                 `json:"text,omitempty"`
	Attachments []ModelInputAttachment `json:"attachments,omitempty"`
	OutputType  ModelOutputItemType    `json:"output_type,omitempty"`
	Raw         json.RawMessage        `json:"raw,omitempty"`
	CallID      string                 `json:"call_id,omitempty"`
	Output      json.RawMessage        `json:"output,omitempty"`
}

type ModelInputItemType string

type ModelOutputItem struct {
	ID   string              `json:"id,omitempty"`
	Type ModelOutputItemType `json:"type"`
	Text string              `json:"text,omitempty"`
	Call *ToolCall           `json:"call,omitempty"`
	Raw  json.RawMessage     `json:"raw,omitempty"`
}

type ModelOutputItemType string

type ModelRequest struct {
	Instructions string           `json:"instructions"`
	Input        []ModelInputItem `json:"input"`
	Tools        []ToolDefinition `json:"tools,omitempty"`
	// ModelCallID is assigned by Runtime immediately before Complete. Model
	// decorators may use it for idempotent metering or provider attribution;
	// transports must not serialize it into the provider request.
	ModelCallID string `json:"-"`
	// DisableReasoning asks adapters with an explicit thinking mode to turn it
	// off for this call. Runtime uses it only for the single corrective retry
	// after a reasoning-only response.
	DisableReasoning bool `json:"disable_reasoning,omitempty"`
	// ToolSetID is reserved for Runtime's content hash. Direct model callers
	// should leave it empty; OpenAIModel rejects IDs that do not match Tools.
	ToolSetID  string          `json:"tool_set_id,omitempty"`
	StreamSink ModelStreamSink `json:"-"`
}

type ModelResponse struct {
	ID           string            `json:"id"`
	OutputText   string            `json:"output_text,omitempty"`
	Refusal      string            `json:"refusal,omitempty"`
	Items        []ModelOutputItem `json:"items"`
	FinishReason string            `json:"finish_reason,omitempty"`
	HadReasoning bool              `json:"had_reasoning,omitempty"`
	Usage        Usage             `json:"usage"`
}

type ModelStreamEvent struct {
	Type           ModelStreamEventType `json:"type"`
	ProviderType   string               `json:"provider_type,omitempty"`
	ModelCallID    string               `json:"model_call_id,omitempty"`
	SequenceNumber *int64               `json:"sequence_number,omitempty"`
	ItemID         string               `json:"item_id,omitempty"`
	OutputIndex    *int64               `json:"output_index,omitempty"`
	ResponseID     string               `json:"response_id,omitempty"`
	CallID         string               `json:"call_id,omitempty"`
	Name           string               `json:"name,omitempty"`
	Phase          string               `json:"phase,omitempty"`
	Delta          string               `json:"delta,omitempty"`
	Arguments      string               `json:"arguments,omitempty"`
	ErrorCode      string               `json:"error_code,omitempty"`
	ErrorMessage   string               `json:"-"`
	RawJSON        string               `json:"-"`
}

type ModelStreamEventType string

type ModelStreamSink func(ModelStreamEvent)

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

type OpenAIModelConfig struct {
	APIKey    string
	BaseURL   string
	Model     string
	UserAgent string
	Reasoning *OpenAIReasoningConfig
}

type OpenAIReasoningConfig struct {
	Effort  OpenAIReasoningEffort
	Summary OpenAIReasoningSummary
}

type OpenAIReasoningEffort string

type OpenAIReasoningSummary string

type Operation struct {
	Name string
	// PreviousNames are accepted only when replaying persisted model transcript
	// items after an operation rename. They are never registered as executable
	// operation names or exposed as current tools to the model.
	PreviousNames []string
	Description   string
	InputSchema   json.RawMessage
	OutputSchema  json.RawMessage
	// NormalizeInput canonicalizes schema-validated arguments before execution
	// IDs, durable plans, approval previews, and executions are created. It must
	// not mutate its input and its result is validated again.
	NormalizeInput func(arguments any) (any, error)
	Effect         OperationEffect
	Capabilities   []string
	Confirmation   ConfirmationSpec
	// ApprovalPreview builds a safe, operation-specific JSON object from
	// schema-validated arguments. Raw arguments never cross the browser trust
	// boundary; writes that require confirmation must provide one so a policy
	// can safely route them through approval.
	ApprovalPreview func(arguments any) (json.RawMessage, error)
	// Terminal ends the current agent turn after this operation completes
	// successfully, or after every call in an allowed homogeneous terminal batch
	// completes. The executor must return FinalResponse for each call.
	Terminal bool
	// TerminalBatchLimit permits 2..N homogeneous calls to this terminal write
	// operation in one model turn. Zero preserves the default single-call rule.
	// Runtime still plans, fences, executes, validates, and persists every call
	// independently before completing the turn with their combined artifacts.
	TerminalBatchLimit int
}

type OperationEffect string

type OperationExecutionRecord struct {
	ID               string
	IdempotencyKey   string
	IdempotencyScope string
	RunID            string
	SessionID        string
	CallID           string
	AttemptID        string
	Name             string
	Arguments        json.RawMessage
	Status           OperationExecutionStatus
	Result           OperationResult
	Verification     *VerificationResult
	Error            string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

type OperationExecutionStatus string

type OperationExecutionTransition struct {
	ID           string
	ExecutionID  string
	AttemptID    string
	RunID        string
	CallID       string
	Actor        string
	Message      string
	From         OperationExecutionStatus
	To           OperationExecutionStatus
	Result       OperationResult
	Verification *VerificationResult
	Evidence     json.RawMessage
	CreatedAt    time.Time
}

type OperationExecutor interface {
	Execute(ctx context.Context, req OperationRequest) (OperationResult, error)
}

type OperationExecutorFunc func(ctx context.Context, req OperationRequest) (OperationResult, error)

type OperationPlanBatch struct {
	RequestID        string
	SessionID        string
	IdempotencyKey   string
	IdempotencyScope string
	Index            uint64
	Steps            []OperationPlanStep
	CreatedAt        time.Time
}

type OperationPlanSeal struct {
	RequestID        string
	SessionID        string
	IdempotencyKey   string
	IdempotencyScope string
	BatchCount       uint64
	SealedAt         time.Time
}

type OperationPlanStep struct {
	ExecutionID string
	Name        string
	Arguments   json.RawMessage
}

type OperationPolicy interface {
	Evaluate(ctx context.Context, req OperationRequest) (PolicyDecision, error)
}

type OperationPolicyFunc func(ctx context.Context, req OperationRequest) (PolicyDecision, error)

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

type OperationReconciliationAction string

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

type OperationRequest struct {
	RunID     string
	SessionID string
	// ExecutionID is stable for one write operation in the persisted request
	// plan, or for one terminal read operation that produces a durable artifact.
	// Write executors must enforce it at their own side-effect boundary.
	ExecutionID string
	// AttemptID fences the current execution owner. Executors that coordinate
	// retries must reject stale attempts before mutating state.
	AttemptID string
	// SessionLease is the fencing token for the session owner. Write executors
	// must validate its generation atomically at their side-effect boundary.
	SessionLease SessionLeaseFence
	Input        Input
	Operation    OperationSummary
	Call         ToolCall
	// Arguments may contain nil for properties that are optional in InputSchema:
	// strict tool schemas encode omission as an explicit JSON null.
	Arguments any
}

type OperationResult struct {
	Output        json.RawMessage  `json:"output"`
	Receipt       json.RawMessage  `json:"receipt,omitempty"`
	FinalResponse string           `json:"final_response,omitempty"`
	Artifacts     []ResultArtifact `json:"artifacts,omitempty"`
	// Continue lets a terminal read operation return a successful,
	// schema-validated correction result to the model without completing the
	// Run. It is only valid when no final response, receipt, or artifacts were
	// produced.
	Continue bool `json:"continue,omitempty"`
}

type OperationSummary struct {
	Name               string           `json:"name"`
	PreviousNames      []string         `json:"-"`
	Description        string           `json:"description,omitempty"`
	InputSchema        json.RawMessage  `json:"input_schema"`
	OutputSchema       json.RawMessage  `json:"output_schema"`
	Effect             OperationEffect  `json:"effect"`
	Capabilities       []string         `json:"capabilities,omitempty"`
	Confirmation       ConfirmationSpec `json:"confirmation"`
	Terminal           bool             `json:"terminal,omitempty"`
	TerminalBatchLimit int              `json:"terminal_batch_limit,omitempty"`
}

type PendingApprovalCommit struct {
	Request  ApprovalRequest
	Decision ApprovalDecision
	Audit    ItemRecord
}

type PlanBatchReservation struct {
	Batch   OperationPlanBatch
	Created bool
}

type PlanSealResult struct {
	Seal    OperationPlanSeal
	Created bool
}

type PolicyAction string

type PolicyDecision struct {
	Action PolicyAction
	Reason string
}

type ReconcileOperationRequest struct {
	ExecutionID       string
	ExpectedAttemptID string
	Action            OperationReconciliationAction
	Result            OperationResult
	Actor             string
	Message           string
	Evidence          json.RawMessage
}

type RenewRunLeaseRequest struct {
	Handle   RunHandle
	LeaseTTL time.Duration
}

type Result struct {
	RunID          string
	SessionID      string
	Status         RunStatus
	LastResponseID string
	Output         string
}

type ResultArtifact struct {
	Type           string          `json:"type"`
	Data           json.RawMessage `json:"data"`
	InternalData   json.RawMessage `json:"internal_data,omitempty"`
	SessionSummary json.RawMessage `json:"session_summary,omitempty"`
}

type ResultVerifier interface {
	Verify(ctx context.Context, req VerificationRequest) (VerificationResult, error)
}

type ResultVerifierFunc func(ctx context.Context, req VerificationRequest) (VerificationResult, error)

type RunHandle struct {
	RunID           string
	SessionID       string
	LeaseID         string
	LeaseGeneration uint64
	LeaseDeadline   time.Time
	SessionRevision uint64
}

type RunRecord struct {
	ID        string
	SessionID string
	Status    RunStatus
	Input     Input
	Result    string
	Artifacts []ResultArtifact
	ErrorCode string
	Error     string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type RunStatus string

type RunStore interface {
	BeginRun(ctx context.Context, request BeginRunRequest) (BeginRunResult, error)
	RenewRunLease(ctx context.Context, request RenewRunLeaseRequest) (RunHandle, error)
	ValidateRunLease(ctx context.Context, handle RunHandle) (RunHandle, error)
	AppendItem(ctx context.Context, item ItemRecord) error
	FinishRun(ctx context.Context, request FinishRunRequest) error
}

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

type RuntimeConfig struct {
	Model           Model
	Operations      *OperationRegistry
	MCPInstructions string
	Policy          OperationPolicy
	Executor        OperationExecutor
	Verifier        ResultVerifier
	Approver        Approver
	ApprovalResumer ApprovalResumer
	RunStore        RunStore
	Executions      ExecutionStore
	EventSink       EventSink
	ContextWindow   *ContextWindowConfig

	MaxIterations        int
	SessionLeaseTTL      time.Duration
	LeaseRenewalInterval time.Duration
	CleanupTimeout       time.Duration
	Now                  func() time.Time
	NewID                func() string
}

type SessionLeaseFence struct {
	RunID           string
	SessionID       string
	LeaseID         string
	Generation      uint64
	Deadline        time.Time
	SessionRevision uint64
}

type SessionState struct {
	ID             string
	Revision       uint64
	Transcript     []ModelInputItem
	Checkpoint     *ContextCheckpoint
	SeenCallIDs    []string
	LastResponseID string
	LastRunID      string
	LastError      string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type TokenCounter interface {
	CountModelRequest(ctx context.Context, request ModelRequest) (int, error)
	CountText(ctx context.Context, text string) (int, error)
}

type ToolCall struct {
	ID    string          `json:"id"`
	Name  string          `json:"name"`
	Input json.RawMessage `json:"input"`
}

type ToolDefinition struct {
	Name          string          `json:"name"`
	PreviousNames []string        `json:"-"`
	Description   string          `json:"description,omitempty"`
	InputSchema   json.RawMessage `json:"input_schema"`
}

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

type VerificationRequest struct {
	Operation OperationRequest
	Result    OperationResult
	Output    any
}

type VerificationResult struct {
	Confirmed bool            `json:"confirmed"`
	Message   string          `json:"message,omitempty"`
	Evidence  json.RawMessage `json:"evidence,omitempty"`
}