fix(builder): fall back to LocalFilesystemSpec when no distributed AgentStateStore is configured by chang6666 · Pull Request #1841 · agentscope-ai/agentscope-java

chang6666 · 2026-06-19T07:04:38Z

BuilderConfig unconditionally wired every agent with RemoteFilesystemSpec but fell back to InMemoryAgentStateStore when no distributed AgentStateStore bean was present. HarnessAgent rejects this combination, so the app could never start on a fresh checkout with the default H2 datasource.

Now when the effective AgentStateStore is local (InMemory/JsonFile), LocalFilesystemSpec is used instead, producing a consistent local-mode topology. Distributed deployments are unaffected — RemoteFilesystemSpec is still used when a distributed AgentStateStore (Redis/MySQL/etc.) is present.

Related Issue

Fixes #1840

AgentScope-Java Version

2.0.0-SNAPSHOT

Description

Background

BuilderConfig configures the filesystem spec for every agent during startup. The previous implementation unconditionally used RemoteFilesystemSpec, and fell back to InMemoryAgentStateStore when no distributed AgentStateStore bean was injected. However, HarnessAgent validates the store-vs-filesystem topology at build time — RemoteFilesystemSpec requires a distributed store that can be shared across pods, while InMemoryAgentStateStore is in-process and not shareable.

Problem

On a fresh checkout with the default H2 datasource (i.e. no Redis/MySQL distributed AgentStateStore bean injected), the harness throws IllegalStateException due to the topology mismatch, so BuilderApp cannot start at all. This is an out-of-the-box usability bug.

Changes Made

File: agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/config/BuilderConfig.java (+38 / -12)

Added imports: io.agentscope.core.state.JsonFileAgentStateStore and io.agentscope.harness.agent.filesystem.spec.LocalFilesystemSpec.
Added helper method isLocalStateStore(AgentStateStore): returns true when the store is InMemoryAgentStateStore or JsonFileAgentStateStore.
Refactored the filesystem wiring in configureAllAgents:
- When the effective store is local, use LocalFilesystemSpec with IsolationScope.USER (no shared prefix, since there is no cross-pod sharing in local mode).
- When the effective store is distributed, keep the original behavior using RemoteFilesystemSpec(baseStore) with the activity/ shared prefix.
Added INFO logs recording which filesystem spec is in effect, to aid deployment troubleshooting.
Refined the existing WARN message: "DistributedStore" → "distributed AgentStateStore bean" for accuracy.

How to Test

Local mode (default H2) — verify the fix:

cd agentscope-examples/agents/agentscope-builder
mvn spring-boot:run

Expected: the app starts normally; logs show Effective AgentStateStore is local (InMemoryAgentStateStore); using LocalFilesystemSpec.; no IllegalStateException. Open the builder UI, create an agent, and start a conversation to verify filesystem writes succeed.

Distributed mode (Redis) — verify no regression:

Inject a distributed AgentStateStore bean (e.g. from agentscope-extensions-redis) and start:

mvn spring-boot:run -Dspring-boot.run.profiles=redis

Expected: logs show Effective AgentStateStore is distributed (...); using RemoteFilesystemSpec.; behavior is unchanged from before the fix; activity/ still goes to the shared BaseStore.

Regression tests:

mvn -pl agentscope-examples/agents/agentscope-builder test

Checklist

Please check the following items before code is ready to be reviewed.

Code has been formatted with mvn spotless:apply
All tests are passing (mvn test)
Javadoc comments are complete and follow project conventions
Related documentation has been updated (e.g. links, examples, etc.)
Code is ready for review

…entStateStore is configured BuilderConfig unconditionally wired every agent with RemoteFilesystemSpec but fell back to InMemoryAgentStateStore when no distributed AgentStateStore bean was present. HarnessAgent rejects this combination, so the app could never start on a fresh checkout with the default H2 datasource. Now when the effective AgentStateStore is local (InMemory/JsonFile), LocalFilesystemSpec is used instead, producing a consistent local-mode topology. Distributed deployments are unaffected — RemoteFilesystemSpec is still used when a distributed AgentStateStore (Redis/MySQL/etc.) is present.

