feat(plan): add changeHook management API to PlanNotebook & add HITL support for plan execution

[LearningGp]

AgentScope-Java Version

1.0.9

Description

feat(plan-notebook): add Human-in-the-Loop (HITL) support for plan execution
feat(plan): add changeHook management API to PlanNotebook

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

[gemini-code-assist]

Summary of Changes

Hello @LearningGp, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the AgentScope-Java framework by integrating Human-in-the-Loop (HITL) capabilities into the plan execution process. It provides users with the ability to intervene, inspect, and guide the agent's plan, making the system more interactive and controllable. The changes involve core PlanNotebook modifications, new service-level logic for managing agent state, and corresponding UI updates to support these interactions.

Highlights

• Human-in-the-Loop (HITL) Support: Introduced functionality to pause agent execution, allowing users to review and modify the plan before resuming. This enhances user control over autonomous agent processes.
• PlanNotebook Change Hook API: Added new addChangeHook and removeChangeHook methods to the PlanNotebook class, enabling external components to register and unregister callbacks that are triggered whenever the plan changes.
• New API Endpoints for Agent Control: Implemented several new REST API endpoints (/resume, /paused, /stop, /stop-requested) in the ChatController to programmatically manage the agent's execution state, facilitating the HITL workflow.
• Dynamic UI for Agent State: Updated the frontend (index.html) with new control buttons (Stop, Continue) and a paused indicator. The UI dynamically reflects the agent's execution state and allows users to interact with the new HITL features.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces Human-in-the-Loop (HITL) support for plan execution and adds a changeHook management API to PlanNotebook. The changes are well-structured, with a clean new core API and a comprehensive example implementation on both the backend and frontend. The HITL feature is a valuable addition. My review focuses on improving the robustness of the implementation by addressing a few potential race conditions in both the Java service and the frontend JavaScript that could arise from concurrent user actions.

[Copilot]

Pull request overview

This PR adds Human-in-the-Loop (HITL) pause/resume support to the PlanNotebook web example and exposes a change-hook management API on PlanNotebook to integrate plan state changes with external systems. It wires the new HITL flow through the backend agent service, REST endpoints, and the frontend UI, and introduces public addChangeHook/removeChangeHook methods on PlanNotebook.

Changes:

• Frontend: extend the PlanNotebook UI with a Stop/Continue control button, paused indicator, and a shared SSE response handler that reacts to a [PAUSED] marker from the backend.
• Backend example: update AgentService and ChatController in the plan-notebook example to support pause/resume via streaming events, track paused/stop-requested state, and expose new HITL-related endpoints.
• Core library: add public addChangeHook(String, BiConsumer<PlanNotebook, Plan>) and removeChangeHook(String) APIs to PlanNotebook to manage plan change hooks externally.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
agentscope-examples/plan-notebook/src/main/resources/static/index.html	Adds HITL UI elements (Stop/Continue control button, paused indicator), centralizes SSE stream parsing (including a [PAUSED] sentinel), and adjusts chat/plan controls to reflect agent pause/stop state.
agentscope-examples/plan-notebook/src/main/java/io/agentscope/examples/plannotebook/service/AgentService.java	Configures a plan change hook on PlanNotebook, introduces atomic pause/stop flags, maps streaming Events (including AGENT_RESULT with ACTING_STOP_REQUESTED) to SSE text, and adds resume, isPaused, requestStop, and isStopRequested methods with state reset logic.
agentscope-examples/plan-notebook/src/main/java/io/agentscope/examples/plannotebook/controller/ChatController.java	Extends the chat API with /resume, /paused, /stop, and /stop-requested endpoints to drive the HITL pause/resume flow and expose pause/stop state to the frontend.
agentscope-core/src/main/java/io/agentscope/core/plan/PlanNotebook.java	Introduces public addChangeHook/removeChangeHook methods backed by the existing changeHooks map and triggerPlanChangeHooks() pipeline, enabling external consumers to react to plan mutations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!