agent

type APIError ¶

type APIError struct {
	StatusCode int
	Body       string
	Err        error
}

APIError is returned by a provider adapter for a non-2xx HTTP response other than 429 (which uses RateLimited). It carries the StatusCode so a retry classifier can tell a transient failure (5xx, 408) from a terminal one (most 4xx: auth, validation), and a short Body snippet for diagnostics. It wraps Err (typically ErrModel) so errors.Is(err, ErrModel) holds.

func (e *APIError) Error() string

func (e *APIError) Unwrap() error

type Agent ¶

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

Agent binds a model, a tool set, a durable store, and a middleware chain.

The WithX/Use/SetX builder methods MUTATE the receiver in place and return it for chaining; they do not copy. This is deliberate: it lets configuration be applied after construction and after the value has been shared, e.g. a.Use(trace.Model(...)) or a.Use(agent.WithRetrieval(...)) wiring a cross-cutting concern onto an agent other code already holds. The consequence is that two variables assigned from the same New(...) are aliases: reconfiguring one reconfigures both. When you need an independently configured variant, construct a fresh Agent rather than expecting a builder to fork. (The internal clone/cloneWith, used by RunTyped, do copy; they are not exported.)

An Agent is safe for concurrent Run/Stream/Session calls once configured; the builder methods are not safe to call concurrently with a run or with each other. Configure first, then run.

func New(model Model, store Durable, tools ...Tool) *Agent

func (a *Agent) Run(ctx context.Context, runID, input string) (Message, error)

func (a *Agent) RunResult(ctx context.Context, runID, input string) (*Result, error)

func (a *Agent) RunSaga(ctx context.Context, runID, input string) (Message, error)

func (a *Agent) RunSagaResult(ctx context.Context, runID, input string) (*Result, error)

func (a *Agent) Session(ctx context.Context, id string) (*Session, error)

func (a *Agent) SetMaxConcurrency(n int) *Agent

func (a *Agent) Stream(ctx context.Context, runID, input string) *AgentStream

// A model that answers directly (a real adapter streams token deltas the same way).
m := &scriptModel{turns: [][]Emit{textTurn("hello world")}}
a := New(m, NewMemStore())

stream := a.Stream(context.Background(), "run-1", "hi")
for ev := range stream.Events() {
	switch e := ev.(type) {
	case TurnStarted:
		fmt.Println("turn started")
	case ModelEvent:
		if d, ok := e.Event.(TextDelta); ok {
			fmt.Printf("delta: %q\n", d.Text)
		}
	case Finished:
		fmt.Println("finished")
	}
}
answer, err := stream.Final()
if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println("answer:", textOf(answer))

Output:
turn started
delta: "hello world"
finished
answer: hello world

func (a *Agent) StreamSaga(ctx context.Context, runID, input string) *AgentStream

func (a *Agent) Use(mw ...Middleware) *Agent

func (a *Agent) UseTool(mw ...ToolMiddleware) *Agent

func (a *Agent) WithApproverVerifiers(fn ApproverVerifierFor) *Agent

func (a *Agent) WithMaxTurns(n int) *Agent

func (a *Agent) WithSampling(opts ...SamplingOption) *Agent

func (a *Agent) WithSystemPrompt(s string) *Agent

func (a *Agent) WithSystemPromptFunc(fn func(context.Context) string) *Agent

func (a *Agent) WithToolChoice(tc ToolChoice) *Agent

type AgentEvent ¶

type AgentEvent interface {
	// contains filtered or unexported methods
}

AgentEvent is a lifecycle event emitted by Agent.Stream as the run loop advances: turn boundaries, live model token deltas, and tool start/finish. It is the SEMANTIC-layer companion to the model's byte-level Event — a UI ranges over these to render progress while the durable loop runs underneath.

The terminal answer and any error are NOT events: they come from AgentStream.Final (mirroring how the model Stream yields Events but returns the assembled Message separately). A run that pauses for approval or halts on an unsafe resume emits the relevant lifecycle event and then surfaces the *PendingApproval / *ResumeHalt via Final, exactly as Run returns it.

func ReplayEvents(ctx context.Context, store Durable, runID string) ([]AgentEvent, error)

type AgentStream ¶

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

AgentStream is a live view of a running agent: range Events for progress, then call Final for the terminal answer (or error). It is the streaming counterpart of Run, the same way the model Stream is the counterpart of Generate — Run is literally Stream(...).Final().

A Stream is consumed once. Either range Events fully (Final then returns immediately) or call Final directly (it drains and discards events); calling Final after breaking out of Events early drains whatever remains. Cancel ctx to abandon a run without draining — pending emits then unblock on ctx.Done rather than leaking.

func (as *AgentStream) Events() iter.Seq[AgentEvent]

func (as *AgentStream) Final() (Message, error)

type ApprovalPolicy ¶ added in v0.4.0

type ApprovalPolicy struct {
	Need      int      // decisions required to proceed (k), 1 <= Need <= len(Approvers)
	Approvers []string // eligible approver ids; the bounded set (n)
}

ApprovalPolicy declares a k-of-n human gate. Need is k; the eligible approvers are the bounded set (n = len(Approvers)). A tool with a non-nil Approval requires approval whether or not RequiresApproval is also set.

func (p ApprovalPolicy) Validate() error

type ApprovalRequired ¶

type ApprovalRequired struct {
	ToolUseID string
	Name      string
	Args      json.RawMessage
	// Quorum is the running tally when the tool has an m-of-n Safety.Approval policy, so a
	// streaming UI can show progress ("1 of 2 approved") without waiting for Final. Nil for
	// a 1-of-1 gate.
	Quorum *ApprovalTally
}

