exp

type Agent[State any] struct {
	// contains filtered or unexported fields
}

type AgentAbortRequest struct {
	// SnapshotID identifies the snapshot whose invocation should be aborted.
	SnapshotID string `json:"snapshotId"`
}

type AgentAbortResponse struct {
	// SnapshotID identifies the snapshot the abort attempt targeted.
	SnapshotID string `json:"snapshotId"`
	// Status is the snapshot's status after the abort attempt. For a
	// pending snapshot this is [SnapshotStatusAborted]. For an
	// already-terminal snapshot this is the existing terminal status (the
	// abort is a no-op).
	Status SnapshotStatus `json:"status,omitempty"`
}

type AgentConnection[State any] struct {
	// contains filtered or unexported fields
}

type AgentFinishReason string

type AgentFunc[State any] = func(ctx context.Context, resp Responder, sess *SessionRunner[State]) (*AgentResult, error)

type AgentInit[State any] struct {
	// SessionID identifies the session (conversation) to resume or start. Only
	// valid when the agent is server-managed (a session store is configured);
	// mutually exclusive with State. Alone, it resumes the session's latest
	// snapshot, rejected if that snapshot is a failed, aborted, or pending dead
	// end. If the session has no snapshots yet, a fresh conversation starts under
	// this caller-chosen ID. Combined with SnapshotID, it asserts the snapshot
	// belongs to that session.
	SessionID string `json:"sessionId,omitempty"`
	// SnapshotID loads state from a persisted snapshot. Only valid when the
	// agent is server-managed (a session store is configured). May be
	// combined with SessionID to validate that the snapshot belongs to that
	// session. Mutually exclusive with State.
	SnapshotID string `json:"snapshotId,omitempty"`
	// State provides direct state for the invocation. Only valid when the agent
	// is client-managed (no session store). The conversation's identity rides
	// inside it ([SessionState.SessionID]). Mutually exclusive with SessionID and
	// SnapshotID.
	State *SessionState[State] `json:"state,omitempty"`
}

type AgentInput struct {
	// Detach signals the client will disconnect after this input is accepted. The
	// server writes a pending snapshot, returns [AgentOutput] with its ID, and
	// keeps processing any already-buffered inputs in the background. The pending
	// snapshot is finalized with the cumulative final state once the queued inputs
	// are processed (or the invocation is aborted).
	Detach bool `json:"detach,omitempty"`
	// Message is the user's input for this turn.
	Message *ai.Message `json:"message,omitempty"`
	// Resume provides options for resuming an interrupted generation.
	// Construct using [ai.ToolDef.RestartWith] / [ai.ToolDef.RespondWith]
	// parts. When set, the generate call resumes with these parts instead
	// of treating Message as a tool response.
	Resume *ToolResume `json:"resume,omitempty"`
}

type AgentMetadata struct {
	// Abortable reports whether the agent's invocations can be aborted
	// (true when the store implements [SnapshotSubscriber]).
	Abortable bool `json:"abortable,omitempty"`
	// StateManagement reports who owns session state.
	StateManagement AgentStateManagement `json:"stateManagement,omitempty"`
	// StateSchema is the JSON schema for the agent's custom session state
	// (the Custom field of [SessionState]), inferred from the agent's state
	// type. It lets the Dev UI and other reflective callers render or
	// validate state without the agent describing it separately. Nil when the
	// state type carries no schema to infer (e.g. an unstructured any state).
	StateSchema map[string]any `json:"stateSchema,omitempty"`
}

type AgentOption[State any] interface {
	// contains filtered or unexported methods
}