chang6666 · 2026-06-19T07:06:47Z

fix issue #1840

…entStateStore is configured BuilderConfig unconditionally wired every agent with RemoteFilesystemSpec but fell back to InMemoryAgentStateStore when no distributed AgentStateStore bean was present. HarnessAgent rejects this combination, so the app could never start on a fresh checkout with the default H2 datasource. Now when the effective AgentStateStore is local (InMemory/JsonFile), LocalFilesystemSpec is used instead, producing a consistent local-mode topology. Distributed deployments are unaffected — RemoteFilesystemSpec is still used when a distributed AgentStateStore (Redis/MySQL/etc.) is present.

# Conflicts: # agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/config/BuilderConfig.java

AgentScopeJavaBot

🤖 AI Review

This PR fixes a genuine out-of-the-box startup failure where BuilderConfig unconditionally wired RemoteFilesystemSpec but fell back to InMemoryAgentStateStore when no distributed store was available — a combination HarnessAgent correctly rejects. The fix is clean and well-scoped: a new isLocalStateStore() helper detects local stores and switches to LocalFilesystemSpec, producing a consistent local-mode topology. The existing test (BuilderAppContextLoadTest) remains unaffected because its Mockito proxy is typed as AgentStateStore (not InMemoryAgentStateStore), so it still takes the RemoteFilesystemSpec path. One recommended improvement: the whitelist-based instanceof check is fragile — any future local AgentStateStore implementation will silently fall into the distributed branch and reproduce the original bug.

AgentScopeJavaBot · 2026-06-19T09:51:04Z

