类class io.agentscope.harness.coding.session preview

SessionAgentManager

public class SessionAgentManager

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:68–924

会话智能体管理器，在多次调用之间保存和恢复会话与记忆数据。位于 io.agentscope.harness.coding.session 包。核心成员包括 setAnnounceDispatcher、setSpawnInterceptor、delegate、getConfig、getRunRegistry、getAgentFactories。

Full session management implementation built on top of DefaultAgentManager. Owns *all * session-related state and concurrency controls:

AgentStateStore registry (sessionsByKey, labels, parent-child)
Lane management (semaphores for bounded concurrency, per-session locks)
SubagentRunRegistry for run lifecycle tracking
#registerSession / #registerMainSession — session creation
#execute — lane-aware, locked agent execution
Pending completions queue (announce) — #drainPendingCompletions
Announce dispatch — AnnounceDispatcher
Full SessionView, HistoryResult views
AgentStateStore listing with kind/time filters

Uses DefaultAgentManager only for agent creation (DefaultAgentManager#createAgent) and invocation (DefaultAgentManager#invokeAgent).

Used by SessionsTool and io.agentscope.harness.coding.gateway.HarnessGateway when the full orchestration stack is active.

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`AnnounceDispatcher`	接口interface	定义 Announce 调度器契约的接口。 Callback invoked when a subagent run completes and an announce payload is ready.
`SpawnInterceptor`	接口interface	定义 Spawn 拦截器契约的接口。 Callback invoked after a subagent session is spawned through this manager.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `SessionAgentManager(DefaultAgentManager delegate, AgentManagerConfig config, SubagentRunRegistry runRegistry, SessionStore sessionStore)`	初始化 `SessionAgentManager` 实例。 Creates a new instance.
`public` `SessionAgentManager(DefaultAgentManager delegate, AgentManagerConfig config, SubagentRunRegistry runRegistry)`	初始化 `SessionAgentManager` 实例。 Constructor without SessionStore (no metadata persistence).

方法摘要Method Summary

方法Method	说明Description
`public void setAnnounceDispatcher(AnnounceDispatcher dispatcher)`	设置 `setAnnounceDispatcher`。 Sets the announce dispatcher.
`public void setSpawnInterceptor(SpawnInterceptor interceptor)`	设置 `setSpawnInterceptor`。 Sets the spawn interceptor.
`public` `DefaultAgentManager delegate()`	返回委托。 The underlying agent factory/invoker this session manager delegates to.
`public` `AgentManagerConfig getConfig()`	获取配置。 Returns the config.
`public` `SubagentRunRegistry getRunRegistry()`	获取运行注册表。 Returns the run registry.
`public Map<String,` `SubagentFactory> getAgentFactories()`	获取 `getAgentFactories`。 Returns the agent factories.
`public` `SessionStore getSessionStore()`	获取会话存储。 The durable session registry, or null if not configured.
`public Optional<String> resolveSessionKey(String keyOrLabel)`	解析会话键。 Performs the resolve session key operation.
`public boolean exists(String sessionKey)`	判断数据是否存在。 Performs the exists operation.
`public Optional<SessionEntry> getSession(String sessionKey)`	获取会话。 Returns the session.
`public Collection<SessionEntry> allSessions()`	返回所有会话。 Returns the all sessions.
`public List<String> listChildren(String parentSessionKey)`	列出子级。 Lists the children.
`public` `SpawnResult registerSession(String agentId, String label, String parentSessionKey, int parentSpawnDepth)`	注册会话。 Registers the session.
`public` `SpawnResult registerSession(String agentId, String label, String parentSessionKey, int parentSpawnDepth, String userId)`	注册会话。 Registers a new subagent session, optionally inheriting the `userId` from its parent for continued namespace isolation.
`public` `SpawnResult registerMainSession(String agentId, String label)`	注册主会话。 Registers the main session.
`public` `SpawnResult registerMainSession(String agentId, String label, String gateKey)`	注册主会话。 Registers the main session.
`public` `SpawnResult registerMainSession(String agentId, String label, String gateKey, String userId)`	注册主会话。 Registers a new MAIN session, optionally recording the `gateKey` for gateway routing persistence and `userId` for HarnessAgent namespace isolation.
`public Optional<SessionView> viewSession(String sessionKey)`	设置该参数。 Performs the view session operation.
`public` `SpawnResult registerReviewerSession(String agentId, String label, String gateKey, String userId)`	注册 `registerReviewerSession`。 Registers a new REVIEWER session.
`public` `SendResult execute(String sessionKeyOrLabel, String prompt, long timeoutMs)`	执行执行相关操作。 Performs the execute operation.
`public` `SendResult execute(String sessionKeyOrLabel, String prompt, long timeoutMs, boolean announceToRequesterOnComplete, CommandLane lane)`	执行执行相关操作。 Performs the execute operation.
`public void evictAgent(String sessionKey)`	设置该参数。 Evicts the cached agent for the given session key.
`public int runMaintenance()`	运行维护。 Runs session maintenance: prunes stale sessions and caps total entries.
`public void removeSession(String sessionKey)`	移除会话。 Removes a session from all registries (in-memory, store, agent cache).
`public List<SessionView> list(Set<String> kinds, int limit, int activeMinutes)`	执行列表相关操作。 Performs the list operation.
`public` `HistoryResult history(String sessionKeyOrLabel, int limit)`	执行历史相关操作。 Performs the history operation.
`public List<PendingCompletion> drainPendingCompletions(String requesterSessionKey, int limit)`	执行 `drainPendingCompletions` 方法。 Performs the drain pending completions operation.
`public int pendingCompletionCount(String requesterSessionKey)`	设置待处理补全数量。 Performs the pending completion count operation.
`public String resolveSessionFilePath(String agentId, String sessionId)`	解析会话文件路径。 Resolves the session file path for a given agent and session.

构造器详情Constructor Detail

SessionAgentManager

public SessionAgentManager(DefaultAgentManager delegate, AgentManagerConfig config, SubagentRunRegistry runRegistry, SessionStore sessionStore)

初始化 SessionAgentManager 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`delegate`	DefaultAgentManager	委托（类型 `DefaultAgentManager`）。agent factory/invoker
`config`	AgentManagerConfig	配置对象（类型 `AgentManagerConfig`）。concurrency and announce tuning
`runRegistry`	SubagentRunRegistry	运行注册表（类型 `SubagentRunRegistry`）。run lifecycle tracking
`sessionStore`	SessionStore	会话存储（类型 `SessionStore`）。durable session registry for metadata persistence; may be null

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:121–135

SessionAgentManager

public SessionAgentManager(DefaultAgentManager delegate, AgentManagerConfig config, SubagentRunRegistry runRegistry)

初始化 SessionAgentManager 实例。

Constructor without SessionStore (no metadata persistence).

参数Parameters

名称Name	类型Type	说明Description
`delegate`	DefaultAgentManager	委托（类型 `DefaultAgentManager`）。The delegate.
`config`	AgentManagerConfig	配置对象（类型 `AgentManagerConfig`）。The config.
`runRegistry`	SubagentRunRegistry	运行注册表（类型 `SubagentRunRegistry`）。The run registry.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:138–143

方法详情Method Detail

setAnnounceDispatcher

public void setAnnounceDispatcher(AnnounceDispatcher dispatcher)

设置 setAnnounceDispatcher。

Sets the announce dispatcher.

参数Parameters

名称Name	类型Type	说明Description
`dispatcher`	AnnounceDispatcher	调度器（类型 `AnnounceDispatcher`）。The dispatcher.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:170–172

setSpawnInterceptor

public void setSpawnInterceptor(SpawnInterceptor interceptor)

设置 setSpawnInterceptor。

Sets the spawn interceptor.

参数Parameters

名称Name	类型Type	说明Description
`interceptor`	SpawnInterceptor	拦截器（类型 `SpawnInterceptor`）。The interceptor.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:174–176

delegate

public DefaultAgentManager delegate()

返回委托。

The underlying agent factory/invoker this session manager delegates to.

返回Returns DefaultAgentManager

返回DefaultAgentManager。Returns default agent manager.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:179–181

getConfig

public AgentManagerConfig getConfig()

获取配置。

Returns the config.

返回Returns AgentManagerConfig

返回AgentManagerConfig。Returns agent manager config.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:187–189

getRunRegistry

public SubagentRunRegistry getRunRegistry()

获取运行注册表。

Returns the run registry.

返回Returns SubagentRunRegistry

返回SubagentRunRegistry。Returns subagent run registry.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:191–193

getAgentFactories

public Map<String, SubagentFactory> getAgentFactories()

获取 getAgentFactories。

Returns the agent factories.

返回Returns Map<String, SubagentFactory>

返回映射。Returns map.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:195–197

getSessionStore

public SessionStore getSessionStore()

获取会话存储。

The durable session registry, or null if not configured.

返回Returns SessionStore

返回SessionStore。Returns session store.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:200–202

resolveSessionKey

public Optional<String> resolveSessionKey(String keyOrLabel)

解析会话键。

Performs the resolve session key operation.

参数Parameters

名称Name	类型Type	说明Description
`keyOrLabel`	String	键或标签（类型 `String`）。The key or label.

返回Returns Optional<String>

返回可选。Returns optional.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:208–221

exists

public boolean exists(String sessionKey)

判断数据是否存在。

Performs the exists operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionKey`	String	会话键（类型 `String`）。The session key.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:223–225

getSession

public Optional<SessionEntry> getSession(String sessionKey)

获取会话。

Returns the session.

参数Parameters

名称Name	类型Type	说明Description
`sessionKey`	String	会话键（类型 `String`）。The session key.

返回Returns Optional<SessionEntry>

返回可选。Returns optional.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:227–232

allSessions

public Collection<SessionEntry> allSessions()

返回所有会话。

Returns the all sessions.

返回Returns Collection<SessionEntry>

返回集合。Returns collection.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:234–236

listChildren

public List<String> listChildren(String parentSessionKey)

列出子级。

Lists the children.

参数Parameters

名称Name	类型Type	说明Description
`parentSessionKey`	String	父级会话键（类型 `String`）。The parent session key.

返回Returns List<String>

返回列出。Returns list.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:238–244

registerSession

public SpawnResult registerSession(String agentId, String label, String parentSessionKey, int parentSpawnDepth)

注册会话。

Registers the session.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.
`parentSessionKey`	String	父级会话键（类型 `String`）。The parent session key.
`parentSpawnDepth`	int	父级 Spawn Depth（类型 `int`）。The parent spawn depth.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:250–253

registerSession

public SpawnResult registerSession(String agentId, String label, String parentSessionKey, int parentSpawnDepth, String userId)

注册会话。

Registers a new subagent session, optionally inheriting the userId from its parent for continued namespace isolation.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.
`parentSessionKey`	String	父级会话键（类型 `String`）。The parent session key.
`parentSpawnDepth`	int	父级 Spawn Depth（类型 `int`）。The parent spawn depth.
`userId`	String	用户标识（类型 `String`）。The user id.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:259–353

registerMainSession

public SpawnResult registerMainSession(String agentId, String label)

注册主会话。

Registers the main session.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:359–361

registerMainSession

public SpawnResult registerMainSession(String agentId, String label, String gateKey)

注册主会话。

Registers the main session.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.
`gateKey`	String	gate 键（类型 `String`）。The gate key.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:363–365

registerMainSession

public SpawnResult registerMainSession(String agentId, String label, String gateKey, String userId)

注册主会话。

Registers a new MAIN session, optionally recording the gateKey for gateway routing persistence and userId for HarnessAgent namespace isolation.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.
`gateKey`	String	gate 键（类型 `String`）。The gate key.
`userId`	String	用户标识（类型 `String`）。The user id.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:371–405

viewSession

public Optional<SessionView> viewSession(String sessionKey)

设置该参数。

Performs the view session operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionKey`	String	会话键（类型 `String`）。The session key.

返回Returns Optional<SessionView>

返回可选。Returns optional.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:407–409

registerReviewerSession

public SpawnResult registerReviewerSession(String agentId, String label, String gateKey, String userId)

Registers a new REVIEWER session.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`label`	String	标签（类型 `String`）。The label.
`gateKey`	String	gate 键（类型 `String`）。The gate key.
`userId`	String	用户标识（类型 `String`）。The user id.

返回Returns SpawnResult

返回SpawnResult。Returns spawn result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:419–453

execute

public SendResult execute(String sessionKeyOrLabel, String prompt, long timeoutMs)

执行执行相关操作。

Performs the execute operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionKeyOrLabel`	String	会话键或标签（类型 `String`）。The session key or label.
`prompt`	String	提示词（类型 `String`）。The prompt.
`timeoutMs`	long	超时 Ms（类型 `long`）。The timeout ms.

返回Returns SendResult

返回SendResult。Returns send result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:459–461

execute

public SendResult execute(String sessionKeyOrLabel, String prompt, long timeoutMs, boolean announceToRequesterOnComplete, CommandLane lane)

执行执行相关操作。

Performs the execute operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionKeyOrLabel`	String	会话键或标签（类型 `String`）。The session key or label.
`prompt`	String	提示词（类型 `String`）。The prompt.
`timeoutMs`	long	超时 Ms（类型 `long`）。The timeout ms.
`announceToRequesterOnComplete`	boolean	announce 到 Requester On Complete（类型 `boolean`）。The announce to requester on complete.
`lane`	CommandLane	lane（类型 `CommandLane`）。The lane.

返回Returns SendResult

返回SendResult。Returns send result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:463–529

evictAgent

public void evictAgent(String sessionKey)

设置该参数。

Evicts the cached agent for the given session key.

参数Parameters

名称Name	类型Type	说明Description
`sessionKey`	String	会话键（类型 `String`）。The session key.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:596–600

runMaintenance

public int runMaintenance()

运行维护。

Runs session maintenance: prunes stale sessions and caps total entries.

返回Returns int

会话已移除的数量。number of sessions removed

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:612–649

removeSession

public void removeSession(String sessionKey)

移除会话。

Removes a session from all registries (in-memory, store, agent cache).

参数Parameters

名称Name	类型Type	说明Description
`sessionKey`	String	会话键（类型 `String`）。The session key.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:656–677

list

public List<SessionView> list(Set<String> kinds, int limit, int activeMinutes)

执行列表相关操作。

Performs the list operation.

参数Parameters

名称Name	类型Type	说明Description
`kinds`	Set<String>	kinds（类型 `Set`）。The kinds.
`limit`	int	数量上限（类型 `int`）。The limit.
`activeMinutes`	int	active 分钟（类型 `int`）。The active minutes.

返回Returns List<SessionView>

返回列出。Returns list.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:683–702

history

public HistoryResult history(String sessionKeyOrLabel, int limit)

执行历史相关操作。

Performs the history operation.

参数Parameters

名称Name	类型Type	说明Description
`sessionKeyOrLabel`	String	会话键或标签（类型 `String`）。The session key or label.
`limit`	int	数量上限（类型 `int`）。The limit.

返回Returns HistoryResult

返回HistoryResult。Returns history result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:704–728

drainPendingCompletions

public List<PendingCompletion> drainPendingCompletions(String requesterSessionKey, int limit)

执行 drainPendingCompletions 方法。

Performs the drain pending completions operation.

参数Parameters

名称Name	类型Type	说明Description
`requesterSessionKey`	String	requester 会话键（类型 `String`）。The requester session key.
`limit`	int	数量上限（类型 `int`）。The limit.

返回Returns List<PendingCompletion>

返回列出。Returns list.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:734–753

pendingCompletionCount

public int pendingCompletionCount(String requesterSessionKey)

设置待处理补全数量。

Performs the pending completion count operation.

参数Parameters

名称Name	类型Type	说明Description
`requesterSessionKey`	String	requester 会话键（类型 `String`）。The requester session key.

返回Returns int

返回数值结果。Returns a numeric result.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:755–766

resolveSessionFilePath

public String resolveSessionFilePath(String agentId, String sessionId)

解析会话文件路径。

Resolves the session file path for a given agent and session.

参数Parameters

名称Name	类型Type	说明Description
`agentId`	String	智能体标识（类型 `String`）。The agent id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/coding/session/SessionAgentManager.java:916–923

嵌套类详情Nested Class Detail

AnnounceDispatcher

@FunctionalInterface public interface AnnounceDispatcher

定义 Announce 调度器契约的接口。位于 io.agentscope.harness.coding.session 包。核心成员包括 dispatch。

Callback invoked when a subagent run completes and an announce payload is ready.

SpawnInterceptor

@FunctionalInterface public interface SpawnInterceptor

定义 Spawn 拦截器契约的接口。位于 io.agentscope.harness.coding.session 包。核心成员包括 onSpawn。

Callback invoked after a subagent session is spawned through this manager.