type AgentOutput[State any] struct {
	// Artifacts contains artifacts produced during the session.
	Artifacts []*Artifact `json:"artifacts,omitempty"`
	// Error is the structured failure information when the invocation ended in
	// failure (FinishReason is [AgentFinishReasonFailed]). Its Status preserves
	// the original error category (e.g. INVALID_ARGUMENT, FAILED_PRECONDITION,
	// INTERNAL) so callers can still branch on it. Nil otherwise.
	Error *core.GenkitError `json:"error,omitempty"`
	// FinishReason is why the invocation finished. It is
	// [AgentFinishReasonDetached] when the client detached and the work continues
	// in the background, or [AgentFinishReasonFailed] when the invocation ended
	// in failure (see [AgentOutput.Error]); otherwise it is the last turn's
	// reason (or the value a custom agent set on its [AgentResult]).
	FinishReason AgentFinishReason `json:"finishReason,omitempty"`
	// Message is the last model response message from the conversation.
	Message *ai.Message `json:"message,omitempty"`
	// SessionID is the ID of the session this invocation belongs to, assigned by
	// the framework when the invocation starts and stable across resumes. Pass it
	// to [WithSessionID] to resume a server-managed session; with client-managed
	// state it also rides inside [AgentOutput.State] ([SessionState.SessionID]).
	SessionID string `json:"sessionId,omitempty"`
	// SnapshotID is the ID of the most recent turn-end snapshot for this
	// invocation. Empty when no store is configured or no turn committed. When
	// FinishReason is [AgentFinishReasonDetached] it is the pending detach
	// snapshot; when [AgentFinishReasonFailed], it is the last committed turn's
	// snapshot (the resume point, holding state through the last successful turn
	// and excluding the failed turn's partial mutations).
	SnapshotID string `json:"snapshotId,omitempty"`
	// State contains the final conversation state.
	// Only populated when state is client-managed (no store configured).
	// When FinishReason is [AgentFinishReasonFailed], it is the last-good state:
	// everything through the last successful turn, excluding the failed turn's
	// partial mutations.
	State *SessionState[State] `json:"state,omitempty"`
}

type AgentRef struct {
	// Name identifies the agent, resolved as /agent/<Name>. Required.
	Name string `json:"name"`
	// Description is a human-readable description used by consumers that list
	// agents (e.g. the agents middleware's system prompt). [Agent.Ref] fills it
	// from the agent's descriptor. Optional.
	Description string `json:"description,omitempty"`
}

type AgentResult struct {
	// Artifacts contains artifacts produced during the session.
	Artifacts []*Artifact `json:"artifacts,omitempty"`
	// FinishReason is why the invocation finished. A custom agent may set it to
	// override the default (the last turn's reason); leave it empty to accept the
	// default.
	FinishReason AgentFinishReason `json:"finishReason,omitempty"`
	// Message is the last model response message from the conversation.
	Message *ai.Message `json:"message,omitempty"`
}

type AgentStateManagement string

type AgentStreamChunk struct {
	// Artifact contains a newly produced artifact.
	Artifact *Artifact `json:"artifact,omitempty"`
	// CustomPatch is an RFC 6902 JSON Patch describing a delta to the session's
	// custom state, emitted automatically whenever the agent mutates it (e.g. via
	// [Session.UpdateCustom]). Pointers are rooted at the custom document (e.g.
	// "/agentStatus"), with no "/custom" prefix. The first patch of each turn is a
	// whole-document replace at the root pointer ("") to re-base the client; later
	// patches are incremental diffs. Apply it with [ApplyPatch] to keep a local
	// copy of custom state live as the turn streams.
	CustomPatch JSONPatch `json:"customPatch,omitempty"`
	// ModelChunk contains generation tokens from the model.
	ModelChunk *ai.ModelResponseChunk `json:"modelChunk,omitempty"`
	// TurnEnd is non-nil when the agent has finished processing the current
	// input. It groups all turn-end signals (snapshot ID, etc.) so callers can
	// check a single field. When set, the client should stop iterating and may
	// send the next input.
	TurnEnd *TurnEnd `json:"turnEnd,omitempty"`
}

type Artifact struct {
	// Metadata contains additional artifact-specific data.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Name identifies the artifact (e.g., "generated_code.go", "diagram.png").
	Name string `json:"name,omitempty"`
	// Parts contains the artifact content (text, media, etc.).
	Parts []*ai.Part `json:"parts"`
}

