Package com.google.genkit.ai.agent.internal

Class SessionResolver

java.lang.Object

com.google.genkit.ai.agent.internal.SessionResolver

public final class SessionResolver
extends Object

Resolves a Session from an AgentInit at the start of an agent invocation.

Enforces the server-vs-client state-management rules:

• API misuse (wrong init for the state-management mode, ownership mismatch) throws GenkitException with FAILED_PRECONDITION or INVALID_ARGUMENT.
• Other pre-turn failures are returned as a SessionResolver.Resolution.failure(com.google.genkit.ai.agent.RuntimeError) so the agent can emit an AgentOutput with finishReason=FAILED rather than surfacing as an unhandled exception.

Pending-leaf decision

When resolving by sessionId and the latest leaf snapshot has a non-COMPLETED status (e.g. PENDING, FAILED, ABORTED), this implementation throws GenkitException with FAILED_PRECONDITION. This matches Go's resumeSessionFrom behavior and is simpler than the JS approach of walking back to the last completed snapshot. The error is conformance-tested; callers should clear or complete any in-progress snapshot before starting a new turn.

Unknown-snapshot decision

When a specific snapshotId is provided but not found in the store, this implementation throws GenkitException with INVALID_ARGUMENT. An unknown snapshotId is treated as API misuse (the client provided a bad reference), not as a recoverable pre-turn error. This matches the design spec §6.4 note: "unknown snapshot → throw/404".

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	SessionResolver.Resolution<S>	Result of session resolution: either a ready Session, or a graceful pre-turn failure.

Method Summary

Modifier and Type	Method	Description
static <S> SessionResolver.Resolution<S>	resolve(SessionStore<S> store, boolean serverManaged, AgentInit<S> init, SessionStoreOptions opts)	Resolves a Session from the given AgentInit.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

resolve

public static <S> SessionResolver.Resolution<S> resolve(SessionStore<S> store,
 boolean serverManaged,
 AgentInit<S> init,
 SessionStoreOptions opts)

Resolves a Session from the given AgentInit.

Rules (see class-level Javadoc for details):

1. State-management mismatch → throws GenkitException.
2. Client-managed: hydrate from init.state or mint a fresh session.
3. Server-managed: resolve via snapshotId, sessionId, or mint fresh.

Type Parameters:

S - the type of custom session state

Parameters:

store - the agent's session store, or null for client-managed agents

serverManaged - true iff the agent has a store (server-managed)

init - the agent init (may be null — treated as all fields null)

opts - options forwarded to store operations (may be null)

Returns:

a SessionResolver.Resolution wrapping either the resolved session or a graceful failure

Throws:

GenkitException - with FAILED_PRECONDITION or INVALID_ARGUMENT for API misuse (wrong init for the state-management mode, or ownership mismatch)