DefaultAgentStateController

Default agent state controller extracted from Runtime.

Handles:

• Active agent resolution with fallback
• Handoff recording in session.handoffHistory + session.metadata.handoffHistory
• Per-agent state updates in session.agentStates
• Circular handoff detection

Implements

• AgentStateController

Constructors

Constructor

new DefaultAgentStateController(): DefaultAgentStateController;

Returns

DefaultAgentStateController

Methods

clearAgent()

clearAgent(session, agentId): void;

Remove per-agent state from session.agentStates. No-op if absent.

Parameters

Parameter	Type
session	Session
agentId	string

Returns

void

Implementation of

AgentStateController.clearAgent

---

getActiveAgent()

getActiveAgent(session, fallbackAgentId): string;

Resolve the active agent ID, falling back to the provided default.

Parameters

Parameter	Type
session	Session
fallbackAgentId	string

Returns

string

Implementation of

AgentStateController.getActiveAgent

---

getAgentState()

getAgentState<T>(session, agentId): T | undefined;

Read per-agent state with optional type assertion. Returns undefined if absent or empty.

Type Parameters

Type Parameter	Default type
T	Record<string, unknown>

Parameters

Parameter	Type
session	Session
agentId	string

Returns

T | undefined

Implementation of

AgentStateController.getAgentState

---

isCircularHandoff()

isCircularHandoff(
   handoffStack,
   agentId,
   maxVisits?): boolean;

Check whether visiting the given agent would constitute a circular handoff. Returns true if the agent has been visited >= maxVisits times in the handoff stack.

Parameters

Parameter	Type	Default value
handoffStack	string[]	undefined
agentId	string	undefined
maxVisits	number	2

Returns

boolean

Implementation of

AgentStateController.isCircularHandoff

---

recordHandoff()

recordHandoff(args): void;

Record a handoff in the session’s handoff history.

Parameters

Parameter	Type
args	{ fromAgentId: string; reason: string; session: Session; toAgentId: string; }
args.fromAgentId	string
args.reason	string
args.session	Session
args.toAgentId	string

Returns

void

Implementation of

AgentStateController.recordHandoff

---

setActiveAgent()

setActiveAgent(session, agentId): void;

Set the active agent on the session.

Parameters

Parameter	Type
session	Session
agentId	string

Returns

void

Implementation of

AgentStateController.setActiveAgent

---

setAgentState()

setAgentState(
   session,
   agentId,
   state): void;

Replace per-agent state fully (no merge). Use when the state is a single opaque blob.

Parameters

Parameter	Type
session	Session
agentId	string
state	Record<string, unknown>

Returns

void

Implementation of

AgentStateController.setAgentState

---

updateAgentState()

updateAgentState(
   session,
   agentId,
   state): void;

Update per-agent state stored in session.agentStates. Merges with existing state.

Parameters

Parameter	Type
session	Session
agentId	string
state	Record<string, unknown>

Returns

void

Implementation of

AgentStateController.updateAgentState