+     * {@link RemoteFilesystemSpec}.
+     */
+    private static boolean isLocalStateStore(AgentStateStore store) {
+        return store instanceof InMemoryAgentStateStore || store instanceof JsonFileAgentStateStore;


[major] The whitelist-based detection (instanceof InMemoryAgentStateStore || instanceof JsonFileAgentStateStore) is fragile: if a new local AgentStateStore implementation is added (e.g. an embedded SQLite store), it will silently fall into the distributed branch and reproduce the exact topology-mismatch bug this PR fixes.

Consider either:

Adding a marker interface or method on AgentStateStore itself, e.g. default boolean isDistributed() { return true; }, overridden to false by local implementations; or

Inverting to a blacklist of known distributed stores:

private static boolean isLocalStateStore(AgentStateStore store) { return !(store instanceof MysqlAgentStateStore || store instanceof RedisAgentStateStore || store instanceof JedisAgentStateStore || store instanceof RedissonAgentStateStore || store instanceof OssAgentStateStore); }

Option 1 is more robust and pushes the classification to where it belongs (the store contract). Option 2 is a quick improvement if changing the interface is out of scope for this PR.

AgentScopeJavaBot · 2026-06-19T09:51:04Z

-                                    .addSharedPrefix("activity/"));
+                    if (localStore) {
+                        b.filesystem(new LocalFilesystemSpec().isolationScope(IsolationScope.USER));
+                    } else {


[nit] In local mode, LocalFilesystemSpec defaults to LocalFsMode.ROOTED with project resolving to System.getProperty("user.dir"). For the builder context, consider explicitly setting .project(cwd) so the agent's shell pwd matches the builder's configured workspace root rather than the JVM working directory:

b.filesystem(new LocalFilesystemSpec() .project(cwd) .isolationScope(IsolationScope.USER));

This is non-blocking — the default works, but explicit is clearer.

AgentScopeJavaBot

🤖 AI Review

This PR fixes a genuine out-of-the-box startup failure where BuilderConfig unconditionally wired RemoteFilesystemSpec but fell back to InMemoryAgentStateStore when no distributed store was available — a combination HarnessAgent correctly rejects. The fix is clean and well-scoped: a new isLocalStateStore() helper detects local stores and switches to LocalFilesystemSpec, producing a consistent local-mode topology. The existing test (BuilderAppContextLoadTest) remains unaffected because its Mockito proxy is typed as AgentStateStore (not InMemoryAgentStateStore), so it still takes the RemoteFilesystemSpec path. One recommended improvement: the whitelist-based instanceof check is fragile — any future local AgentStateStore implementation will silently fall into the distributed branch and reproduce the original bug.

AgentScopeJavaBot · 2026-06-19T09:52:04Z

+     * {@link RemoteFilesystemSpec}.
+     */
+    private static boolean isLocalStateStore(AgentStateStore store) {
+        return store instanceof InMemoryAgentStateStore || store instanceof JsonFileAgentStateStore;


[major] The whitelist-based detection (instanceof InMemoryAgentStateStore || instanceof JsonFileAgentStateStore) is fragile: if a new local AgentStateStore implementation is added (e.g. an embedded SQLite store), it will silently fall into the distributed branch and reproduce the exact topology-mismatch bug this PR fixes.

Consider either:

Adding a marker interface or method on AgentStateStore itself, e.g. default boolean isDistributed() { return true; }, overridden to false by local implementations; or

Inverting to a blacklist of known distributed stores:

private static boolean isLocalStateStore(AgentStateStore store) { return !(store instanceof MysqlAgentStateStore || store instanceof RedisAgentStateStore || store instanceof JedisAgentStateStore || store instanceof RedissonAgentStateStore || store instanceof OssAgentStateStore); }

Option 1 is more robust and pushes the classification to where it belongs (the store contract). Option 2 is a quick improvement if changing the interface is out of scope for this PR.

AgentScopeJavaBot · 2026-06-19T09:52:04Z

-                                    .addSharedPrefix("activity/"));
+                    if (localStore) {
+                        b.filesystem(new LocalFilesystemSpec().isolationScope(IsolationScope.USER));
+                    } else {


[nit] In local mode, LocalFilesystemSpec defaults to LocalFsMode.ROOTED with project resolving to System.getProperty("user.dir"). For the builder context, consider explicitly setting .project(cwd) so the agent's shell pwd matches the builder's configured workspace root rather than the JVM working directory:

b.filesystem(new LocalFilesystemSpec() .project(cwd) .isolationScope(IsolationScope.USER));

This is non-blocking — the default works, but explicit is clearer.

codecov · 2026-06-19T10:09:26Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

chang6666 requested a review from a team June 19, 2026 07:04

chang6666 added 3 commits June 19, 2026 15:18

Merge remote-tracking branch 'origin/main'

9be3a59

# Conflicts: # agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/config/BuilderConfig.java

style: 格式化代码换行

e7690f1

AgentScopeJavaBot added bug Something isn't working area/examples agentscope-examples labels Jun 19, 2026

AgentScopeJavaBot reviewed Jun 19, 2026

View reviewed changes

fix: close HarnessAgent in test to prevent JUnit extension context leak

c2086ad

Merge branch 'main' of https://github.com/agentscope-ai/agentscope-java

e3a5241

chickenlj approved these changes Jun 25, 2026

View reviewed changes

Merge branch 'main' into main

315230c

chickenlj merged commit b27ca24 into agentscope-ai:main Jun 25, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(builder): fall back to LocalFilesystemSpec when no distributed AgentStateStore is configured#1841

fix(builder): fall back to LocalFilesystemSpec when no distributed AgentStateStore is configured#1841
chickenlj merged 7 commits into
agentscope-ai:mainfrom
chang6666:main

chang6666 commented Jun 19, 2026 •

edited

Loading

Uh oh!

chang6666 commented Jun 19, 2026 •

edited

Loading

Uh oh!

AgentScopeJavaBot left a comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Uh oh!

AgentScopeJavaBot left a comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Uh oh!

codecov Bot commented Jun 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

chang6666 commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

AgentScope-Java Version

Description

Background

Problem

Changes Made

How to Test

Checklist

Uh oh!

chang6666 commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AgentScopeJavaBot left a comment

Choose a reason for hiding this comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

AgentScopeJavaBot left a comment

Choose a reason for hiding this comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

AgentScopeJavaBot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Jun 19, 2026

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chang6666 commented Jun 19, 2026 •

edited

Loading

chang6666 commented Jun 19, 2026 •

edited

Loading