agent

type ChatChunk struct {
	// Delta is appended text since the last chunk. Empty for chunks
	// that only carry tool-call deltas, usage, or stop information.
	Delta string `json:"delta,omitempty"`

	// ToolCallDelta carries an incremental update to a tool call.
	// Empty when the chunk only carries text or end-of-stream
	// metadata.
	ToolCallDelta *ToolCallDelta `json:"tool_call_delta,omitempty"`

	// Usage is populated only on the final chunk of the stream when
	// the provider reports usage at the end (Anthropic and OpenAI
	// both do; Gemini reports per-chunk usage that the runtime
	// accumulates).
	Usage *Usage `json:"usage,omitempty"`

	// StopReason is populated on the final chunk when generation
	// ended cleanly. Empty on intermediate chunks.
	StopReason StopReason `json:"stop_reason,omitempty"`
}

type ChatModel interface {
	Generate(ctx context.Context, req ChatRequest) (ChatResponse, error)
	Stream(ctx context.Context, req ChatRequest) (*StreamReader[ChatChunk], error)
}

type ChatRequest struct {
	// Model is the canonical model ID (e.g. "claude-opus-4-7",
	// "gpt-4o", "gemini-2.0-flash"). Provider packages reject IDs
	// outside their family.
	Model string `json:"model"`

	// Messages are the conversation history in order. The last
	// message is the active turn.
	Messages []Message `json:"messages"`

	// System is an optional conversation-level system prompt.
	// Providers that take a top-level `system` field populate that
	// field; providers without one prepend a system-role message.
	System string `json:"system,omitempty"`

	// Tools is the catalog the model may invoke. Empty disables tool
	// use. Each provider translates ToolInfo to its own catalog
	// shape.
	Tools []ToolInfo `json:"tools,omitempty"`

	// Temperature is the sampling temperature. Zero means "use the
	// provider default"; explicit zero is not addressable through
	// this field. Negative values are rejected at the provider layer.
	Temperature float64 `json:"temperature,omitempty"`

	// MaxTokens is the maximum number of tokens the model may emit.
	// Zero means "use the provider default" (Anthropic requires a
	// value; the provider supplies one).
	MaxTokens int `json:"max_tokens,omitempty"`

	// StopSequences are textual sequences that, when generated, end
	// the model's turn. Providers translate verbatim.
	StopSequences []string `json:"stop_sequences,omitempty"`
}

type ChatResponse struct {
	// Model is the canonical model ID the provider actually served
	// the call with. May differ from ChatRequest.Model when the
	// provider auto-substitutes (e.g. "claude-3-5-sonnet-latest" →
	// dated revision).
	Model string `json:"model"`

	// Content is the textual body of the assistant turn. Empty when
	// the turn consisted only of tool-use blocks.
	Content string `json:"content,omitempty"`

	// ToolCalls are the tool invocations the model wants the runtime
	// to perform. The runtime is responsible for executing them and
	// feeding the results back through subsequent ChatRequests.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// StopReason is the gridctl-shaped reason generation ended.
	StopReason StopReason `json:"stop_reason"`

	// Usage is the per-call token accounting.
	Usage Usage `json:"usage"`
}

type Graph[I, O any] = einoadapter.Graph[I, O]

type Message struct {
	// Role is "system", "user", "assistant", or "tool".
	Role Role `json:"role"`

	// Content is the textual body of the message. Empty when an
	// assistant message contains only ToolCalls.
	Content string `json:"content,omitempty"`

	// ToolCalls are the tool invocations an assistant message asks
	// the runtime to perform. Populated only for Role == RoleAssistant.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// ToolCallID is the ID of the tool call this message answers.
	// Populated only for Role == RoleTool. Must reference a prior
	// assistant ToolCall.ID in the same conversation.
	ToolCallID string `json:"tool_call_id,omitempty"`

	// Name is the tool name for tool-result messages. Some providers
	// (notably Anthropic) require the tool name on the result block;
	// others (OpenAI, Gemini) ignore it. Required when Role == RoleTool.
	Name string `json:"name,omitempty"`
}

type Role string

type Runnable[I, O any] = einoadapter.Runnable[I, O]

type StopReason string

type StreamReader[T any] = einoadapter.StreamReader[T]

type ToolCall struct {
	// ID is the provider-issued tool-call identifier. Required so
	// tool-result messages can reference the originating call.
	ID string `json:"id"`

	// Name is the tool name (no server prefix; the gateway prefixes
	// when needed).
	Name string `json:"name"`

	// Arguments is the JSON-encoded argument object as the model
	// emitted it. Callers MUST validate against the tool's input
	// schema before invoking; raw JSON is preserved verbatim so
	// provider quirks (key ordering, escaping) are visible.
	Arguments json.RawMessage `json:"arguments"`
}

type ToolCallDelta struct {
	// Index identifies which tool call this delta belongs to. Tool
	// calls are emitted in declaration order (0, 1, 2, ...).
	Index int `json:"index"`

	// ID is the tool-call identifier. Populated on the first delta
	// for an index.
	ID string `json:"id,omitempty"`

	// Name is the tool name. Populated on the first delta for an
	// index.
	Name string `json:"name,omitempty"`

	// ArgsDelta is a partial JSON fragment for the call's Arguments.
	// Concatenating all ArgsDelta values for a given Index yields the
	// final Arguments JSON.
	ArgsDelta string `json:"args_delta,omitempty"`
}

type ToolCallResult = mcp.ToolCallResult

type ToolCaller interface {
	CallTool(ctx context.Context, name string, arguments map[string]any) (*ToolCallResult, error)
}

type ToolInfo struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
}

type ToolResult struct {
	// ToolCallID references the assistant message's ToolCall.ID.
	ToolCallID string `json:"tool_call_id"`

	// Name is the tool name. Some providers require it on the result.
	Name string `json:"name,omitempty"`

	// Output is the textual content surfaced to the model. The runtime
	// renders gateway ToolCallResult.Content into a single string here;
	// structured-content support lands in a follow-up.
	Output string `json:"output"`

	// IsError reports whether the tool invocation produced an error.
	// Providers map this to their error-flag conventions (Anthropic
	// `is_error: true`, OpenAI tool error message, Gemini error part).
	IsError bool `json:"is_error,omitempty"`
}

type Usage struct {
	// InputTokens is the count of prompt tokens billed at the input
	// rate. Excludes cache-read tokens, which are priced separately.
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the count of generated tokens billed at the
	// output rate.
	OutputTokens int `json:"output_tokens"`

	// CacheReadTokens is the count of input tokens served from a
	// prompt cache. Anthropic and OpenAI both report this; Gemini
	// surfaces it through cached_content_token_count.
	CacheReadTokens int `json:"cache_read_tokens,omitempty"`

	// CacheWriteTokens is the count of input tokens written to a
	// prompt cache (Anthropic-only on the providers we cover).
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
}