type ArtifactStore interface {
	// Artifacts returns a snapshot of the session's current artifacts.
	Artifacts() []*Artifact
	// AddArtifacts adds artifacts, replacing any existing artifact of the same
	// name.
	AddArtifacts(artifacts ...*Artifact)
}

type GetSnapshotRequest struct {
	// SessionID identifies the session whose latest snapshot to fetch.
	// Optional when SnapshotID is given. The latest snapshot is the session's
	// most recently updated row regardless of status (pending, failed, or
	// aborted included).
	SessionID string `json:"sessionId,omitempty"`
	// SnapshotID identifies the snapshot to fetch. Optional when SessionID is
	// given; when both are present the fetched snapshot must belong to that
	// session.
	SnapshotID string `json:"snapshotId,omitempty"`
}

type InlinePrompt []ai.PromptOption

type InterruptibleTool[In, Out, Res any] struct {
	Tool[In, Out]
}

type InterruptibleToolFunc[In, Out, Resume any] = func(ctx context.Context, input In, res *Resume) (Out, error)

type InvocationOption[State any] interface {
	// contains filtered or unexported methods
}

type JSONPatch []*JSONPatchOperation

type JSONPatchOp string

type JSONPatchOperation struct {
	// From is a JSON Pointer to the source location; required for "move" and "copy".
	From string `json:"from,omitempty"`
	// Op is the operation to perform.
	Op JSONPatchOp `json:"op"`
	// Path is a JSON Pointer (RFC 6901) to the target location, e.g. "/agentStatus".
	// The empty pointer "" refers to the whole document.
	Path string `json:"path"`
	// Value is the operand for "add", "replace", and "test"; an explicit null is a
	// valid operand. Ignored for "remove", "move", and "copy".
	Value any `json:"value"`
}

type PromptAgentOption[State any] interface {
	// contains filtered or unexported methods
}

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

type Session[State any] struct {
	// contains filtered or unexported fields
}

type SessionRunner[State any] struct {
	*Session[State]
	// contains filtered or unexported fields
}