ApprovalRequired fires immediately before the run pauses for a human decision on a tool that requires approval. The run then returns *PendingApproval from Final; record a decision (Approve, or ApproveAs for an m-of-n gate) and re-invoke to continue.

type ApprovalSubject ¶ added in v0.4.0

type ApprovalSubject struct {
	RunID     string
	ToolUseID string
	ToolName  string
	Args      json.RawMessage
}

ApprovalSubject is exactly what an approver decides on: one tool call, with its name and arguments, in one run. The decision bytes bind all of it, so a signature approves this call and no other: not another run, not another call, and not the same call id with different arguments.

type ApprovalTally ¶ added in v0.4.0

type ApprovalTally struct {
	Need       int      `json:"need"`                  // the policy's k
	Approvers  []string `json:"approvers"`             // the eligible set the gate enforced, in policy order
	Approved   int      `json:"approved"`              // approvers whose counted decision is an approval
	Denied     int      `json:"denied"`                // approvers whose counted decision is a denial
	ApprovedBy []string `json:"approved_by,omitempty"` // those approvers, in journal order
	DeniedBy   []string `json:"denied_by,omitempty"`   // those approvers, in journal order
	Pending    []string `json:"pending,omitempty"`     // eligible approvers with no valid decision yet, in policy order
	// Records names every decision record on this call the gate read, valid or not, in
	// journal order. Evidence must disclose all of them, so an omitted decision is detectable.
	Records []string `json:"records,omitempty"`
}

ApprovalTally is the m-of-n gate's count for one call. At a pause it is the running tally (PendingApproval.Quorum, ApprovalRequired.Quorum). At a terminal outcome the gate journals it under ApprovalTallyStep, before the tool runs, as the record of what it enforced and what it read.

func (t ApprovalTally) Passed() bool

func (t ApprovalTally) Unreachable() bool

type ApproveOption ¶ added in v0.4.0

type ApproveOption func(*approveOptions)

ApproveOption configures ApproveAs.

func WithDecisionCheck(verifierFor ApproverVerifierFor) ApproveOption

type ApproverVerifier ¶ added in v0.4.0

type ApproverVerifier interface {
	Verify(message, sig []byte) bool
}

ApproverVerifier checks an approver's signature over the decision bytes. Any audit.Verifier satisfies it structurally, so a deployment reuses the existing ed25519/ML-DSA/hybrid verifiers with no new cryptography and no agent->audit import.

type ApproverVerifierFor ¶ added in v0.4.0

type ApproverVerifierFor func(approverID string) (ApproverVerifier, bool)

ApproverVerifierFor resolves the verifier for an approver id (the caller's PKI, mirroring audit's issuer lookup). It reports ok=false for an unknown approver; the counting rule treats that approver's decisions as unverifiable.

type AssistantTurn ¶

type AssistantTurn struct {
	Message  Message
	Replayed bool
}

AssistantTurn is the fully-assembled assistant message for a turn. Replayed is true when it was reconstructed from the journal on resume rather than produced by a live model call (in which case no ModelEvent deltas preceded it).

type Awaiting ¶

type Awaiting struct {
	RunID  string
	Name   string
	Prompt any // optional caller payload describing what the run is waiting for
}

Awaiting is returned by Run when a tool called Await and no signal has been delivered for that name yet. The run has paused durably at the await point. Deliver a signal with Signal (same name), then re-invoke Run with the same runID to continue. Awaiting is the externally-pushed dual of Interrupted: Interrupt asks a human and resumes with their answer; Await waits for an event an outside system delivers.

func (e *Awaiting) Error() string

type Compensator ¶

type Compensator interface {
	// Compensate undoes a completed call. args are the tool's original arguments; result
	// is what Call returned. Must be idempotent — on a crash mid-rollback it may re-run.
	Compensate(ctx context.Context, args, result json.RawMessage) error
}

Compensator is an optional interface a Tool implements to declare how to UNDO its side effect. In a saga run (RunSaga), if a step fails after earlier writes succeeded, the completed compensatable writes are rolled back in reverse order — automatically, and recursively through sub-agent trees.

This is the transactional / saga agent: "charged the card and booked the flight, then failed on the hotel → cleanly refund + cancel." It's the gsm compensation idea applied to the agent runtime — the journal records exactly which writes completed, so well-founded reverse compensation falls out of the durable substrate.

