runtime

type Backend interface {
	// Kind returns the backend kind identifier.
	Kind() BackendKind

	// Execute runs code with the given request parameters.
	// It validates the request, executes the code, and returns the result.
	Execute(ctx context.Context, req ExecuteRequest) (ExecuteResult, error)
}

type BackendContract struct {
	// NewBackend creates a fresh backend instance for testing.
	NewBackend func() Backend

	// NewGateway creates a gateway for testing.
	// The gateway should allow at least basic tool operations.
	NewGateway func() ToolGateway

	// ExpectedKind is the BackendKind the backend should return.
	ExpectedKind BackendKind

	// SkipExecutionTests skips tests that require actual code execution.
	// Useful for backends that need complex setup (e.g., Docker).
	SkipExecutionTests bool
}

type BackendInfo struct {
	// Kind identifies the type of backend.
	Kind BackendKind

	// Details contains backend-specific information.
	Details map[string]any
}

type BackendKind string

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

type ExecuteRequest struct {
	// Language specifies the programming language of the code.
	// If empty, the backend's default language is used.
	Language string

	// Code is the source code to execute.
	// Required.
	Code string

	// Timeout specifies the maximum duration for execution.
	// If zero, the backend's default timeout is used.
	Timeout time.Duration

	// Limits specifies resource limits for execution.
	Limits Limits

	// Profile specifies the security profile to use.
	// If empty, the runtime's default profile is used.
	Profile SecurityProfile

	// Gateway is the tool gateway exposed to the executed code.
	// Required.
	Gateway ToolGateway

	// Metadata contains arbitrary metadata for the execution.
	Metadata map[string]any
}

type ExecuteResult struct {
	// Value is the final result of the code execution.
	// Typically captured via the __out variable convention.
	Value any

	// Stdout contains any output written to stdout.
	Stdout string

	// Stderr contains any output written to stderr.
	Stderr string

	// ToolCalls records all tool invocations made during execution.
	ToolCalls []ToolCallRecord

	// Duration is the total execution time.
	Duration time.Duration

	// Backend contains information about the backend that executed the code.
	Backend BackendInfo

	// LimitsEnforced reports which limits the backend was able to enforce.
	// Backends that cannot enforce a given limit should set that field to false.
	// This allows callers to know when limits degraded gracefully.
	LimitsEnforced LimitsEnforced
}

type GatewayContract struct {
	// NewGateway creates a fresh gateway instance for testing.
	// The gateway should be configured with at least one tool for search/describe tests.
	NewGateway func() ToolGateway
}

type Limits struct {
	// MaxToolCalls limits the number of tool invocations.
	// Zero means unlimited.
	MaxToolCalls int

	// MaxChainSteps limits the number of steps in a tool chain.
	// Zero means unlimited.
	MaxChainSteps int

	// CPUQuotaMillis limits CPU time in milliseconds.
	// Zero means unlimited.
	CPUQuotaMillis int64

	// MemoryBytes limits memory usage in bytes.
	// Zero means unlimited.
	MemoryBytes int64

	// PidsMax limits the number of processes/threads.
	// Zero means unlimited.
	PidsMax int64

	// DiskBytes limits disk usage in bytes.
	// Zero means unlimited.
	DiskBytes int64
}

type LimitsEnforced struct {
	// Timeout indicates whether the timeout was enforced.
	Timeout bool

	// ToolCalls indicates whether tool call limits were enforced.
	ToolCalls bool

	// ChainSteps indicates whether chain step limits were enforced.
	ChainSteps bool

	// Memory indicates whether memory limits were enforced.
	Memory bool

	// CPU indicates whether CPU limits were enforced.
	CPU bool

	// Pids indicates whether process limits were enforced.
	Pids bool

	// Disk indicates whether disk limits were enforced.
	Disk bool
}

type Logger interface {
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

type Runtime interface {
	// Execute runs code with the given request parameters.
	// It selects the appropriate backend based on the security profile
	// and delegates execution.
	Execute(ctx context.Context, req ExecuteRequest) (ExecuteResult, error)
}

type RuntimeConfig struct {
	// Backends maps security profiles to their backend implementations.
	Backends map[SecurityProfile]Backend

	// DenyUnsafeProfiles lists profiles that cannot use the unsafe backend.
	// If a profile is listed here and only the unsafe backend is available,
	// execution will be denied.
	DenyUnsafeProfiles []SecurityProfile

	// DefaultProfile is the profile to use when none is specified in the request.
	// If empty and no profile is specified, execution will fail.
	DefaultProfile SecurityProfile

	// Logger is an optional logger for runtime events.
	Logger Logger
}

type RuntimeError struct {
	// Err is the underlying error.
	Err error

	// Op is the operation that failed (e.g., "execute", "container_create").
	Op string

	// Backend is the backend kind that was in use when the error occurred.
	Backend BackendKind

	// Retryable indicates whether the operation can be retried.
	// True for transient errors like timeouts; false for policy violations.
	Retryable bool
}

type SecurityProfile string

type ToolCallRecord struct {
	// ToolID is the canonical identifier of the tool that was called.
	ToolID string

	// BackendKind indicates which backend executed the tool.
	BackendKind string

	// Duration is the execution time for this tool call.
	Duration time.Duration

	// ErrorOp indicates the operation that failed, if any.
	ErrorOp string
}

type ToolGateway interface {
	// SearchTools searches for tools matching the query.
	SearchTools(ctx context.Context, query string, limit int) ([]index.Summary, error)

	// ListNamespaces returns all available tool namespaces.
	ListNamespaces(ctx context.Context) ([]string, error)

	// DescribeTool returns documentation for a tool at the specified detail level.
	DescribeTool(ctx context.Context, id string, level tooldoc.DetailLevel) (tooldoc.ToolDoc, error)

	// ListToolExamples returns up to maxExamples usage examples for a tool.
	ListToolExamples(ctx context.Context, id string, maxExamples int) ([]tooldoc.ToolExample, error)

	// RunTool executes a single tool and returns the result.
	RunTool(ctx context.Context, id string, args map[string]any) (run.RunResult, error)

	// RunChain executes a sequence of tool calls.
	RunChain(ctx context.Context, steps []run.ChainStep) (run.RunResult, []run.StepResult, error)
}