Introduce agentscope-harness module (#1353)

This pull request introduces a new `agentscope-harness` module built
with the `Harness Engineering` practices.

## Purpose
agentscope-harness builds on agentscope-core with a higher-level agent
runtime for production-style assistants: workspace-first workflows,
pluggable execution environments, and richer memory/session tooling.

## Entry point
HarnessAgent wraps ReActAgent with opinionated defaults: hooks, toolkit
wiring, and configuration for workspace, skills, subagents, and
persistence.

## Key design ideas

* Workspace-centric context — Loads and injects workspace material (e.g.
AGENTS.md, MEMORY.md, knowledge) into the agent’s unified system message
via hooks such as WorkspaceContextHook.
* Pluggable filesystem — Abstracts file operations behind a filesystem
layer (local, sandbox-backed, remote/composite) so tools and agents
share one API regardless of where files actually live.
* Sandbox & isolation — Optional sandbox execution with lifecycle
management, state stores, and options for distributed deployments when
session/sandbox state must be shared across replicas.
* Session & persistence — WorkspaceSession, session trees, and hooks
(e.g. session persistence, traces) tie long-running work to durable
session state where configured.
* Memory operations — Memory flush/consolidation, compaction, and
eviction policies help keep context bounded; dedicated tools (e.g.
memory search/get) support retrieval over workspace memory files.
* Subagents — Declarative subagent specs, spawn/send/list tooling, and
background tasks for delegated or async work (SubagentsHook, task
repository).
* Relationship to core. Harness does not replace ReActAgent; it composes
it with extra hooks, tools, and backends so applications can adopt
“harness” behavior incrementally while staying aligned with core APIs
(Model, Toolkit, Session, hooks).

This pull request also includes significant enhancements to the
`ReActAgent` class, focusing on improved runtime context handling,
per-call system message management, and better integration of
hook-supplied tools.

* Runtime Context and System Message Handling
* Hook and Toolkit Integration
* General Refactoring and Minor Improvements

---------

Co-authored-by: fang-tech <tianyufang978@gmail.com>
Co-authored-by: Copilot <copilot@github.com>

Author: 3 people

.gitignore

@@ -55,3 +55,9 @@ logs/
 **/boba-tea-shop/supervisor-agent/**/static/
 **/boba-tea-shop/**/node_modules/
 **/boba-tea-shop/**/dist/
+
+##agentscope
+.agentscope/
+
+## harness db
+**/*.db

.licenserc.yaml

@@ -17,6 +17,11 @@ header:
       limitations under the License.
 
   paths-ignore:
+    # Config / example files without license headers
+    - 'agentscope-examples/harness-example/.env.example'
+    - 'agentscope-examples/harness-example/src/main/resources/agentscope.json.example'
+    - 'agentscope-examples/harness-example/src/main/resources/log4j2.xml'
+    - 'agentscope-harness/src/main/resources/agentscope.json.example'
     - '**/*.versionsBackup'
     - '**/.idea/'
     - '**/*.iml'

agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java

@@ -15,6 +15,10 @@
  */
 package io.agentscope.core;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import io.agentscope.core.agent.Event;
+import io.agentscope.core.agent.RuntimeContext;
+import io.agentscope.core.agent.StreamOptions;
 import io.agentscope.core.agent.StructuredOutputCapableAgent;
 import io.agentscope.core.agent.accumulator.ReasoningContext;
 import io.agentscope.core.hook.ActingChunkEvent;
@@ -151,6 +155,17 @@ public class ReActAgent extends StructuredOutputCapableAgent {
     private final PlanNotebook planNotebook;
     private final ToolExecutionContext toolExecutionContext;
     private final StatePersistence statePersistence;
+    private RuntimeContext pendingRuntimeContext;
+
+    /**
+     * Per-call system message, propagated across PreCallEvent → PreReasoningEvent /
+     * PreSummaryEvent. It is safe to use an {@link java.util.concurrent.atomic.AtomicReference}
+     * here because {@code AgentBase.acquireExecution()} guarantees that only one {@code call()}
+     * runs concurrently per agent instance, so this reference is effectively owned by a single
+     * logical execution at any time.
+     */
+    private final java.util.concurrent.atomic.AtomicReference<Msg> currentSystemMsg =
+            new java.util.concurrent.atomic.AtomicReference<>();
 
     // ==================== Constructor ====================
 
@@ -178,6 +193,91 @@ private ReActAgent(Builder builder, Toolkit agentToolkit) {
                         : StatePersistence.all();
     }
 
+    // ==================== RuntimeContext ====================
+
+    @Override
+    protected void beforeAgentExecution(List<Msg> msgs) {
+        RuntimeContext ctx = this.pendingRuntimeContext;
+        this.pendingRuntimeContext = null;
+        if (ctx == null) {
+            ctx = RuntimeContext.empty();
+        }
+        bindRuntimeContextToHooks(ctx);
+        // Reset per-call system message; will be initialised by consumeSystemMsgAfterPreCall
+        currentSystemMsg.set(null);
+    }
+
+    @Override
+    protected Msg seedSystemMsg() {
+        if (sysPrompt != null && !sysPrompt.trim().isEmpty()) {
+            return Msg.builder()
+                    .name("system")
+                    .role(MsgRole.SYSTEM)
+                    .content(TextBlock.builder().text(sysPrompt).build())
+                    .build();
+        }
+        return null;
+    }
+
+    @Override
+    protected void consumeSystemMsgAfterPreCall(Msg systemMsg) {
+        currentSystemMsg.set(systemMsg);
+    }
+
+    @Override
+    protected void afterAgentExecution() {
+        unbindRuntimeContextFromHooks();
+    }
+
+    private ToolExecutionContext buildMergedToolContext() {
+        RuntimeContext run = getRuntimeContext();
+        if (run == null) {
+            return toolExecutionContext != null
+                    ? toolExecutionContext
+                    : ToolExecutionContext.empty();
+        }
+        return ToolExecutionContext.merge(run.asToolExecutionContext(), toolExecutionContext);
+    }
+
+    /**
+     * Calls the agent with a per-call {@link RuntimeContext} (metadata for hooks and tools, not
+     * persisted).
+     */
+    public Mono<Msg> call(List<Msg> msgs, RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return call(msgs);
+    }
+
+    public Mono<Msg> call(List<Msg> msgs, Class<?> structuredOutputClass, RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return call(msgs, structuredOutputClass);
+    }
+
+    public Mono<Msg> call(List<Msg> msgs, JsonNode outputSchema, RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return call(msgs, outputSchema);
+    }
+
+    public Flux<Event> stream(List<Msg> msgs, StreamOptions options, RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return stream(msgs, options);
+    }
+
+    public Flux<Event> stream(
+            List<Msg> msgs,
+            StreamOptions options,
+            Class<?> structuredModel,
+            RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return stream(msgs, options, structuredModel);
+    }
+
+    public Flux<Event> stream(
+            List<Msg> msgs, StreamOptions options, JsonNode schema, RuntimeContext context) {
+        this.pendingRuntimeContext = context;
+        return stream(msgs, options, schema);
+    }
+
     // ==================== New StateModule API ====================
 
     /**
@@ -466,17 +566,17 @@ private Mono<Msg> reasoning(int iter, boolean ignoreMaxIters) {
         ReasoningContext context = new ReasoningContext(getName());
 
         return checkInterruptedAsync()
-                .then(notifyPreReasoningEvent(prepareMessages()))
+                .then(notifyPreReasoningEvent(memory.getMessages()))
                 .flatMapMany(
                         event -> {
                             GenerateOptions options =
                                     event.getEffectiveGenerateOptions() != null
                                             ? event.getEffectiveGenerateOptions()
                                             : buildGenerateOptions();
-                            return model.stream(
-                                            event.getInputMessages(),
-                                            toolkit.getToolSchemas(),
-                                            options)
+                            List<Msg> modelInput =
+                                    prependSystemMsg(
+                                            event.getInputMessages(), event.getSystemMessage());
+                            return model.stream(modelInput, toolkit.getToolSchemas(), options)
                                     .concatMap(chunk -> checkInterruptedAsync().thenReturn(chunk));
                         })
                 .doOnNext(
@@ -665,7 +765,7 @@ private Msg buildSuspendedMsg(List<Map.Entry<ToolUseBlock, ToolResultBlock>> pen
      */
     private Mono<List<Map.Entry<ToolUseBlock, ToolResultBlock>>> executeToolCalls(
             List<ToolUseBlock> toolCalls) {
-        return toolkit.callTools(toolCalls, toolExecutionConfig, this, toolExecutionContext)
+        return toolkit.callTools(toolCalls, toolExecutionConfig, this, buildMergedToolContext())
                 .map(
                         results ->
                                 IntStream.range(0, toolCalls.size())
@@ -734,7 +834,10 @@ protected Mono<Msg> summarizing() {
         return notifyPreSummaryHook(messageList, generateOptions)
                 .flatMap(
                         preSummaryEvent -> {
-                            List<Msg> effectiveMessages = preSummaryEvent.getInputMessages();
+                            List<Msg> effectiveMessages =
+                                    prependSystemMsg(
+                                            preSummaryEvent.getInputMessages(),
+                                            preSummaryEvent.getSystemMessage());
                             GenerateOptions effectiveOptions =
                                     preSummaryEvent.getEffectiveGenerateOptions();
 
@@ -775,7 +878,7 @@ private Mono<Msg> streamAndAccumulateSummary(
     }
 
     private List<Msg> prepareSummaryMessages() {
-        List<Msg> messageList = prepareMessages();
+        List<Msg> messageList = new ArrayList<>(memory.getMessages());
         messageList.add(
                 Msg.builder()
                         .name("user")
@@ -816,20 +919,21 @@ private Mono<Msg> handleSummaryError(Throwable error) {
     // ==================== Helper Methods ====================
 
     /**
-     * Prepare messages for model input.
+     * Prepends the system message to {@code msgs} if non-null.
+     *
+     * <p>Called immediately before each {@code model.stream()} invocation to build the final
+     * LLM input without contaminating the in-memory message list.
      */
-    private List<Msg> prepareMessages() {
-        List<Msg> messages = new ArrayList<>();
-        if (sysPrompt != null && !sysPrompt.trim().isEmpty()) {
-            messages.add(
-                    Msg.builder()
-                            .name("system")
-                            .role(MsgRole.SYSTEM)
-                            .content(TextBlock.builder().text(sysPrompt).build())
-                            .build());
+    private static List<Msg> prependSystemMsg(List<Msg> msgs, Msg systemMsg) {
+        if (systemMsg == null) {
+            return msgs != null ? msgs : List.of();
         }
-        messages.addAll(memory.getMessages());
-        return messages;
+        List<Msg> result = new ArrayList<>();
+        result.add(systemMsg);
+        if (msgs != null) {
+            result.addAll(msgs);
+        }
+        return result;
     }
 
     /**
@@ -911,7 +1015,9 @@ private <T extends HookEvent> Mono<T> notifyHooks(T event) {
     }
 
     private Mono<PreReasoningEvent> notifyPreReasoningEvent(List<Msg> msgs) {
-        return notifyHooks(new PreReasoningEvent(this, model.getModelName(), null, msgs));
+        PreReasoningEvent event = new PreReasoningEvent(this, model.getModelName(), null, msgs);
+        event.setSystemMessage(currentSystemMsg.get());
+        return notifyHooks(event);
     }
 
     private Mono<PostReasoningEvent> notifyPostReasoning(Msg msg) {
@@ -981,9 +1087,11 @@ private Mono<Void> notifyReasoningChunk(Msg chunkMsg, ReasoningContext context)
 
     private Mono<PreSummaryEvent> notifyPreSummaryHook(
             List<Msg> msgs, GenerateOptions generateOptions) {
-        return notifyHooks(
+        PreSummaryEvent event =
                 new PreSummaryEvent(
-                        this, model.getModelName(), generateOptions, msgs, maxIters, maxIters));
+                        this, model.getModelName(), generateOptions, msgs, maxIters, maxIters);
+        event.setSystemMessage(currentSystemMsg.get());
+        return notifyHooks(event);
     }
 
     private Mono<PostSummaryEvent> notifyPostSummaryHook(Msg msg, GenerateOptions generateOptions) {
@@ -1219,6 +1327,7 @@ public Builder maxIters(int maxIters) {
          * @param hook The hook to add, must not be null
          * @return This builder instance for method chaining
          * @see Hook
+         * @see Hook#tools()
          */
         public Builder hook(Hook hook) {
             this.hooks.add(hook);
@@ -1234,6 +1343,7 @@ public Builder hook(Hook hook) {
          * @param hooks The list of hooks to add, must not be null
          * @return This builder instance for method chaining
          * @see Hook
+         * @see Hook#tools()
          */
         public Builder hooks(List<Hook> hooks) {
             this.hooks.addAll(hooks);
@@ -1374,7 +1484,8 @@ public Builder planNotebook(PlanNotebook planNotebook) {
          * <p>The skill box is used to manage the skills for this agent. It will be used to register the skills to the toolkit.
          * <ul>
          *   <li>Skill loader tools will be automatically registered to the toolkit</li>
-         *   <li>A skill hook will be added to inject skill prompts and manage skill activation</li>
+         *   <li>A skill hook will be added to inject skill prompts on {@link io.agentscope.core.hook.PreCallEvent}
+         *       and manage skill activation</li>
          * </ul>
          * @param skillBox The skill box to use for this agent
          * @return This builder instance for method chaining
@@ -1562,6 +1673,8 @@ public ReActAgent build() {
             // Deep copy toolkit to avoid state interference between agents
             Toolkit agentToolkit = this.toolkit.copy();
 
+            registerToolsFromHooks(agentToolkit);
+
             if (enableMetaTool) {
                 agentToolkit.registerMetaTool();
             }
@@ -1594,6 +1707,26 @@ public ReActAgent build() {
             return new ReActAgent(this, agentToolkit);
         }
 
+        /**
+         * Registers tool objects declared by hooks ({@link Hook#tools()}) on the agent toolkit.
+         *
+         * <p>Runs after {@link Toolkit#copy()} so hook-supplied tools are scoped to this agent
+         * instance without modifying the builder's original toolkit.
+         */
+        private void registerToolsFromHooks(Toolkit agentToolkit) {
+            for (Hook hook : hooks) {
+                List<Object> toolObjects = hook.tools();
+                if (toolObjects == null || toolObjects.isEmpty()) {
+                    continue;
+                }
+                for (Object toolObject : toolObjects) {
+                    if (toolObject != null) {
+                        agentToolkit.registerTool(toolObject);
+                    }
+                }
+            }
+        }
+
         /**
          * Configures long-term memory based on the selected mode.
          *
@@ -1748,7 +1881,9 @@ public <T extends HookEvent> Mono<T> onEvent(T event) {
          * <p>This method automatically:
          * <ul>
          *   <li>Registers skill load tool to the toolkit
-         *   <li>Adds the skill hook to inject skill prompts and manage skill activation
+         *   <li>Adds the skill hook to inject skill prompts on {@link io.agentscope.core.hook.PreCallEvent}
+         *       (priority {@link io.agentscope.core.skill.SkillHook#SKILL_HOOK_PRIORITY}) and manage skill
+         *       activation
          *   <li>Uploads skill files to the upload directory if auto upload is enabled
          * </ul>
          */