type SessionSnapshot[State any] struct {
	// CreatedAt is when the snapshot was created.
	CreatedAt time.Time `json:"createdAt"`
	// Error is the structured failure information for a snapshot in
	// [SnapshotStatusFailed]. Nil otherwise.
	Error *core.GenkitError `json:"error,omitempty"`
	// FinishReason is the semantic reason the turn or invocation captured here
	// ended (e.g. [AgentFinishReasonStop], [AgentFinishReasonInterrupted],
	// [AgentFinishReasonFailed], [AgentFinishReasonAborted]). It complements
	// [SessionSnapshot.Status] (the persistence lifecycle) so a resumed or
	// background task can report how it ended without re-deriving it from the
	// messages.
	FinishReason AgentFinishReason `json:"finishReason,omitempty"`
	// HeartbeatAt is refreshed periodically while a detached (background) turn is
	// in flight, so a reader can detect a dead background worker: if a pending
	// snapshot's heartbeat goes stale (older than the configured timeout), reads
	// surface its status as [SnapshotStatusExpired] (the dead worker can no longer
	// persist a terminal status itself). Refreshing it does not advance
	// [SessionSnapshot.UpdatedAt], so liveness stays distinct from state changes. Nil
	// on snapshots that never detached.
	HeartbeatAt *time.Time `json:"heartbeatAt,omitempty"`
	// ParentID is the ID of the previous snapshot in this timeline. It is
	// informational lineage (for debugging and UI history trees) and plays
	// no part in resolving a session's latest snapshot.
	ParentID string `json:"parentId,omitempty"`
	// SessionID is the ID of the session this snapshot belongs to. Assigned by the
	// framework on the conversation's first invocation and stamped on every later
	// snapshot in the chain, across resumed invocations; stores preserve it across
	// rewrites.
	SessionID string `json:"sessionId,omitempty"`
	// SnapshotID is the unique identifier for this snapshot (UUID).
	SnapshotID string `json:"snapshotId"`
	// State is the conversation state captured at this point. Nil on a
	// pending snapshot (the live state is not yet committed; the background
	// invocation is still processing queued inputs); populated on terminal
	// snapshots with the cumulative final state.
	State *SessionState[State] `json:"state,omitempty"`
	// Status is the lifecycle state of this snapshot. Empty is treated as
	// [SnapshotStatusCompleted] for backwards compatibility.
	Status SnapshotStatus `json:"status,omitempty"`
	// UpdatedAt is when the snapshot's state was last written. A heartbeat refresh on
	// a pending snapshot deliberately does not advance it, so a pending snapshot's
	// UpdatedAt equals CreatedAt until the snapshot is finalized, whose terminal write
	// advances it.
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

type SessionState[State any] struct {
	// Artifacts are named collections of parts produced during the conversation.
	Artifacts []*Artifact `json:"artifacts,omitempty"`
	// Custom is the user-defined state associated with this conversation.
	Custom State `json:"custom,omitempty"`
	// Messages is the conversation history (user/model exchanges).
	// Does NOT include prompt-rendered messages — those are rendered fresh each turn.
	Messages []*ai.Message `json:"messages,omitempty"`
	// SessionID is the ID of the session (conversation) this state belongs to.
	// Framework-owned: assigned on the conversation's first invocation and
	// re-stamped on outbound state, so client-managed callers can round-trip the
	// state object opaquely. For server-managed agents the snapshot row's
	// [SessionSnapshot.SessionID] is canonical and this field mirrors it.
	SessionID string `json:"sessionId,omitempty"`
}

type SessionStore[State any] interface {
	SnapshotReader[State]
	SnapshotWriter[State]
}

type SnapshotReader[State any] interface {
	// GetSnapshot retrieves a snapshot by ID. Returns nil if not found.
	GetSnapshot(ctx context.Context, snapshotID string) (*SessionSnapshot[State], error)

	// GetLatestSnapshot returns the session's most recently created
	// snapshot, whatever its status: a pending, failed, or aborted row is
	// returned like any other, and the caller applies its own policy.
	// Returns nil if the session has no rows, and an error if sessionID is
	// empty.
	//
	// "Most recently created" means the greatest [SessionSnapshot.CreatedAt];
	// break ties deterministically (e.g. by SnapshotID). This is a plain
	// max-timestamp lookup, implementable as a single indexed query (e.g.
	// WHERE sessionId = ? ORDER BY createdAt DESC LIMIT 1). A later rewrite of
	// an older row (e.g. a detach finalize) does not move it ahead of a
	// newer-created sibling, since CreatedAt is preserved across rewrites.
	// ParentID is informational lineage and plays no part in resolution: when
	// history forks, the most recently created branch wins.
	GetLatestSnapshot(ctx context.Context, sessionID string) (*SessionSnapshot[State], error)
}

type SnapshotStatus string

type SnapshotSubscriber interface {
	// OnSnapshotStatusChange returns a channel that yields the snapshot's
	// status whenever it changes. The first value (if any) reflects the
	// status at subscription time. The channel is closed when ctx is
	// cancelled. If the snapshot does not exist when the subscription is
	// established, the channel is closed without yielding a value.
	//
	// Implementations may push changes from a transaction log or CDC feed,
	// or poll internally.
	OnSnapshotStatusChange(ctx context.Context, snapshotID string) <-chan SnapshotStatus
}

type SnapshotWriter[State any] interface {
	// SaveSnapshot atomically reads the snapshot at id (if any), applies
	// fn, and persists the result largely verbatim. The store owns only
	// identity; the caller (fn) owns the lifecycle timestamps and status:
	//
	//   - SnapshotID: if id is empty, the store generates a fresh ID;
	//     otherwise the store uses id (any SnapshotID populated by fn is
	//     overridden).
	//   - SessionID: the ID of the session (chain of snapshots) the row
	//     belongs to: preserved from the existing row on update (a row's
	//     session never changes once set), otherwise taken from fn's row
	//     as-is. Stores never mint or infer session IDs.
	//   - CreatedAt / UpdatedAt: caller-managed. The store persists whatever fn
	//     returns and never stamps them. fn sets CreatedAt and UpdatedAt to the
	//     current time on a new row, preserves CreatedAt and advances UpdatedAt
	//     on a state-changing rewrite, and preserves both on a non-state write
	//     (e.g. a heartbeat refresh, which carries the existing snapshot through
	//     unchanged but for HeartbeatAt). Keeping timestamps with the caller is
	//     what lets a heartbeat advance liveness without registering as a state
	//     change - the store has no special heartbeat path.
	//   - Status: if the snapshot returned by fn has Status="", it is
	//     defaulted to [SnapshotStatusCompleted] (the common case for
	//     synchronous turn-end writes). Callers writing a pending row must
	//     set Status explicitly.
	//
	// fn receives the existing snapshot (or nil if id is empty or the
	// row does not exist) and returns the snapshot to commit, or
	// (nil, nil) to skip the write without changing the row.
	//
	// Under contention, stores that use optimistic concurrency or
	// transaction retries may call fn multiple times. fn must therefore
	// be a pure function of its input: no side effects (channel sends,
	// logging, external I/O) inside fn.
	//
	// Returns the snapshot as persisted (with the store-owned fields
	// populated), or nil if fn declined to write.
	SaveSnapshot(
		ctx context.Context,
		snapshotID string,
		fn func(existing *SessionSnapshot[State]) (*SessionSnapshot[State], error),
	) (*SessionSnapshot[State], error)
}

type StateTransform[State any] = func(ctx context.Context, state *SessionState[State]) (*SessionState[State], error)

type StreamTransform = func(ctx context.Context, chunk *AgentStreamChunk) (*AgentStreamChunk, error)

type Tool[In, Out any] struct {
	// contains filtered or unexported fields
}

type ToolFunc[In, Out any] = func(ctx context.Context, input In) (Out, error)

type ToolResume struct {
	// Respond contains tool response parts to send to the model when resuming.
	Respond []*ai.Part `json:"respond,omitempty"`
	// Restart contains tool request parts to restart when resuming.
	Restart []*ai.Part `json:"restart,omitempty"`
}

type TurnContext struct {
	// SnapshotID is the ID the turn-end snapshot will be saved under, minted
	// before the turn runs so the handler knows it in advance. A server-managed
	// turn persists its snapshot under this ID on success. It is empty for a
	// client-managed agent (no store, so no snapshot) and is the reserved-but-
	// unused ID for a turn that writes none (a failed turn, or one whose
	// snapshots a detach suspended).
	SnapshotID string
	// ParentSnapshotID is the ID of the snapshot this turn continues from: the
	// previous turn's snapshot, or the snapshot the invocation resumed from. It
	// is empty on the first turn of a fresh conversation and for a
	// client-managed agent.
	ParentSnapshotID string
	// TurnIndex is the zero-based index of this turn within the invocation.
	TurnIndex int
}

type TurnEnd struct {
	// FinishReason is why this turn finished (e.g. [AgentFinishReasonStop],
	// [AgentFinishReasonInterrupted]). It lets a caller react to a turn boundary
	// (such as pausing on an interrupt) without scanning the message content.
	// Empty when the turn reported no reason.
	//
	// [AgentFinishReasonFailed] reports a failed turn; unless the agent
	// recovers and keeps processing, the invocation then resolves with a failed
	// [AgentOutput] carrying the error and the last-good state, and further
	// sends fail with [core.ErrActionCompleted].
	FinishReason AgentFinishReason `json:"finishReason,omitempty"`
	// SnapshotID is the ID of the snapshot persisted at the end of this turn.
	// Empty if no snapshot was written (no store configured, the turn failed, or
	// snapshots were suspended after detach).
	SnapshotID string `json:"snapshotId,omitempty"`
}

type TurnResult struct {
	// FinishReason is why this turn ended (e.g. [AgentFinishReasonStop],
	// [AgentFinishReasonInterrupted]). Empty to report no reason.
	FinishReason AgentFinishReason
}