agentrun

type Effort string

type Engine interface {
	// Start initializes a session and returns a Process handle.
	// The Process immediately begins producing Messages on its Output channel.
	// Options override Session fields for this specific invocation.
	Start(ctx context.Context, session Session, opts ...Option) (Process, error)

	// Validate checks that the engine is available and ready.
	// For CLI engines, this verifies the binary exists and is executable.
	// For API engines, this checks connectivity and authentication.
	Validate() error
}

type ExitError struct {
	Code int
	Err  error
}

type HITL string

type InitMeta struct {
	// Model is the model identifier reported by the backend at session start.
	// Reflects the agent's reported model during handshake; may differ from
	// the active model if the caller overrides via Session.Model.
	// Empty means the backend did not report a model on init.
	// Sanitized: control chars rejected, truncated to 128 bytes at parse time.
	Model string `json:"model,omitempty"`

	// AgentName is the agent implementation's name (e.g., "opencode", "claude-code").
	// Empty means the backend did not report an agent name.
	// Currently populated by ACP backends only.
	// Sanitized: control chars rejected, truncated to 128 bytes at parse time.
	AgentName string `json:"agent_name,omitempty"`

	// AgentVersion is the agent implementation's version string.
	// Empty means the backend did not report a version.
	// Currently populated by ACP backends only.
	// Sanitized: control chars rejected, truncated to 128 bytes at parse time.
	AgentVersion string `json:"agent_version,omitempty"`
}

type Message struct {
	// Type identifies the kind of message.
	Type MessageType `json:"type"`

	// Content is the text content. Semantics vary by Type:
	//   - MessageText: assistant text output
	//   - MessageError: human-readable error description (see ErrorCode for machine-readable)
	//   - MessageSystem: status text
	//   - MessageResult: optional result text (may be empty; see StopReason for completion signal)
	//   - *Delta types: partial content fragment (text, JSON, or thinking)
	Content string `json:"content,omitempty"`

	// Tool contains tool invocation details (for ToolUse, ToolResult messages).
	Tool *ToolCall `json:"tool,omitempty"`

	// Usage contains token usage data (typically on Text messages).
	Usage *Usage `json:"usage,omitempty"`

	// StopReason indicates why the agent's turn ended.
	// Set exclusively on MessageResult messages. Empty means the backend
	// did not report a stop reason.
	//
	// Consumers should handle unknown values gracefully — backends may
	// report values beyond the StopReason constants defined in this package.
	StopReason StopReason `json:"stop_reason,omitempty"`

	// ErrorCode is the machine-readable error code from the backend.
	// Set exclusively on MessageError messages. Human-readable description
	// is in Content. Empty means no structured code was provided.
	//
	// Intentionally a plain string (not a named type like StopReason):
	// error codes have no universal constants across backends — CLI backends
	// emit string codes (e.g., "rate_limit"), ACP emits library-defined
	// constants (e.g., acp.ErrCodeToolCallFailed). A named type would imply
	// root-level constants that don't exist. Consumers should match on raw
	// string values or use backend-exported constants where available.
	//
	// Backend parsers populate this field when the wire format includes a
	// structured error code. Empty means no code was provided.
	ErrorCode string `json:"error_code,omitempty"`

	// ResumeID is the backend-assigned session identifier for resume.
	// Set exclusively on MessageInit messages. Consumers persist this value
	// and pass it back via OptionResumeID to resume the session later.
	// Empty means the backend could not capture a session ID.
	ResumeID string `json:"resume_id,omitempty"`

	// Init carries metadata from the agent's initialization handshake.
	// Set exclusively on MessageInit messages. Nil on all other types.
	// Only non-nil when at least one field contains meaningful data.
	Init *InitMeta `json:"init,omitempty"`

	// Process carries subprocess metadata from the engine.
	// Set on MessageInit messages by subprocess engines (CLI, ACP).
	// Nil on all other message types and for API-based engines.
	Process *ProcessMeta `json:"process,omitempty"`

	// Raw is the original unparsed JSON from the backend.
	// Backends populate this for pass-through or debugging.
	Raw json.RawMessage `json:"raw,omitempty"`

	// Timestamp is when the message was produced.
	// Producers should always set this; zero value serializes as
	// "0001-01-01T00:00:00Z".
	Timestamp time.Time `json:"timestamp"`
}

type MessageType string

type Mode string

type Option func(*StartOptions)