A saga step must be ATOMIC: it must not leave a partial external side effect before returning an error, because the failing step itself is not compensated (there's no recorded result to drive Compensate). Make forward steps all-or-nothing, or idempotent.

type DecisionCheck ¶ added in v0.4.0

type DecisionCheck struct {
	Step     string // the record's journal name
	Approver string
	Approved bool
	Counted  bool   // this is the approver's decision: their first valid one
	Reason   string // why it did not count; empty when Counted
}

DecisionCheck is how the counting rule classified one decision record.

type Doc ¶

type Doc struct {
	ID       string         `json:"id,omitempty"`
	Text     string         `json:"text"`
	Score    float64        `json:"score,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

Doc is a document returned by a Retriever: its text plus optional id, similarity score, and metadata. This is the neutral shape the retrieval helpers speak; your Retriever maps your store's results onto it.

type Durable ¶

type Durable interface {
	// Do returns the recorded Record for (runID, name) without running fn if present;
	// otherwise runs fn, records the returned Record (with Name set), and returns it.
	// If fn errors, nothing is recorded — the step re-runs on the next attempt.
	Do(ctx context.Context, runID, name string, fn func(context.Context) (Record, error)) (Record, error)
	// History returns all recorded steps for a run, in order.
	History(ctx context.Context, runID string) ([]Record, error)
}

Durable is the crash-safe substrate: named-step memoization. Do runs a step at most-once per (runID, name): a recorded step returns without re-running fn. This mirrors DBOS RunAsStep and ADK v2 RunNode; our SQLite default implements it directly, and store/postgres is the high-availability backend. The side-effect-safety layer (Safety / ResumeHalt) sits ABOVE this and is substrate-agnostic (see Agent.Run).

type Emit ¶

type Emit struct {
	Event Event
	Err   error
}

Emit is what an adapter pushes onto its event channel (event or terminal error).

type Event ¶

type Event interface {
	// contains filtered or unexported methods
}

Event is a normalized streamed model event. The stream/ package maps every provider wire format (OpenAI SSE / Anthropic typed / Gemini NDJSON / Bedrock binary) onto these.

type Finish ¶

type Finish struct {
	Reason string
	Usage  Usage
}

type Finished ¶

type Finished struct{ Final Message }

Finished carries the terminal assistant answer — the same Message that Run returns and that Final reports. The event stream closes after this.

type HaltTooYoung ¶ added in v0.3.0

type HaltTooYoung struct {
	RunID     string
	ToolUseID string
	Age       time.Duration // elapsed since the effect was attempted
	Min       time.Duration // the required minimum
}

HaltTooYoung is returned by ResolveHalt when WithMinHaltAge is set and the halt has not aged past the grace period yet. Wait and retry the resolution later.

func (e *HaltTooYoung) Error() string

type Identity ¶

type Identity struct {
	// Actor is the acting agent instance: a deployment plus model version, e.g. "exec-agent@1.4.2".
	Actor string `json:"actor,omitempty"`
	// OnBehalfOf is the principal the agent acts for: a desk, an account, a user.
	OnBehalfOf string `json:"on_behalf_of,omitempty"`
	// AuthorityRef identifies the grant that authorizes this action: the digest or id of a signed
	// capability/authority record (see audit anchoring), so the leaf links to what permitted it.
	AuthorityRef string `json:"authority_ref,omitempty"`
}

Identity is the accountability binding for a run: which agent instance acted, on whose behalf, and under what authority. It is assigned by the DEPLOYMENT, not by the model: the operator sets it at run start from its own auth layer (an IdP, a signed capability grant, a service identity), and it rides the context so every governed action and every sub-agent call inherits it. The SDK anchors and proves the identity CLAIM (these fields, committed in the audit log); it does not authenticate the principal, which is the operator's IdP/PKI, and the attribution is only as strong as custody of whatever key signs the run's tree heads and grants.

The model has no inherent identity. "The agent's identity" is the identity the deployment binds to this run, so a compromised or misconfigured deployment attributes to whatever it claims. That boundary is deliberate and matches the model/governance split: prove the record and the granted authority, do not overclaim the intent behind them.

func IdentityFrom(ctx context.Context) (Identity, bool)

func (i Identity) Empty() bool

type Image ¶

type Image struct {
	Mime string `json:"mime,omitempty"` // MIME type for Data (required when Data is set), e.g. "image/jpeg"; ignored for URL
	Data []byte `json:"data,omitempty"` // raw image bytes; adapters base64-encode. Mutually exclusive with URL.
	URL  string `json:"url,omitempty"`  // hosted image URL. Mutually exclusive with Data.
}

Image is a provider-neutral image input. Exactly one of Data or URL is set (Data XOR URL). For raw bytes, set Data and Mime (e.g. "image/png"); the adapter base64-encodes it (Anthropic base64 source / OpenAI data URI). For a hosted image, set URL and leave Data nil; Mime is not required for URLs. This is an input-only part: models emit text, reasoning, and tool calls, never images, so nothing produces an Image on the response path.

func ImageData(mime string, data []byte) Image

func ImageURL(url string) Image

type Interrupted ¶

type Interrupted struct {
	RunID  string
	Key    string
	Prompt any // caller-defined payload for the human: a question, options, current state
}

Interrupted is returned by Run when a tool called Interrupt and no resume value has been recorded for that key yet. The run has paused durably at the interrupt point. Inspect Prompt to decide what to ask the human, record an answer with Resume (same Key), then re-invoke Run with the same runID to continue.

func (e *Interrupted) Error() string

type JSONToolResultCodec ¶ added in v0.2.0

type JSONToolResultCodec struct{}

JSONToolResultCodec is the default codec: it passes the canonical JSON through unchanged. It is equivalent to what an adapter does when no ToolResultCodec is configured.

func (JSONToolResultCodec) EncodeToolResult(raw json.RawMessage) (string, error)

type Leaser ¶

type Leaser interface {
	// AcquireLease claims runID for holder until now+ttl. It returns true if granted (the run is
	// unleased or the live lease is already holder's, which renews it), false if another holder
	// currently holds a live lease. An expired lease is available to any holder.
	AcquireLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
	// RenewLease extends holder's lease on runID, returning false if holder no longer holds it (it
	// expired or was taken). A driver whose work outlasts ttl renews to keep the lease.
	RenewLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
	// ReleaseLease relinquishes runID if held by holder (a no-op otherwise) so another process can
	// take it immediately rather than waiting for expiry.
	ReleaseLease(ctx context.Context, runID, holder string) error
}

Leaser is the optional capability that coordinates driving a run across processes. Without it, several processes recovering against a shared store all re-drive the same in-flight runs. That is safe but wasteful: side effects stay at-most-once because each non-idempotent call is guarded by an exclusive attempt claim (ClaimAttempt), but the drivers duplicate model calls and a loser of a claim halts with ResumeHalt. A store that implements Leaser lets a driver take a time-bounded lease on a run so normally only the holder drives it; a dead holder's lease expires and another process takes over, which is the high-availability property. Recover uses it automatically when the store provides it. A lease is an efficiency and liveness mechanism, not the safety one: no lease can guarantee mutual exclusion against a holder that stalls past its TTL, which is why the claim, not the lease, is what keeps side effects at-most-once.

The base Durable contract does not require leasing, and MemStore's implementation is in-process (for tests and as the reference); the cross-process payoff is a shared backend (store/postgres) implementing this with an atomic upsert over a leases table.

type Lister ¶

type Lister interface {
	// Runs returns the IDs of every run the store holds, in no guaranteed order.
	Runs(ctx context.Context) ([]string, error)
}

Lister is the optional capability a crash-recovery supervisor needs: it enumerates the runs a store knows about, so Recover can find in-flight runs to re-drive after a restart. The base Durable interface intentionally does NOT require it: memoization (Do) and replay (History) are the crash-safety core, and enumeration is a separate, backend-specific concern (a SQL store lists with a query; a sharded store may not enumerate cheaply at all). A store opts in by implementing Runs; Recover type-asserts for it.

type MemStore ¶

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

MemStore is an in-memory Durable for tests and local dev. SQLite is the shipping default; store/postgres is the high-availability backend.

It keeps each record as its JSON encoding and decodes on every read, the same way the SQL stores do. So a record a caller gets back is always an independent copy (modifying it cannot change the journal), and it has the same byte-normalized form a production store returns, which keeps tests on MemStore faithful to SQLite and Postgres.

func NewMemStore() *MemStore

func (m *MemStore) AcquireLease(_ context.Context, runID, holder string, ttl time.Duration) (bool, error)

func (m *MemStore) Do(ctx context.Context, runID, name string, fn func(context.Context) (Record, error)) (Record, error)

func (m *MemStore) History(_ context.Context, runID string) ([]Record, error)

func (m *MemStore) ReleaseLease(_ context.Context, runID, holder string) error

func (m *MemStore) RenewLease(_ context.Context, runID, holder string, ttl time.Duration) (bool, error)

func (m *MemStore) Runs(_ context.Context) ([]string, error)

type MemWaker ¶

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

MemWaker is an in-process Waker: it holds pending timers and, when Fire is called with the current time (or via a Start ticker), resumes every run whose timer is due by calling the resume function it was built with. resume is how the deployment re-invokes a run, typically agent.Run(ctx, runID, savedInput); a resumed run whose wait is over proceeds, and one that sleeps again re-registers a new wake here. MemWaker is a reference and a local-dev default, not a durable scheduler: a process exit loses its in-memory timer set, so the wake times must also live in the durable journal (they do, Sleep journals them), and a restarted deployment rebuilds pending wakes by scanning runs, or an external scheduler owns the trigger.

func NewMemWaker(resume func(ctx context.Context, runID string) error) *MemWaker

func (w *MemWaker) Fire(ctx context.Context, now time.Time) (int, error)

func (w *MemWaker) Schedule(runID, name string, fireAt time.Time)

func (w *MemWaker) Start(ctx context.Context, every time.Duration, onError func(error))

type Message ¶

type Message struct {
	Role  Role
	Parts []Part
}

Message is one turn. Its content is a sequence of typed Parts (NOT a flat string), so reasoning/thinking parts (which Anthropic requires echoed back across turns), tool calls, tool results, and image inputs all survive round-trips intact. This is the provider-neutral type; adapters translate to/from provider wire formats.

func SystemText(s string) Message

func UserParts(parts ...Part) Message

func UserText(s string) Message

func (m Message) MarshalJSON() ([]byte, error)

func (m Message) Text() string

func (m *Message) UnmarshalJSON(b []byte) error

type Middleware ¶

type Middleware func(ModelHandler) ModelHandler

Middleware wraps a ModelHandler — the net/http-style func(Handler) Handler chain, at the SEMANTIC layer (it sees messages, tool calls, token usage — not bytes). Batteries live in the middleware/ package (Retry, TokenBudget, ...).

func WithRetrieval(r Retriever, k int) Middleware

type Model ¶

type Model interface {
	Stream(ctx context.Context, req Request) (*Stream, error)
}

Model is the provider primitive. Streaming is FIRST-CLASS: Stream is the only method an adapter must implement. Generate is a convenience drain built on top — the opposite of frameworks that make blocking generation primary and bolt streaming on later.

func Replay(ctx context.Context, source Durable, runID string) (Model, error)

type ModelEvent ¶

type ModelEvent struct{ Event Event }

ModelEvent forwards one live model stream Event (TextDelta, ReasoningDelta, ToolCallDelta, Finish) from the current turn — the token-by-token feed. Emitted only for a FRESH model call; on durable replay the turn is reused from the journal and produces no deltas (an AssistantTurn with Replayed=true is emitted instead).

type ModelHandler ¶

type ModelHandler func(context.Context, Request) (Message, Usage, error)

ModelHandler generates one assistant turn. Middleware wraps it.

type Part ¶

type Part interface {
	// contains filtered or unexported methods
}

Part is a single piece of message content. Concrete parts: Text, Reasoning, ToolUse, ToolResult, Image.

type PendingApproval ¶

type PendingApproval struct {
	RunID     string
	ToolUseID string
	ToolName  string
	Args      json.RawMessage
	// Quorum is non-nil for an m-of-n gate: the running tally at the pause. Record
	// decisions with ApproveAs, then re-run.
	Quorum *ApprovalTally
}

PendingApproval is returned by Agent.Run when a tool requiring human approval has no recorded decision yet. The run has paused durably; call Approve then re-run to resume.

func (e *PendingApproval) Error() string

func (e *PendingApproval) Subject() ApprovalSubject

sig := signer.Sign(agent.ApprovalDecisionBytes(pend.Subject(), "finance", true))

type RateLimited ¶

type RateLimited struct {
	RetryAfter time.Duration
	Err        error
}

RateLimited is returned by a provider adapter when it receives HTTP 429. It carries an optional RetryAfter hint from the Retry-After response header (0 means no hint was provided). It wraps the caller-supplied Err (typically wrapping ErrModel) so errors.Is(err, ErrModel) holds.

func (e *RateLimited) Error() string

func (e *RateLimited) Unwrap() error

type Reasoning ¶

type Reasoning struct {
	Text      string `json:"text"`
	Signature string `json:"signature,omitempty"`
}

Reasoning is model thinking. Signature is the provider's opaque token that must be echoed back on later turns (Anthropic extended thinking); dropping it corrupts the conversation — which is exactly why Content can't be a flat string.

type ReasoningDelta ¶

type ReasoningDelta struct {
	Text      string
	Signature string // opaque provider token to echo back on later turns (Anthropic thinking)
}

type Received ¶

type Received[T any] struct {
	Key     string
	Payload T
}

Received is one message pulled from a channel.

func Receive[T any](ctx context.Context, channel string) (Received[T], error)

type Record ¶

type Record struct {
	Name      string          `json:"name"`
	Kind      StepKind        `json:"kind"`
	Message   *Message        `json:"message,omitempty"`     // StepModel
	ToolUseID string          `json:"tool_use_id,omitempty"` // StepToolResult
	Result    json.RawMessage `json:"result,omitempty"`      // StepToolResult / StepValue
	IsError   bool            `json:"is_error,omitempty"`    // StepToolResult
	Approved  bool            `json:"approved,omitempty"`    // StepApproval
	Approver  string          `json:"approver,omitempty"`    // StepApproval written by ApproveAs
	Signature []byte          `json:"signature,omitempty"`   // StepApproval written by ApproveAs
	// AttemptedAt is the Unix-millis wall-clock time an attempt marker (StepAttempt) was
	// written, i.e. just before a non-retriable side effect fired. It is set once and read
	// back verbatim on replay, so it stays deterministic. Zero (and omitted) on every
	// other kind; a reconciler uses it to honor a grace period before resolving a halt.
	AttemptedAt int64 `json:"attempted_at,omitempty"`
	// Reconciled marks a StepToolResult that ResolveHalt injected from verified evidence
	// rather than one the tool produced by running. It lets a later reader (and bide-audit)
	// tell a reconciled outcome from a clean one at a glance.
	Reconciled bool `json:"reconciled,omitempty"`
	// Evidence is what a reconciler read to decide the outcome (a queried provider record,
	// a message id, a log line). It is carried on the reconciled result and signed with it,
	// so the verdict and its basis live in the journal beside the outcome.
	Evidence json.RawMessage `json:"evidence,omitempty"`
	// Claim is the random id of the driver that wrote an attempt marker (see ClaimAttempt).
	// A driver runs the side effect only if the marker it gets back carries its own claim, so
	// two drivers of the same run can never both run it, whatever their leases say.
	Claim string `json:"claim,omitempty"`
}

Record is one durably-recorded, named event. The ordered sequence of Records for a run is its full, replayable history; resume rebuilds state by replaying them. Name is the stable identity used for memoization (see Durable.Do).

func ClaimAttempt(ctx context.Context, d Durable, runID, name string, rec Record) (won bool, got Record, err error)

type RecoverOption ¶

type RecoverOption func(*recoverConfig)

RecoverOption configures Recover. Lease options apply only when the store implements Leaser.

func WithLeaseHolder(id string) RecoverOption

func WithLeaseTTL(d time.Duration) RecoverOption

type Request ¶

type Request struct {
	Messages       []Message
	Tools          []Tool
	Sampling       Sampling        // generation controls; zero value = provider/model defaults
	ResponseFormat *ResponseFormat // nil = free-form; set = constrain output to a JSON schema
	ToolChoice     *ToolChoice     // nil = provider default (auto); see ToolChoice
}

Request is a single model call.

type ResolveOption ¶ added in v0.3.0

type ResolveOption func(*resolveConfig)

ResolveOption configures ResolveHalt.

func WithEvidence(v any) ResolveOption

func WithMinHaltAge(d time.Duration) ResolveOption

func WithNow(now func() time.Time) ResolveOption

type ResponseFormat ¶

type ResponseFormat struct {
	Name   string
	Schema json.RawMessage
}

ResponseFormat asks the provider to constrain the model's output to a named JSON schema (OpenAI structured outputs / "json_schema" response format). Adapters that don't support it ignore it. Name is the schema name; Schema is provider-neutral JSON Schema (as from the schema package). See RunTypedNative.

type Result ¶

type Result struct {
	// Message is the final assistant answer, identical to what Run / RunSaga return.
	Message Message

	// Usage is the sum of all model-call usages across the run (input, output, and
	// cache tokens accumulated across every turn).
	Usage Usage

	// Turns is the number of live model turns executed during this run (replayed turns
	// from the durable journal are not counted, since their usage was already accounted
	// for in the original run).
	Turns int

	// Duration is the wall-clock elapsed time for the run (from entry to return).
	Duration time.Duration

	// RunID echoes the run identifier passed to RunResult / RunSagaResult.
	RunID string
}

Result is a rich envelope returned by RunResult and RunSagaResult. It carries the terminal assistant message plus telemetry accumulated over the whole run: total token usage (sum of every model-call Usage), the number of model turns, wall-clock duration, and the run ID.

Run and RunSaga are unchanged and remain the idiomatic path for callers that only need the final message; RunResult / RunSagaResult are the additive counterparts for callers that need observability data.

type ResumeHalt ¶

type ResumeHalt struct {
	RunID     string
	ToolUseID string
	ToolName  string
	// AttemptedAt is when the effect was attempted (the attempt marker's timestamp), zero
	// if unknown. A reconciler uses it to honor a grace period before resolving (see
	// ResolveHalt with WithMinHaltAge) so it does not query the provider before its record
	// has settled.
	AttemptedAt time.Time
}

ResumeHalt is returned when resume can't safely proceed: a non-retriable tool was invoked but no result was recorded, so its outcome is unknown. The run stops for confirmation rather than risk a double side effect (e.g. a double charge).

It is also returned when another driver of the same run claimed the call first (see ClaimAttempt), for example a second node that took over after this node's lease lapsed. That driver owns the side effect; once it records the result, re-running proceeds normally.

func (e *ResumeHalt) Error() string

type Retriever ¶

type Retriever interface {
	Retrieve(ctx context.Context, query string, k int) ([]Doc, error)
}

Retriever is the bring-your-own-RAG port: given a query, return the top-k relevant documents from YOUR store (pgvector, Pinecone, a file index — anything). Bide ships no vector store and no embedder; you implement Retrieve against infrastructure you already run, and wire it in with RetrievalTool (agentic — the model searches on demand) or WithRetrieval (classic — top-k auto-injected as context on each user turn). Sessions already give conversational memory; this is the seam for semantic / long-term memory.

type Role ¶

type Role string

Role identifies the author of a Message.

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type Safety ¶

type Safety struct {
	// ReadOnly: no external side effects — always safe to re-run.
	ReadOnly bool
	// Idempotent: mutates state but is safe to retry, because a repeat with the same
	// key is a no-op downstream. Set IdempotencyKey to make that concrete.
	Idempotent bool
	// IdempotencyKey derives a stable key from the args so a retried call can be
	// de-duplicated. Empty result => not derivable.
	IdempotencyKey func(args json.RawMessage) string
	// RequiresApproval pauses the run for a durable human decision (HITL) before the
	// tool executes — surfaced as *PendingApproval; resume after agent.Approve.
	RequiresApproval bool
	// Approval, when non-nil, upgrades the approval gate from one
	// decision to an m-of-n human gate over a bounded, named set of
	// approvers. nil = the existing 1-of-1 RequiresApproval behavior.
	Approval *ApprovalPolicy
}

Safety declares how a tool may be retried when a run resumes after a crash and the call's outcome is unknown (it was invoked, but no result was journaled). Replaces a coarse Read/Write flag. Maps directly onto MCP tool annotations (readOnlyHint / idempotentHint / destructiveHint) for MCP-sourced tools.

type SagaAborted ¶

type SagaAborted struct {
	RunID         string
	Cause         error
	Compensated   []string
	Uncompensated []string
	CompensateErr error
}

SagaAborted is returned by RunSaga when a step failed and the transaction was rolled back. Compensated lists tools whose side effects were undone (reverse of execution, including sub-agent trees). Uncompensated lists completed WRITES that had no compensator — dangling side effects needing manual cleanup. CompensateErr is non-nil if a compensator itself failed: rollback stopped, so writes before it remain uncompensated.

func (e *SagaAborted) Error() string

func (e *SagaAborted) Unwrap() error

type Sampling ¶

type Sampling struct {
	Temperature *float64 // 0..2 (OpenAI) / 0..1 (Anthropic); determinism at 0
	TopP        *float64 // nucleus sampling
	MaxTokens   *int     // cap on generated tokens; overrides the adapter's construction default
	Stop        []string // stop sequences
	Seed        *int64   // best-effort determinism (OpenAI; ignored where unsupported)
}

Sampling holds provider-neutral generation controls. Pointer fields distinguish "unset" (nil → use the provider/model default) from an explicit value — so a deliberate Temperature of 0 is not confused with "not specified". Each adapter maps the set fields onto its wire format and ignores those it doesn't support (e.g. Anthropic has no Seed). Set it once with Agent.WithSampling.

type SamplingOption ¶

type SamplingOption func(*Sampling)

SamplingOption sets one field of the Sampling config; see Temperature, TopP, MaxTokens, Stop, Seed.

func MaxTokens(v int) SamplingOption

func Seed(v int64) SamplingOption

func Stop(seqs ...string) SamplingOption

func Temperature(v float64) SamplingOption

func TopP(v float64) SamplingOption

type ScriptedModel ¶

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

ScriptedModel is a deterministic, LLM-free Model that replays a fixed script of turns, one turn per model call. It is the batteries-included version of the model fakes people otherwise reverse-engineer from ToolCallDelta + Finish for tests, examples, and local dev, so you can drive the whole agent loop offline.

It is replay-safe: it selects the turn to emit by counting the assistant messages already in the request, not by an internal cursor. On a durable resume the agent loop replays journaled assistant turns without calling the model, so a cursor would drift; counting the transcript instead lines the script back up with the live turn every time, including after a crash and re-run. Once the script is exhausted it repeats its last turn, so an over-long conversation does not panic.

Build turns with ToolTurn, TextTurn, and ErrorTurn:

m := agent.NewScriptedModel(
    agent.ToolTurn("call-1", "lookup", `{"q":"weather"}`),
    agent.TextTurn("it is sunny"),
)
a := agent.New(m, agent.NewMemStore(), lookupTool)
out, err := a.Run(ctx, "run-1", "what's the weather?")

A ScriptedModel is safe for the sequential agent loop; it is not intended for concurrent Stream calls from multiple runs at once.

func NewScriptedModel(turns ...ScriptedTurn) *ScriptedModel

func (m *ScriptedModel) Stream(_ context.Context, req Request) (*Stream, error)

type ScriptedTurn ¶

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

ScriptedTurn is one scripted model output. Construct one with ToolTurn, TextTurn, or ErrorTurn rather than building it directly.

func ErrorTurn(err error) ScriptedTurn

func TextTurn(text string) ScriptedTurn

func ToolTurn(id, name, args string) ScriptedTurn

type Session ¶

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

Session is a durable multi-turn conversation. Each Send is one full agent run (tools, resume, side-effect safety and all), seeded with the transcript so far — so the agent remembers earlier turns. The transcript is journaled turn-by-turn under the session id, so a Session reloaded (after a restart) from the same store resumes the conversation.

Layering: turn N runs under runID "<id>/tN" (its own durable journal handles crash resume WITHIN the turn); the session-level journal under "<id>" records each completed turn's (input, answer) so the transcript can be rebuilt. Intermediate tool calls stay in the turn's journal and are NOT carried into later turns — the conversational memory is the question/answer transcript, not every tool call.

func (s *Session) History() []Message

func (s *Session) Send(ctx context.Context, input string) (Message, error)

func (s *Session) Turns() int

type Sleeping ¶

type Sleeping struct {
	RunID  string
	Name   string
	FireAt time.Time
}

Sleeping is returned by Run when a tool called Sleep or WaitUntil and the wake time has not yet passed. The run has paused durably at the timer: its wake time is journaled, so the pause survives a restart. Re-invoke Run with the same runID at or after FireAt to resume (a Waker does this automatically; otherwise the deployment re-invokes on its own schedule).

func (e *Sleeping) Error() string

type StepKind ¶

type StepKind string

StepKind records what a journal entry represents.

const (
	StepModel      StepKind = "model"       // an assistant message from the model
	StepToolResult StepKind = "tool_result" // a completed tool call + its result
	StepValue      StepKind = "value"       // a user-authored durable step (see Step[T])
	StepSignal     StepKind = "signal"      // an external event delivered into a run (see Signal/Await)
	StepApproval   StepKind = "approval"    // a durable human approve/deny decision (HITL)
	StepAttempt    StepKind = "attempt"     // "about to run a non-retriable side effect" marker
	StepSagaFail   StepKind = "saga_fail"   // a saga step failed → durable abort trigger
)

type Stream ¶

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

Stream is a live model response. Range over Events() for a streaming UI, OR call Message() to drain it into the fully-assembled assistant Message — not both (a Stream is consumed once).

func NewStream(ch <-chan Emit) *Stream

func (s *Stream) Events() iter.Seq2[Event, error]

func (s *Stream) Message() (Message, Usage, error)

type Task ¶

type Task[T any] struct {
	Name string
	Fn   func(context.Context) (T, error)
}

Task is one unit of durable parallel work: a named step returning a T. Name is the durable memoization key within the run, so it must be unique across the tasks in one Parallel call. Because each task is a journaled step, a resumed run returns a completed task's recorded result without re-running it, and that result is an independently provable record (see audit.ProveStep).

type Text ¶

type Text struct {
	Text string `json:"text"`
}

Text is plain assistant/user text.

type TextDelta ¶

type TextDelta struct{ Text string }

type Tool ¶

type Tool interface {
	Name() string
	Description() string
	// ArgsSchema is the provider-NEUTRAL argument schema. The schema/ package emits
	// per-provider dialects (OpenAI-strict / Gemini / Anthropic) from it — so this is
	// never a single frozen blob handed straight to a provider.
	ArgsSchema() json.RawMessage
	// Safety declares how the tool may be retried on resume.
	Safety() Safety
	Call(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

Tool is an action the agent can take. The interface is untyped (json.RawMessage) so heterogeneous tools share one type — including runtime MCP tools whose schema is only known at runtime and can't be a Go struct. Native tools get compile-time typing via Func (below); that's the primary ergonomic.

func CompensatedFunc[In, Out any](
	name, description string,
	safety Safety,
	do func(context.Context, In) (Out, error),
	undo func(context.Context, In, Out) error,
) Tool

func Func[In, Out any](name, description string, safety Safety, fn func(context.Context, In) (Out, error)) Tool

func RetrievalTool(r Retriever, k int) Tool

// Your store, behind the Retriever port (here a trivial in-memory one).
docs := map[string]string{"france": "Paris is the capital of France."}
r := retrieverFunc(func(_ context.Context, query string, _ int) ([]Doc, error) {
	if d, ok := docs[strings.ToLower(query)]; ok {
		return []Doc{{Text: d}}, nil
	}
	return nil, nil
})

tool := RetrievalTool(r, 1)
out, _ := tool.Call(context.Background(), json.RawMessage(`{"query":"france"}`))
fmt.Println(string(out))

Output:
[{"text":"Paris is the capital of France."}]

func SubAgent(name, description string, sub *Agent) Tool

type ToolCallDelta ¶

type ToolCallDelta struct {
	Index        int
	ID           string
	Name         string
	ArgsFragment json.RawMessage
}

ToolCallDelta is an incremental fragment of a tool call, keyed by Index. Fragments are concatenated and gated by json.Valid before use (the UTF-8/partial-JSON safety the research flagged as universally missing).

type ToolChoice ¶

type ToolChoice struct {
	Mode string // "", "auto", "none", "required", or "tool"
	Name string // tool name to force; only meaningful when Mode == "tool"
}

ToolChoice controls whether and how the model may call tools on a request. Mode is one of "" or "auto" (model decides, the default), "none" (never call a tool), "required" (must call some tool), or "tool" (must call the specific tool named in Name). A nil *ToolChoice on a Request means the provider default (auto).

CAVEAT: in the multi-turn agent loop, forcing "required" or "tool" on EVERY turn prevents the model from ever emitting a final text answer, so the loop never terminates. Those two modes are intended for single-turn or typed/structured calls where exactly one tool round-trip is expected. Use "auto" (the default) for the loop.

type ToolCompleted ¶

type ToolCompleted struct {
	ToolUseID string
	Name      string
	Result    json.RawMessage
	IsError   bool
}

ToolCompleted carries a tool call's result. Emitted for live executions, for a human-denied call, and for each result reconstructed from the journal on resume.

type ToolHandler ¶

type ToolHandler func(context.Context, ToolUse) (json.RawMessage, error)

ToolHandler executes one tool call: given the ToolUse (ID, Name, Args), it returns the raw JSON result or an error. It is the tool-side analogue of ModelHandler.

type ToolMiddleware ¶

type ToolMiddleware func(ToolHandler) ToolHandler

ToolMiddleware wraps a ToolHandler — the same func(Handler) Handler idiom as model Middleware, but around TOOL execution. First added = outermost. A middleware can:

• observe/log/trace a call (its name, args, duration, error);
• MUTATE the outgoing args (validate, redact, inject defaults) by calling next with a modified ToolUse;
• transform the result before it is journaled;
• SHORT-CIRCUIT — return a result (a cache hit) or an error (a policy denial) WITHOUT calling next, so the tool never runs.

The chain runs INSIDE the durable, memoized step, so a short-circuit result or a transformed result is what gets journaled — resume replays it and never re-runs the middleware or the tool. Batteries live in the middleware/ package (ToolLog, ToolCache).

type ToolResult ¶

type ToolResult struct {
	ToolUseID string          `json:"tool_use_id"`
	Result    json.RawMessage `json:"result,omitempty"`
	IsError   bool            `json:"is_error,omitempty"`
}

ToolResult carries a tool's output back to the model (tool turn).

type ToolResultCodec ¶ added in v0.2.0

type ToolResultCodec interface {
	EncodeToolResult(raw json.RawMessage) (string, error)
}

ToolResultCodec renders a tool result's canonical JSON bytes into the string content that is sent to the model. The journal always stores the JSON form (see Record.Result), so this only changes what the model reads: an adapter can hand the model a more token-efficient or better-comprehended encoding (for example GCF via github.com/bide-ai/bide/codec/gcf) without touching the durable record or the audit trail. Implementations must be pure and deterministic.

type ToolStarted ¶

type ToolStarted struct {
	ToolUseID string
	Name      string
	Args      json.RawMessage
}

ToolStarted fires when a tool call begins executing (after any approval gate and, for non-idempotent tools, after the durable attempt marker is written).

type ToolUse ¶

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

ToolUse is the model's request to call a tool (assistant turn).

func FindToolCall(recs []Record, toolUseID string) (idx int, call ToolUse, ok bool)

type TurnStarted ¶

type TurnStarted struct{ Seq int }

TurnStarted marks the beginning of a fresh model turn (Seq is the model-call sequence number within the run). Not emitted for turns replayed from the journal.

type Usage ¶

type Usage struct {
	InputTokens  int
	OutputTokens int
	// CacheReadTokens is input tokens served from the provider's prompt cache (billed at
	// a discount). CacheWriteTokens is input tokens written to the cache on this call
	// (Anthropic cache creation; 0 for providers that cache implicitly, like OpenAI).
	CacheReadTokens  int
	CacheWriteTokens int
}

Usage is token accounting for a call; middleware turns it into cost.

type Waker ¶

type Waker interface {
	// Schedule registers that runID should be resumed at fireAt, idempotent per (runID, name).
	Schedule(runID, name string, fireAt time.Time)
}

Waker is the pluggable trigger that re-invokes a sleeping run when its durable timer is due. Sleep registers a wake with the Waker bound to the run's context (WithWaker); the Waker later calls back to resume the run. The SDK provides the durable, at-most-once timer and its resume safety; what re-invokes the run at the wake time is deployment policy (an in-process loop, a cron, a queue), exactly as the inbound trigger for an event-driven run is (see docs/MESSAGING.md). MemWaker is the reference in-process implementation.