fix(core): promote interrupt(RuntimeContext) to Agent interface to fix slot-mismatch silent failure

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

@@ -711,6 +711,7 @@ public void interrupt(InterruptSource source) {
      *
      * @param ctx the runtime context identifying the session to interrupt
      */
+    @Override
     public void interrupt(RuntimeContext ctx) {
         interrupt(ctx, null);
     }
@@ -722,6 +723,7 @@ public void interrupt(RuntimeContext ctx) {
      * @param ctx the runtime context identifying the session to interrupt
      * @param msg optional user message to attach to the interrupt signal
      */
+    @Override
     public void interrupt(RuntimeContext ctx, Msg msg) {
         String uid = ctx != null ? ctx.getUserId() : null;
         String sid = ctx != null ? ctx.getSessionId() : null;

agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java

@@ -71,21 +71,61 @@ default String getDescription() {
 
     /**
      * Interrupt the current agent execution.
-     * This method sets an interrupt flag that will be checked by the agent at appropriate
-     * checkpoints during execution. The interruption is cooperative and may not take effect
-     * immediately.
+     *
+     * @deprecated since 2.0.0, use {@link #interrupt(RuntimeContext)} with explicit runtime
+     *     context to ensure the interruption targets the correct session slot.
      */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     void interrupt();
 
     /**
      * Interrupt the current agent execution with a user message.
-     * This method sets an interrupt flag and associates a user message with the interruption.
-     * The interruption is cooperative and may not take effect immediately.
      *
-     * @param msg User message associated with the interruption
+     * @deprecated since 2.0.0, use {@link #interrupt(RuntimeContext, Msg)} with explicit runtime
+     *     context to ensure the interruption targets the correct session slot.
      */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     void interrupt(Msg msg);
 
+    /**
+     * Interrupt the agent execution for the session identified by the given {@link RuntimeContext}.
+     * This is the session-aware variant of {@link #interrupt()} that targets a specific
+     * {@code (userId, sessionId)} session instead of a hardcoded default session.
+     *
+     * <p>When called from a middleware or tool that holds both {@code Agent agent} and
+     * {@code RuntimeContext ctx}, this method ensures the interruption targets the current
+     * in-flight call's session rather than a different session.
+     *
+     * <p>Default implementation delegates to {@link #interrupt()} for backward compatibility.
+     * Subclasses that maintain per-session state (e.g., {@link io.agentscope.core.ReActAgent})
+     * should override this to trigger the interrupt signal on the correct session slot.
+     *
+     * @param ctx the runtime context identifying the session to interrupt; if {@code null} or
+     *            {@code ctx.getSessionId()} is {@code null}/{@code blank}, implementations may
+     *            fall back to a default session
+     */
+    default void interrupt(RuntimeContext ctx) {
+        interrupt();
+    }
+
+    /**
+     * Interrupt the agent execution for the session identified by the given {@link RuntimeContext}
+     * with an associated user message.
+     *
+     * <p>This is the session-aware variant of {@link #interrupt(Msg)} that targets a specific
+     * {@code (userId, sessionId)} session instead of a hardcoded default session.
+     *
+     * <p>Default implementation delegates to {@link #interrupt(Msg)} for backward compatibility.
+     * Subclasses that maintain per-session state (e.g., {@link io.agentscope.core.ReActAgent})
+     * should override this to trigger the interrupt signal on the correct session slot.
+     *
+     * @param ctx the runtime context identifying the session to interrupt
+     * @param msg optional user message to associate with the interruption
+     */
+    default void interrupt(RuntimeContext ctx, Msg msg) {
+        interrupt(msg);
+    }
+
     /**
      * Returns the agent's runtime {@link io.agentscope.core.state.AgentState}, or {@code null} if
      * this agent type does not maintain one.

agentscope-core/src/main/java/io/agentscope/core/agent/AgentBase.java

@@ -440,28 +440,44 @@ public static void removeSystemHook(Hook hook) {
         systemHooks.remove(hook);
     }
 
-    /** @deprecated Subclasses should implement per-session interrupt via RuntimeContext. */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0, use {@link #interrupt(RuntimeContext)} with explicit runtime context
+     *     to ensure the interruption targets the correct session slot.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @Override
     public void interrupt() {}
 
-    /** @deprecated Subclasses should implement per-session interrupt via RuntimeContext. */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0, use {@link #interrupt(RuntimeContext, Msg)} with explicit runtime
+     *     context to ensure the interruption targets the correct session slot.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @Override
     public void interrupt(Msg msg) {}
 
-    /** @deprecated Subclasses should implement per-session interrupt via RuntimeContext. */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0, use {@link #interrupt(RuntimeContext)} with explicit runtime
+     *     context to ensure the interruption targets the correct session slot.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public void interrupt(InterruptSource source) {}
 
-    /** @deprecated No longer needed; ReActAgent uses per-session InterruptControl. */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0; no longer needed. ReActAgent uses per-session
+     *     {@link io.agentscope.core.interruption.InterruptControl} on its per-call
+     *     {@link io.agentscope.core.state.AgentState}.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     protected Mono<Void> checkInterruptedAsync() {
         return Mono.empty();
     }
 
-    /** @deprecated No-op; per-session interrupt state is managed by AgentState.interruptControl(). */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0; no-op. Per-session interrupt state is managed by
+     *     {@link io.agentscope.core.interruption.InterruptControl}.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     protected void resetInterruptFlag() {}
 
     private InterruptContext createInterruptContext() {
@@ -502,14 +518,21 @@ private Function<Throwable, Mono<Msg>> createErrorHandler(Msg... originalArgs) {
         };
     }
 
-    /** @deprecated No-op stub. */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0; returns a detached flag that is never read. Use
+     *     {@link io.agentscope.core.interruption.InterruptControl#isInterrupted()} on the
+     *     session's {@link io.agentscope.core.state.AgentState} instead.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     protected AtomicBoolean getInterruptFlag() {
         return new AtomicBoolean(false);
     }
 
-    /** @deprecated Returns USER. Per-session interrupt source is on AgentState.interruptControl(). */
-    @Deprecated
+    /**
+     * @deprecated since 2.0.0; always returns {@link InterruptSource#USER}. Per-session
+     *     interrupt source is on {@link io.agentscope.core.interruption.InterruptControl}.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     protected InterruptSource getInterruptSource() {
         return InterruptSource.USER;
     }

agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java

@@ -488,6 +488,16 @@ public void interrupt(Msg msg) {
         delegate.interrupt(msg);
     }
 
+    @Override
+    public void interrupt(RuntimeContext ctx) {
+        delegate.interrupt(ctx);
+    }
+
+    @Override
+    public void interrupt(RuntimeContext ctx, Msg msg) {
+        delegate.interrupt(ctx, msg);
+    }
+
     // -----------------------------------------------------------------
     //  Channel / Gateway
     // -----------------------------------------------------------------