agentrt

type Agent interface {
	Decide(ctx context.Context, in StepInput) (Decision, error)
}

type Approval struct {
	ID           string          `json:"id"`
	RunID        string          `json:"run_id"`
	StepID       string          `json:"step_id"`
	Kind         string          `json:"kind"`
	Capability   json.RawMessage `json:"capability"`
	Presentation json.RawMessage `json:"presentation"`
	Request      ToolRequest     `json:"request"`
	Hash         string          `json:"hash"`
	Status       ApprovalStatus  `json:"status"`
	CreatedAt    time.Time       `json:"created_at"`
	ExpiresAt    time.Time       `json:"expires_at,omitempty"`
	DecidedAt    time.Time       `json:"decided_at,omitempty"`
	DecidedBy    string          `json:"decided_by,omitempty"`
	Note         string          `json:"note,omitempty"`
}

type ApprovalStatus string

type Config struct {
	Store    *Store
	Agent    Agent
	Policy   Policy
	Tools    []Tool
	Observer Observer
	// Model, when set, is wrapped in a ModelCaller that agents receive in
	// StepInput. Scripted agents leave it nil.
	Model *ModelConfig
	// Reconcile, when set, runs before a run found mid-step is continued by
	// Resume. Consumers reconcile their own journaled operations and say
	// whether the run continues, completed, waits, or is in conflict.
	Reconcile func(ctx context.Context, view RunView) (Reconciliation, error)
	// Now and NewID may be overridden by tests.
	Now   func() time.Time
	NewID func() string
}

type ContentBlock struct {
	Type string `json:"type"`
	// Text applies to text blocks.
	Text string `json:"text,omitempty"`
	// ToolUseID, Name, and Input apply to tool_use blocks; ToolUseID also
	// links a tool_result block to the call it answers.
	ToolUseID string          `json:"tool_use_id,omitempty"`
	Name      string          `json:"name,omitempty"`
	Input     json.RawMessage `json:"input,omitempty"`
	// Content and IsError apply to tool_result blocks.
	Content string `json:"content,omitempty"`
	IsError bool   `json:"is_error,omitempty"`
}

type Decision struct {
	Kind DecisionKind `json:"kind"`
	// Tool and Args apply to tool_call.
	Tool string          `json:"tool,omitempty"`
	Args json.RawMessage `json:"args,omitempty"`
	// Reason is the agent's stated rationale, recorded as data.
	Reason string `json:"reason,omitempty"`
	// Result applies to complete.
	Result json.RawMessage `json:"result,omitempty"`
	// Message applies to fail.
	Message string `json:"message,omitempty"`
}

type DecisionKind string

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

type ErrAbortRun struct {
	Detail string
}

type ErrLimit struct {
	Reason TerminalReason
	Detail string
}

type ErrModelUnavailable struct {
	Attempts int
	Last     error
}

type Event struct {
	Seq     int64
	RunID   string
	StepID  string
	At      time.Time
	Type    string
	Payload json.RawMessage
}

type Limits struct {
	// MaxSteps is the maximum number of steps a run may start.
	MaxSteps int `json:"max_steps"`
	// MaxConsecutiveToolFailures ends the run when this many consecutive steps
	// produced a failure observation (tool error, policy denial, or an invalid
	// decision).
	MaxConsecutiveToolFailures int `json:"max_consecutive_tool_failures"`
	// LoopThreshold ends the run when the same tool call with the same
	// arguments has produced the same observation this many times in a row.
	// Repeating a call whose result changed is progress and is allowed.
	LoopThreshold int `json:"loop_threshold"`
	// MaxModelCalls counts every attempt, including retries and ambiguous
	// ones. Zero means unlimited.
	MaxModelCalls int `json:"max_model_calls,omitempty"`
	// MaxOutputTokensPerCall caps each request's output. Zero leaves the
	// agent's value.
	MaxOutputTokensPerCall int `json:"max_output_tokens_per_call,omitempty"`
	// MaxTotalTokens and MaxEstimatedCost are estimated limits: they are
	// checked before each call against totals plus a conservative estimate
	// for the call. Zero means unlimited.
	MaxTotalTokens   int    `json:"max_total_tokens,omitempty"`
	MaxEstimatedCost Micros `json:"max_estimated_cost_micros,omitempty"`
	// MaxActiveTime bounds the sum of step durations while RUNNING;
	// approval waits are excluded. MaxElapsedTime is an absolute deadline
	// from creation, including waits. ApprovalTTL expires a pending
	// approval and cancels the run when it is next touched. Zero disables
	// each.
	MaxActiveTime  time.Duration `json:"max_active_time,omitempty"`
	MaxElapsedTime time.Duration `json:"max_elapsed_time,omitempty"`
	ApprovalTTL    time.Duration `json:"approval_ttl,omitempty"`
}

type Message struct {
	Role    string         `json:"role"` // user or assistant
	Content []ContentBlock `json:"content"`
}

type Micros int64

type Model interface {
	// Name identifies the model for accounting and pricing.
	Name() string
	Generate(ctx context.Context, req ModelRequest) (ModelResponse, error)
}

type ModelCall struct {
	ID           string
	RunID        string
	StepID       string
	Attempt      int
	Status       ModelCallStatus
	Model        string
	Usage        Usage
	Cost         Micros
	Latency      time.Duration
	Error        string
	DispatchedAt time.Time
	CompletedAt  time.Time
}

