tools

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

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

type OutputCapture struct {
	// Bytes is the total size of the output stream, regardless of Truncated.
	Bytes int64
	// Preview is a truncated prefix of the output stream, or nil if not captured
	// (e.g. stdout on a successful call) or empty.
	Preview *string
	// Truncated indicates whether Preview was cut short of the full output.
	Truncated bool
}

type TextOrData interface {
	~string | ~[]byte
}

type ToolCallContext struct {
	// CallID is the provider's own identifier for this tool call, if the provider's API
	// assigns one (e.g. OpenAI/Anthropic/DeepSeek/Mistral AI/xAI's tool_call/tool_use ID).
	// Reusing the provider's own ID - rather than minting an unrelated one - means this same
	// ID can also be found in any API error message that references the call. If empty,
	// ExecuteTool generates one internally (a ULID) instead, so ToolCallSummary.CallID is
	// never empty; note this means CallID's shape/format varies depending on whether - and
	// how - the calling provider assigns its own IDs.
	CallID string
	// ConversationTurn is the 1-based conversation turn this call is being made during, or 0
	// if unknown/not applicable.
	ConversationTurn int
}

type ToolCallSummary struct {
	// Tool is the name of the tool this call invoked.
	Tool string
	// CallID is a unique identifier (ULID) for this call. It is also included in the
	// prefix of every log line emitted while this call was in progress, so a specific
	// invocation can be correlated between this summary and the corresponding log lines.
	CallID string
	// ConversationTurn is the 1-based conversation turn this call was made during, or 0 if
	// unknown/not provided by the caller.
	ConversationTurn int
	// StartedAt is when this call began (start of setup, before the container ever runs).
	StartedAt time.Time
	// CompletedAt is when this call finished, successfully or not.
	CompletedAt time.Time
	// DurationNs is the wall-clock duration of the container's runtime (start through exit),
	// the same measurement window as the aggregate ToolUsage.TotalDurationNs. It does not
	// include setup (argument parsing, mounts, container creation) or teardown overhead, and
	// stays nil when no container process ever ran (e.g. an infrastructure_error during setup).
	DurationNs *int64
	// WallTimeNs is the wall-clock duration of the entire call attempt, from setup
	// through output retrieval - i.e. DurationNs plus setup/teardown overhead. Unlike
	// DurationNs, this is always set, even for calls whose container never ran.
	WallTimeNs int64
	// ExitCode is the container's exit code, or nil if no exit code is known (e.g. setup never
	// reached container start, or the run was aborted/cancelled before it could be observed).
	ExitCode *int64
	// TimedOut indicates the call was aborted due to exceeding its configured timeout.
	TimedOut bool
	// Status is one of: "success", "nonzero_exit", "empty_output", "timeout",
	// "invalid_arguments", "infrastructure_error". Statuses are chosen to be meaningful for
	// result analysis: "nonzero_exit", "empty_output", and "invalid_arguments" reflect the
	// tool being used incorrectly (a plausible model/tool-usage issue), while
	// "infrastructure_error" covers environment/tooling failures (container/filesystem setup,
	// Docker runtime errors including cancellation, and log retrieval failures) that the
	// model has no influence over and are not informative about the model or tool under test.
	Status string
	// Stdout is a size-limited capture of the call's standard output, or nil if no output was
	// ever captured (e.g. an infrastructure_error before or during log retrieval).
	Stdout *OutputCapture
	// Stderr is a size-limited capture of the call's standard error, or nil if no output was
	// ever captured (e.g. an infrastructure_error before or during log retrieval).
	Stderr *OutputCapture
	// ErrorMessage is a short explanation of the failure when Status is not "success".
	ErrorMessage string
}

type ToolUsage struct {
	CallCount       int64
	TotalDurationNs int64
	Exhausted       int32
}