type Process interface {
	// Output returns the channel for receiving messages from the agent.
	// The channel is closed when the session ends (normally or on error).
	// The first message may be of type MessageInit for engines that
	// perform a handshake.
	//
	// Callers must drain this channel concurrently with Send for engines
	// that stream updates during the RPC call. See [RunTurn] for a helper
	// that handles this correctly.
	Output() <-chan Message

	// Send transmits a user message to the active session.
	// For ACP engines, Send blocks until the agent's turn completes.
	// Callers must drain Output() concurrently to avoid deadlock.
	// See [RunTurn] for a helper that handles this correctly.
	Send(ctx context.Context, message string) error

	// Stop terminates the session. For CLI engines, this sends SIGTERM
	// then SIGKILL after a grace period.
	Stop(ctx context.Context) error

	// Wait blocks until the session ends naturally.
	// Returns nil on clean exit, or an error describing the failure.
	Wait() error

	// Err returns the terminal error after the Output channel is closed.
	// Returns nil if the session ended cleanly. Callers should call Err
	// after the Output channel is closed to distinguish clean exit from
	// failure.
	Err() error
}

type ProcessMeta struct {
	// PID is the OS process identifier of the subprocess.
	// Per the nil-guard contract on ProcessMeta, this field is always > 0.
	PID int `json:"pid,omitempty"`

	// Binary is the resolved path to the subprocess executable.
	// Populated from exec.Cmd.Path (the result of exec.LookPath).
	// Empty means not available.
	Binary string `json:"binary,omitempty"`
}

type Session struct {
	// ID uniquely identifies the session.
	ID string `json:"id"`

	// CWD is the working directory for the agent process.
	CWD string `json:"cwd"`

	// Model specifies the AI model to use (e.g., "claude-sonnet-4-5-20250514").
	Model string `json:"model,omitempty"`

	// Prompt is the initial prompt or message for the session.
	Prompt string `json:"prompt,omitempty"`

	// Options holds session configuration as key-value pairs.
	// Use well-known Option* constants for cross-cutting features
	// (e.g., OptionSystemPrompt, OptionMaxTurns). Backend-specific
	// options are defined in their respective packages.
	Options map[string]string `json:"options,omitempty"`

	// Env holds additional environment variables for the agent process.
	// These are merged with the parent process environment via MergeEnv —
	// os.Environ() provides the base, and Env entries override matching keys.
	// Nil or empty means inherit parent environment unchanged.
	//
	// Keys must not be empty, contain '=' or null bytes.
	// Values must not contain null bytes.
	//
	// Security note: consumers are responsible for what they pass.
	// The library validates key syntax but does not blocklist specific
	// variable names (e.g., LD_PRELOAD, PATH). Treat Session.Env like
	// cmd.Env — the caller owns the security boundary.
	Env map[string]string `json:"env,omitempty"`
}

type StartOptions struct {
	// Prompt overrides Session.Prompt for this invocation.
	// Zero value means use Session.Prompt.
	Prompt string

	// Model overrides Session.Model for this invocation.
	// Zero value means use Session.Model.
	Model string

	// Timeout sets a deadline for the Start operation.
	// Zero means no timeout beyond the context deadline.
	Timeout time.Duration
}

type StopReason string

type ToolCall struct {
	// Name is the tool identifier.
	Name string `json:"name"`

	// Input is the tool's input parameters as raw JSON.
	Input json.RawMessage `json:"input,omitempty"`

	// Output is the tool's result as raw JSON.
	Output json.RawMessage `json:"output,omitempty"`
}

type Usage struct {
	// InputTokens is the cumulative context window fill.
	// Always serialized (0 means zero tokens used).
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the number of tokens generated.
	// Always serialized (0 means zero tokens generated).
	OutputTokens int `json:"output_tokens"`

	// CacheReadTokens is tokens served from cache instead of recomputed.
	// Omitted when zero (0 means not reported by this backend).
	CacheReadTokens int `json:"cache_read_tokens,omitempty"`

	// CacheWriteTokens is tokens written to cache for future reuse.
	// Omitted when zero (0 means not reported by this backend).
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`

	// ThinkingTokens is tokens used for model reasoning/thinking.
	// Omitted when zero (0 means not reported by this backend).
	ThinkingTokens int `json:"thinking_tokens,omitempty"`

	// CostUSD is the estimated cost in USD for this turn.
	// Omitted when zero. Always a finite non-negative value; parsers
	// must sanitize NaN/Inf to zero before populating this field.
	// Approximate — not suitable for billing reconciliation.
	CostUSD float64 `json:"cost_usd,omitempty"`

	// ContextSizeTokens is the total context window capacity in tokens.
	// Omitted when zero (0 means not reported by this backend).
	// Set on MessageContextWindow messages (ACP usage_update).
	ContextSizeTokens int `json:"context_size_tokens,omitempty"`

	// ContextUsedTokens is the current context window fill level in tokens.
	// Omitted when zero (0 means not reported by this backend).
	// Set on MessageContextWindow messages (ACP usage_update).
	ContextUsedTokens int `json:"context_used_tokens,omitempty"`
}