type ModelCallStatus string

type ModelCaller interface {
	Generate(ctx context.Context, req ModelRequest) (ModelResponse, error)
}

type ModelConfig struct {
	Model       Model
	Prices      PriceTable
	CallTimeout time.Duration // per attempt; default 2 minutes
	MaxRetries  int           // transient retries per Generate; default 2
	Backoff     time.Duration // base backoff; default 1 second
}

type ModelRequest struct {
	System          string     `json:"system,omitempty"`
	Messages        []Message  `json:"messages"`
	Tools           []ToolSpec `json:"tools,omitempty"`
	MaxOutputTokens int        `json:"max_output_tokens,omitempty"`
}

type ModelResponse struct {
	Text       string          `json:"text,omitempty"`
	ToolUses   []ToolUse       `json:"tool_uses,omitempty"`
	StopReason string          `json:"stop_reason,omitempty"`
	Usage      Usage           `json:"usage"`
	Raw        json.RawMessage `json:"raw,omitempty"`
}

type Observation struct {
	Kind    ObservationKind `json:"kind"`
	Content json.RawMessage `json:"content,omitempty"`
	Summary string          `json:"summary,omitempty"`
	// ContentHash is the SHA-256 of the canonical JSON content. It is recorded
	// now so that later no-progress detection can key on it.
	ContentHash string `json:"content_hash,omitempty"`
}

type ObservationKind string

type Observer func(Event)

type Policy interface {
	Evaluate(ctx context.Context, req ToolRequest, view RunView) (PolicyDecision, error)
}

type PolicyDecision struct {
	Outcome PolicyOutcome `json:"outcome"`
	Reason  string        `json:"reason,omitempty"`
	// Kind, Capability, and Presentation apply to require_approval. In this
	// milestone the run pauses and records them; the approval record and
	// resumption arrive with durable approvals.
	Kind         string          `json:"kind,omitempty"`
	Capability   json.RawMessage `json:"capability,omitempty"`
	Presentation json.RawMessage `json:"presentation,omitempty"`
}

type PolicyFunc func(ctx context.Context, req ToolRequest, view RunView) (PolicyDecision, error)

type PolicyOutcome string

type Price struct {
	InputPerMTok       Micros `json:"input_per_mtok"`
	OutputPerMTok      Micros `json:"output_per_mtok"`
	CachedInputPerMTok Micros `json:"cached_input_per_mtok"`
}

type PriceTable map[string]Price

type ReconcileOutcome string

type Reconciliation struct {
	Outcome ReconcileOutcome
	Result  json.RawMessage
	Detail  string
}

type Run struct {
	ID           string
	Goal         string
	Status       RunStatus
	Reason       TerminalReason
	ReasonDetail string
	Limits       Limits
	// StepCount is the number of steps started, including the current one.
	StepCount  int
	CreatedAt  time.Time
	StartedAt  time.Time
	FinishedAt time.Time
	// Result is the payload of a Complete decision, if any.
	Result json.RawMessage
	// Model accounting totals across every attempt.
	ModelCalls    int
	Usage         Usage
	EstimatedCost Micros
	// ActiveTime is the sum of finished step durations.
	ActiveTime time.Duration
}

type RunStatus string

type RunView struct {
	Run       Run
	Steps     []Step
	Approvals []Approval
}

type SideEffect string

type SideEffectPolicy map[SideEffect]PolicyOutcome

type Step struct {
	ID          string
	RunID       string
	Index       int
	Status      StepStatus
	Decision    *Decision
	Policy      *PolicyDecision
	Observation *Observation
	StartedAt   time.Time
	FinishedAt  time.Time
}

type StepInput struct {
	Run       Run
	Steps     []Step
	Approvals []Approval
	Tools     []ToolSpec
	// Model is the agent's only handle to the model. It is nil when the
	// driver was configured without one, as for scripted agents.
	Model ModelCaller
}

type StepStatus string

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

type TerminalReason string

type Tool interface {
	Spec() ToolSpec
	Call(ctx context.Context, call ToolCall) (ToolResult, error)
}

type ToolCall struct {
	RunID  string
	StepID string
	Args   json.RawMessage
}

type ToolRequest struct {
	RunID  string          `json:"run_id"`
	StepID string          `json:"step_id"`
	Spec   ToolSpec        `json:"spec"`
	Args   json.RawMessage `json:"args"`
}

type ToolResult struct {
	Content json.RawMessage
	Summary string
}

type ToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"input_schema"`
	SideEffect  SideEffect      `json:"side_effect"`
	// Timeout bounds a single call. It is required.
	Timeout time.Duration `json:"timeout"`
	// Terminal tools complete the run when they succeed; their result
	// becomes the run result and no further decision is requested.
	Terminal bool `json:"terminal,omitempty"`
}

type ToolUse struct {
	ID   string          `json:"id"`
	Name string          `json:"name"`
	Args json.RawMessage `json:"args"`
}

type TransientError struct {
	Err error
}

type Usage struct {
	InputTokens       int `json:"input_tokens"`
	OutputTokens      int `json:"output_tokens"`
	CachedInputTokens int `json:"cached_input_tokens,omitempty"`
}