agentsafe

type AESGCM struct {
	Keys    map[string][]byte // key id -> 32-byte key
	Current string            // the id new events are sealed with
}

type Approval struct {
	By           string          // the verified identity making the decision
	Decision     string          // "approved" or "rejected"
	Reason       string          // the decider's reason (rejections)
	Tool         string          // the gated tool
	Key          string          // the operation's idempotency key
	Summary      json.RawMessage // what the approver was shown: the VALIDATED arguments (payee, amount, ...)
	RunStartedBy string          // who started the run (Runner.StartedBy), for separation of duties
}

type Authorizer interface {
	Authorize(ctx context.Context, a Approval) error
}

type AuthorizerFunc func(ctx context.Context, a Approval) error

type Codec interface {
	Seal(ctx context.Context, plaintext, aad []byte) ([]byte, error)
	Open(ctx context.Context, ciphertext, aad []byte) ([]byte, error)
}

type Decimal string

type Decision struct {
	Message      Message
	FinishReason string // "tool_calls", "stop", "length" (truncated: week 1 F1), ...
	Usage        Usage
}

type Describer interface {
	Describe() (provider, model string)
}

type Event struct {
	V    int       `json:"v,omitempty"` // log format version (FormatVersion); absent = 0, written before versions existed
	Seq  int       `json:"seq"`
	Prev string    `json:"prev,omitempty"` // hash of the previous line as written (FileLog's chain); see chain.go
	Type EventType `json:"type"`
	Time time.Time `json:"time"`

	// run_started
	Kind     string `json:"kind,omitempty"` // "proxy" (v5): calls arrive from outside, not from a model; absent = an agent run
	System   string `json:"system,omitempty"`
	Task     string `json:"task,omitempty"`
	MaxSteps int    `json:"max_steps,omitempty"` // the budget lives in the log, not in the runner's config
	KeyBits  int    `json:"key_bits,omitempty"`  // idempotency key length for this run (v4+); fixed for the run's life
	Provider string `json:"provider,omitempty"`  // e.g. "groq": so a trace can be built from the log alone
	Model    string `json:"model,omitempty"`

	// run_paused / budget_extended / approvals
	Reason     string `json:"reason,omitempty"`
	ExtraSteps int    `json:"extra_steps,omitempty"`
	By         string `json:"by,omitempty"` // who extended, decided, or (run_started, v2) started the run

	// model_decided
	Step         int      `json:"step,omitempty"`
	Message      *Message `json:"message,omitempty"`
	FinishReason string   `json:"finish_reason,omitempty"`
	Usage        *Usage   `json:"usage,omitempty"`

	// call_received (v5): who sent it, as the client reports itself (unverified: for audit display only)
	Client string `json:"client,omitempty"`
	// call_received (v6): request metadata the gateway's tool receives with the call (CallMetaFrom), e.g. the
	// client's MCP _meta minus what belongs to its own connection. Recorded so a retry after a crash sends the
	// same request. Content: sealed with the rest.
	Meta string `json:"meta,omitempty"` // JSON text, like args

	// tool_started / tool_result
	CallID string `json:"call_id,omitempty"`
	Tool   string `json:"tool,omitempty"`
	Args   string `json:"args,omitempty"`
	Result string `json:"result,omitempty"` // JSON, exactly what the model receives

	// tool_started / tool_result for an IdempotentTool
	Key         string `json:"key,omitempty"`          // derived from the operation's identity, never from the call id
	PayloadHash string `json:"payload_hash,omitempty"` // compared on replay: same key + different payload = conflict
	Replayed    bool   `json:"replayed,omitempty"`     // the result came from an earlier tool_result, nothing ran

	// approval_requested / approval_decided / tool_refused
	Summary  string `json:"summary,omitempty"`  // what the approver is shown: VALIDATED values, as JSON
	Decision string `json:"decision,omitempty"` // "approved" | "rejected"

	// run_finished
	Stop string `json:"stop,omitempty"`
	Text string `json:"text,omitempty"`

	// Sealed (format v3) holds the content fields above, encrypted by a Codec; they are empty while it is
	// set. See seal.go.
	Sealed string `json:"sealed,omitempty"`
}

type EventType string

type FileLog struct {
	Path string
	// Key, if set, makes the chain an HMAC-SHA256 chain: without the key, an attacker who rewrites the whole
	// file can't recompute the links. Use the same key for a log's whole life; keep it off the log's host.
	Key []byte
	// Codec, if set, seals each event's content before it is written and opens it on Read (seal.go). The
	// chain covers the sealed line, so tampering is still detected without the Codec's keys.
	Codec Codec
	// contains filtered or unexported fields
}

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

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type Gated interface {
	// NeedsApproval reports whether this particular call must be approved.
	NeedsApproval(args json.RawMessage) bool
	// Summary is what the approver is shown. It is built from VALIDATED arguments, so the human signs off on
	// checked values, never on the model's raw proposal.
	Summary(args json.RawMessage) (any, error)
}

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

type GatewayResult struct {
	Result   string // the tool's result as JSON, or {"error": ...} when it failed, was refused or is in doubt
	Replayed bool   // answered from the log: the operation had already happened, and nothing ran
	Refused  bool   // never attempted (refused before it ran, or waiting for approval)
	Pending  bool   // waiting for a human decision: call again with the same arguments for the outcome
}

type IdempotentTool interface {
	Tool
	// Identity returns the operation's identity (hashed into the key) and its payload (compared on replay).
	Identity(args json.RawMessage) (identity, payload any, err error)
	// CallWithKey performs the effect at most once per key. On a repeated key it must return the original
	// outcome and must NOT perform the effect again. That includes CONCURRENT calls with one key: after a
	// timeout the runner retries while the first call may still be running (exec.go). Return an error
	// wrapping ErrOutcomeUnknown when you can't tell whether the effect happened (e.g. a 504).
	CallWithKey(ctx context.Context, key string, args json.RawMessage) (any, error)
}

type Journal struct {
	Store LineStore
	Key   []byte
	Codec Codec
	// contains filtered or unexported fields
}

type KeyHonouring interface {
	HonoursKey() bool
}

type LineStore interface {
	// ReadLines returns every acknowledged line, in order, without line endings. It must never return a line
	// whose AppendLine didn't succeed (a torn write), and must return every line whose AppendLine did.
	ReadLines(ctx context.Context) ([][]byte, error)
	// AppendLine durably stores line as number seq (1-based), only if exactly seq-1 lines exist. Otherwise it
	// returns an error wrapping ErrConflict and stores nothing. The check and the write must be atomic against
	// every other writer of the run, in any process: a unique (run, seq) constraint, or a lock around both.
	// line is one line of JSON, without a line ending.
	AppendLine(ctx context.Context, seq int, line []byte) error
}

type Locker interface {
	Lock(ctx context.Context) (unlock func() error, err error)
}

type Log interface {
	Append(ctx context.Context, e Event) error
	Read(ctx context.Context) ([]Event, error)
}

type Message struct {
	Role       Role       `json:"role"`
	Content    *string    `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`

	// Native is the provider's own form of an assistant message, kept so the adapter that produced it can send
	// it back byte for byte (e.g. Claude's thinking blocks, which are bound to the exact conversation before
	// them: a resumed run that rebuilt them differently would be rejected). Other adapters ignore it. It is
	// logged, and sealed with the rest of the message.
	Native json.RawMessage `json:"native,omitempty"`
}

type Model interface {
	Decide(ctx context.Context, messages []Message, tools []ToolSpec) (Decision, error)
}

type Option func(*Runner)

type Outcome struct {
	PayloadHash string
	Result      string
	At          time.Time // when it was recorded: a ReplayWindowTool's window runs from here
	Unknown     bool      // recorded as an unknown outcome (ErrOutcomeUnknown): it may have happened, so it never expires
}

type PanicError struct {
	Tool  string
	Value any
	Stack []byte
}

type Redactor func(s string) string

type ReplayWindowTool interface {
	ReplayWindow() time.Duration
}

type Request struct {
	Client string          // who sent it, as the client reports itself: recorded for audit, not trusted
	Tool   string          // the tool to call
	Args   json.RawMessage // its arguments
	// Meta is metadata the tool receives with the call (CallMetaFrom): a JSON object, or empty. It's recorded
	// (sealed, like the arguments) so a retry after a crash sends the same request, and it's not part of the
	// operation: two calls that differ only in Meta are the same operation.
	Meta json.RawMessage
}

type Role string

type Runner struct {
	Model    Model
	Tools    []Tool
	Log      Log
	MaxSteps int                  // budget for a NEW run (logged in run_started); 0 = 8. Resumes use the logged budget.
	Scope    string               // idempotency scope, e.g. a hash of the input files; "" = per log
	Logf     func(string, ...any) // progress output; nil = silent
	Redact   Redactor             // masks arguments, results and summaries in Logf output (redact.go); nil = shown as is
	Hook     func(point string)   // test/chaos hook, called at named points; nil = none

	// Tool calls (exec.go). ToolTimeout bounds each call (a TimeoutTool sets its own); 0 = no limit. When an
	// IdempotentTool's outcome is unknown (timeout, ErrOutcomeUnknown), it's retried with the same key up to
	// ToolAttempts times (0 = 3), waiting ToolBackoff (0 = 200ms) and doubling between tries.
	ToolTimeout  time.Duration
	ToolAttempts int
	ToolBackoff  time.Duration

	// Authorizer decides who may approve or reject gated calls. Without one, decisions are refused
	// (ErrNoAuthorizer) unless AnyApprover is set: a gate anyone can open must be a visible choice.
	Authorizer  Authorizer
	AnyApprover bool
	// StartedBy records who started the run (an identity your system verified); NotRequester uses it.
	StartedBy string

	// Unlocked runs without a single-driver guarantee when the Log doesn't implement Locker. Off by default:
	// running a run from two processes at once must be a visible choice, not a silent gap.
	Unlocked bool
	// contains filtered or unexported fields
}

type ScriptedModel struct {
	Plan  []FunctionCall
	Final string
	Calls int // how many times Decide was called (to prove the runner never re-asks for a logged decision)
}

type State struct {
	Kind     string // "" for an agent run, KindProxy for a proxy run
	Status   Status
	Step     int        // model decisions so far
	Messages []Message  // the conversation to send on the next model call
	Pending  []ToolCall // proposed by the model, no tool_result yet, in the model's order
	// Started holds pending calls that have a tool_started event: they MAY have executed before a crash.
	// A pending call NOT in Started definitely never ran. That distinction is why tool_started exists.
	Started map[string]bool
	Stop    string
	Text    string // final answer
	Events  int
	Budget  int // max model decisions, from run_started + every budget_extended
	KeyBits int // idempotency key length, from run_started: a run keeps it across library upgrades

	// Approvals: decision per call id ("requested", "approved", "rejected"); ByKey: per operation key, so an
	// approval can be addressed by the payout's key and a repeated identical decision is a no-op.
	Approvals map[string]string
	ByKey     map[string]string
	Waiting   *Waiting // set while awaiting_approval
	// CallMeta is a proxy run's pending call's request metadata (call_received.meta), by call id: a retry after a
	// crash gives the tool the same metadata as the first attempt.
	CallMeta map[string]string
	// Requests are a proxy run's approvals still waiting, by operation key. A proxy run doesn't pause for an
	// approval: the call is answered "pending" and the run stays open; the decision is addressed by key.
	Requests  map[string]Waiting
	Denials   int    // refused approval attempts (approval_denied), for audit
	StartedBy string // who started the run (Runner.StartedBy), for separation of duties

	// Effects indexes every completed idempotent call by key: the log IS the idempotency store for
	// outcomes it has seen. (Outcomes it never saw, after a crash mid-call, are the tool's job: it gets the key.)
	Effects map[string]Outcome
}

type Status string

type TimeoutTool interface {
	Timeout() time.Duration
}

type Tool interface {
	Spec() ToolSpec
	// Call executes the tool. A returned error becomes an {"error": ...} result for the model, not a run
	// failure: the model decides what to do about a failed tool.
	Call(ctx context.Context, args json.RawMessage) (any, error)
}

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Function FunctionCall `json:"function"`
}

type ToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
}

type Validator interface {
	Validate(ctx context.Context, args json.RawMessage) error
}

type Waiting struct {
	CallID, Key, Tool, Summary string
}