Skip to content

Build and run agents you can see, understand and trust.

feat(agent): add steering support to the SDK and WebUI (#3638)

qbc9a2d631fc7fa
diff --git a/examples/web_ui/frontend/src/api/chat.ts b/examples/web_ui/frontend/src/api/chat.ts
index 7fae0c264..128689ac9 100644
--- a/examples/web_ui/frontend/src/api/chat.ts
+++ b/examples/web_ui/frontend/src/api/chat.ts
@@ -10,6 +10,10 @@ export interface ChatQueueItem {
created_at: string;
/** One message or an ordered message group executed as one turn. */
input: Msg | Msg[];
+ /** Current deferred-send or steering lifecycle state. */
+ state: 'queued' | 'steering' | 'failed';
+ /** Visible preparation failure for a failed steering attempt. */
+ error: string | null;
}
export interface ChatQueueResponse {
@@ -87,6 +91,22 @@ export const chatApi = {
session_id: sessionId,
}),
+ /**
+ * Reserve one pending item for the reply that is currently active.
+ *
+ * @param itemId - Stable id of the pending item.
+ * @param agentId - Agent that owns the target session.
+ * @param sessionId - Session whose reply should be steered.
+ * @param replyId - Active reply observed by the client.
+ * @returns Complete queue snapshot with the item marked as steering.
+ */
+ steerQueued: (itemId: string, agentId: string, sessionId: string, replyId: string) =>
+ client.post<ChatQueueResponse>(`/chat/queue/${encodeURIComponent(itemId)}/steer`, {
+ agent_id: agentId,
+ session_id: sessionId,
+ reply_id: replyId,
+ }),
+
/**
* Apply an exact permutation of the current pending queue.
*
diff --git a/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx b/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx
index a0cb43b20..aa6d1760b 100644
--- a/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx
+++ b/examples/web_ui/frontend/src/components/chat/ASMessageBubble.tsx
@@ -2,6 +2,7 @@ import { ReplyFinishedReason } from '@agentscope-ai/agentscope/event';
import type {
ContentBlock,
DataBlock,
+ HintBlock,
Msg,
TextBlock,
ThinkingBlock,
@@ -15,6 +16,7 @@ import {
CheckCircle,
ChevronRight,
CirclePlay,
+ CornerDownRight,
Copy,
FileText,
FileVideo2,
@@ -67,6 +69,60 @@ interface ToolCallGroupBlock {
type ExtendedContentBlock = ContentBlock | ToolCallGroupBlock;
+const STEERING_HINT_SOURCE = 'chat_input_steering';
+
+const isSteeringHint = (block: ExtendedContentBlock): block is HintBlock =>
+ block.type === 'hint' && block.source === STEERING_HINT_SOURCE;
+
+const getHintItems = (block: HintBlock): (TextBlock | DataBlock)[] =>
+ typeof block.hint === 'string'
+ ? [
+ {
+ type: 'text',
+ id: `${block.id}-text`,
+ text: block.hint,
+ created_at: block.created_at,
+ },
+ ]
+ : block.hint;
+
+interface SteeringMessageBubbleProps {
+ blocks: ContentBlock[];
+ status: 'steering' | 'steered';
+}
+
+/** User-facing projection of a prompt steering the active reply. */
+export function SteeringMessageBubble({ blocks, status }: SteeringMessageBubbleProps) {
+ const { t } = useTranslation();
+ return (
+ <div className="flex w-full flex-col items-end gap-1">
+ <Bubble align="end" variant="muted">
+ <BubbleContent className="flex flex-col gap-2">
+ {blocks.map((block) => (
+ <ASBlock block={block} key={block.id} />
+ ))}
+ </BubbleContent>
+ </Bubble>
+ <div
+ className="flex items-center gap-1 px-1 text-xs text-muted-foreground"
+ role="status"
+ aria-live="polite"
+ >
+ {status === 'steering' ? (
+ <Loader2 className="size-3 animate-spin" aria-hidden="true" />
+ ) : (
+ <CornerDownRight className="size-3" aria-hidden="true" />
+ )}
+ <span>
+ {status === 'steering'
+ ? t('chatQueue.stateSteering')
+ : t('chatQueue.stateSteered')}
+ </span>
+ </div>
+ </div>
+ );
+}
+
/**
* Pair every tool_call with its tool_result (by id) and collect *consecutive*
* tool calls into a single `tool_call_group`, regardless of tool name — so a
@@ -459,13 +515,21 @@ function ASMessageBubbleComponent({ message }: MessageBubbleProps) {
<MessageContent>
{blocks
.filter((block) => block.type !== 'data')
- .map((block, index) => (
- <Bubble key={index} variant={isUser ? 'muted' : 'ghost'}>
- <BubbleContent>
- <ASBlock block={block} />
- </BubbleContent>
- </Bubble>
- ))}
+ .map((block, index) =>
+ isSteeringHint(block) ? (
+ <SteeringMessageBubble
+ blocks={getHintItems(block)}
+ status="steered"
+ key={block.id}
+ />
+ ) : (
+ <Bubble key={index} variant={isUser ? 'muted' : 'ghost'}>
+ <BubbleContent>
+ <ASBlock block={block} />
+ </BubbleContent>
+ </Bubble>
+ ),
+ )}
{message.finished_reason === ReplyFinishedReason.ERROR && (
<Alert
variant="destructive"
@@ -697,17 +761,7 @@ export function ASBlock({ block, ...props }: ASBlockProps) {
} else {
hintLabel = t('common.message');
}
- const items: (TextBlock | DataBlock)[] =
- typeof block.hint === 'string'
- ? [
- {
- type: 'text',
- id: `${block.id}-text`,
- text: block.hint,
- created_at: block.created_at,
- },
- ]
- : block.hint;
+ const items = getHintItems(block);
return (
<Collapsible>
<CollapsibleTrigger asChild>
diff --git a/examples/web_ui/frontend/src/components/chat/ChatContent.tsx b/examples/web_ui/frontend/src/components/chat/ChatContent.tsx
index bbcbf2298..560434776 100644
--- a/examples/web_ui/frontend/src/components/chat/ChatContent.tsx
+++ b/examples/web_ui/frontend/src/components/chat/ChatContent.tsx
@@ -11,7 +11,7 @@ import React, { useEffect, useMemo, useState } from 'react';
import type { GitStatus } from '@/api';
import type { ChatQueueItem } from '@/api/chat';
-import { ASMessageBubble } from '@/components/chat/ASMessageBubble.tsx';
+import { ASMessageBubble, SteeringMessageBubble } from '@/components/chat/ASMessageBubble.tsx';
import { ConfirmCard } from '@/components/chat/ConfirmCard.tsx';
import { FlipCard } from '@/components/chat/FlipCard.tsx';
import { QueuedMessages } from '@/components/chat/QueuedMessages.tsx';
@@ -80,6 +80,7 @@ interface ChatContentProps {
queuedCount: number;
queuedItems: ChatQueueItem[];
queueReorderDisabled: boolean;
+ activeReplyId: string | null;
disabled: boolean;
onSend: (content: ContentBlock[]) => Promise<void> | void;
onUserConfirm: (
@@ -94,6 +95,7 @@ interface ChatContentProps {
onInterrupt?: () => void;
onUpdateQueued: (itemId: string, text: string) => Promise<void>;
onDeleteQueued: (itemId: string) => Promise<void>;
+ onSteerQueued: (itemId: string, replyId: string) => Promise<void>;
onMoveQueued: (itemId: string, direction: -1 | 1) => Promise<void>;
onReorderQueued: (itemIds: string[]) => Promise<void>;
voiceState?: RealtimeConnectionState;
@@ -132,6 +134,7 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({
queuedCount,
queuedItems,
queueReorderDisabled,
+ activeReplyId,
disabled,
onSend,
onUserConfirm,
@@ -140,6 +143,7 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({
onInterrupt,
onUpdateQueued,
onDeleteQueued,
+ onSteerQueued,
onMoveQueued,
onReorderQueued,
voiceState,
@@ -156,10 +160,29 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({
onRefreshGit,
}) => {
const { t, i18n } = useTranslation();
+ const { deferredItems, steeringMessages } = useMemo(() => {
+ const deferred: ChatQueueItem[] = [];
+ const steering: Array<{ id: string; content: ContentBlock[] }> = [];
+ for (const item of queuedItems) {
+ if (item.state !== 'steering') {
+ deferred.push(item);
+ continue;
+ }
+ const messages = Array.isArray(item.input) ? item.input : [item.input];
+ for (const message of messages) {
+ steering.push({
+ id: `${item.id}:${message.id}`,
+ content: message.content,
+ });
+ }
+ }
+ return { deferredItems: deferred, steeringMessages: steering };
+ }, [queuedItems]);
+
// Only a session that finished loading with nothing in it is empty.
// Treating "no messages yet" as empty would flash the greeting over
// every session that does have history.
- const isEmpty = !loading && msgs.length === 0;
+ const isEmpty = !loading && msgs.length === 0 && steeringMessages.length === 0;
// A spinner that appears and vanishes inside a couple of frames reads
// as a flicker, not as feedback — so hold it back until the load has
@@ -236,6 +259,17 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({
</MessageScrollerItem>
);
})}
+ {steeringMessages.map((message) => (
+ <MessageScrollerItem
+ key={message.id}
+ messageId={`steering:${message.id}`}
+ >
+ <SteeringMessageBubble
+ blocks={message.content}
+ status="steering"
+ />
+ </MessageScrollerItem>
+ ))}
{msgs.length > 0 &&
msgs[msgs.length - 1].finished_reason ===
ReplyFinishedReason.EXCEED_MAX_ITERS &&
@@ -310,10 +344,12 @@ const ChatContentComponent: React.FC<ChatContentProps> = ({
)}
</FlipCard>
<QueuedMessages
- items={queuedItems}
+ items={deferredItems}
reorderDisabled={queueReorderDisabled}
+ activeReplyId={activeReplyId}
onUpdate={onUpdateQueued}
onDelete={onDeleteQueued}
+ onSteer={onSteerQueued}
onMove={onMoveQueued}
onReorder={onReorderQueued}
/>
diff --git a/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx b/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx
index 967acf599..c630a2fac 100644
--- a/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx
+++ b/examples/web_ui/frontend/src/components/chat/QueuedMessages.tsx
@@ -1,5 +1,15 @@
import { getTextContent } from '@agentscope-ai/agentscope/message';
-import { ArrowDown, ArrowUp, Check, GripVertical, Loader2, Pencil, Trash2, X } from 'lucide-react';
+import {
+ ArrowDown,
+ ArrowUp,
+ Check,
+ CornerDownRight,
+ GripVertical,
+ Loader2,
+ Pencil,
+ Trash2,
+ X,
+} from 'lucide-react';
import { type ReactNode, useState } from 'react';
import type { ChatQueueItem } from '@/api/chat';
@@ -12,8 +22,10 @@ import { cn } from '@/lib/utils';
interface QueuedMessagesProps {
items: ChatQueueItem[];
reorderDisabled: boolean;
+ activeReplyId: string | null;
onUpdate: (itemId: string, text: string) => Promise<void>;
onDelete: (itemId: string) => Promise<void>;
+ onSteer: (itemId: string, replyId: string) => Promise<void>;
onMove: (itemId: string, direction: -1 | 1) => Promise<void>;
onReorder: (itemIds: string[]) => Promise<void>;
}
@@ -58,8 +70,10 @@ function QueueActionButton({ label, disabled, onClick, children }: QueueActionBu
export function QueuedMessages({
items,
reorderDisabled,
+ activeReplyId,
onUpdate,
onDelete,
+ onSteer,
onMove,
onReorder,
}: QueuedMessagesProps) {
@@ -108,7 +122,8 @@ export function QueuedMessages({
// Optimistic ids are local-only and cannot be sent to mutation
// endpoints until POST /chat returns the stable server id.
const busy = busyId === item.id || item.id.startsWith('optimistic:');
- const reorderBusy = busy || reorderDisabled;
+ const steering = item.state === 'steering';
+ const reorderBusy = busy || reorderDisabled || steering;
const editable = !Array.isArray(item.input);
return (
<div
@@ -175,6 +190,21 @@ export function QueuedMessages({
{itemText(item) || t('chatQueue.attachmentOnly')}
</p>
)}
+ <span
+ className={cn(
+ 'shrink-0 rounded-full px-2 py-0.5 text-[11px] font-medium',
+ item.state === 'steering' && 'bg-primary/10 text-primary',
+ item.state === 'failed' && 'bg-destructive/10 text-destructive',
+ item.state === 'queued' && 'bg-muted text-muted-foreground',
+ )}
+ title={item.error ?? undefined}
+ >
+ {item.state === 'steering'
+ ? t('chatQueue.stateSteering')
+ : item.state === 'failed'
+ ? t('chatQueue.stateFailed')
+ : t('chatQueue.stateQueued')}
+ </span>
{busy ? (
<Loader2 className="size-4 shrink-0 animate-spin text-muted-foreground" />
@@ -201,6 +231,19 @@ export function QueuedMessages({
</>
) : (
<>
+ {activeReplyId && (
+ <QueueActionButton
+ disabled={steering}
+ label={t('chatQueue.steer')}
+ onClick={() =>
+ void run(item.id, () =>
+ onSteer(item.id, activeReplyId),
+ )
+ }
+ >
+ <CornerDownRight className="size-3.5" />
+ </QueueActionButton>
+ )}
<QueueActionButton
disabled={reorderBusy || index === 0}
label={t('chatQueue.moveUp')}
@@ -216,7 +259,7 @@ export function QueuedMessages({
<ArrowDown className="size-3.5" />
</QueueActionButton>
<QueueActionButton
- disabled={!editable}
+ disabled={!editable || steering}
label={t('chatQueue.edit')}
onClick={() => {
setDraft(itemText(item));
@@ -226,6 +269,7 @@ export function QueuedMessages({
<Pencil className="size-3.5" />
</QueueActionButton>
<QueueActionButton
+ disabled={steering}
label={t('chatQueue.delete')}
onClick={() => void run(item.id, () => onDelete(item.id))}
>
diff --git a/examples/web_ui/frontend/src/hooks/useChatQueue.ts b/examples/web_ui/frontend/src/hooks/useChatQueue.ts
index 97b02fc9e..31ca511d8 100644
--- a/examples/web_ui/frontend/src/hooks/useChatQueue.ts
+++ b/examples/web_ui/frontend/src/hooks/useChatQueue.ts
@@ -152,6 +152,8 @@ export function useChatQueue(
id: optimisticId,
created_at: message.created_at,
input: message,
+ state: 'queued',
+ error: null,
},
]);
return optimisticId;
@@ -283,6 +285,40 @@ export function useChatQueue(
[agentId, sessionId, session, applyMutationSnapshot, onError],
);
+ const steerQueued = useCallback(
+ async (itemId: string, replyId: string) => {
+ if (!agentId || !sessionId || activeSessionRef.current !== session) return;
+ const previousItem = itemsRef.current.find((item) => item.id === itemId);
+ if (!previousItem) return;
+ updateItems(
+ itemsRef.current.map((item) =>
+ item.id === itemId
+ ? { ...item, state: 'steering' as const, error: null }
+ : item,
+ ),
+ );
+ const snapshotVersion = snapshotVersionRef.current;
+ try {
+ const response = await chatApi.steerQueued(itemId, agentId, sessionId, replyId);
+ applyMutationSnapshot(response.items, snapshotVersion);
+ } catch (error) {
+ if (activeSessionRef.current === session) {
+ if (snapshotVersion === snapshotVersionRef.current) {
+ updateItems(
+ itemsRef.current.map((item) =>
+ item.id === itemId ? previousItem : item,
+ ),
+ );
+ }
+ void refreshQueue();
+ onError(error as Error);
+ }
+ throw error;
+ }
+ },
+ [agentId, sessionId, session, applyMutationSnapshot, onError, updateItems, refreshQueue],
+ );
+
const reorderQueued = useCallback(
async (visibleItemIds: string[]) => {
if (!agentId || !sessionId || activeSessionRef.current !== session) return;
@@ -356,13 +392,16 @@ export function useChatQueue(
[conversationMessageIds, items],
);
const reorderDisabled = useMemo(
- () => items.some((item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX)),
+ () =>
+ items.some(
+ (item) => item.id.startsWith(OPTIMISTIC_ITEM_PREFIX) || item.state === 'steering',
+ ),
[items],
);
return {
items: visibleItems,
- visibleCount: visibleItems.length,
+ visibleCount: visibleItems.filter((item) => item.state !== 'steering').length,
pendingCount: items.length,
reorderDisabled,
addOptimistic,
@@ -373,6 +412,7 @@ export function useChatQueue(
finishItem,
updateQueued,
deleteQueued,
+ steerQueued,
moveQueued,
reorderQueued,
};
diff --git a/examples/web_ui/frontend/src/hooks/useMessages.ts b/examples/web_ui/frontend/src/hooks/useMessages.ts
index a4bc4564f..9a9269d22 100644
--- a/examples/web_ui/frontend/src/hooks/useMessages.ts
+++ b/examples/web_ui/frontend/src/hooks/useMessages.ts
@@ -164,6 +164,9 @@ export function useMessages(
// state over a session that does have messages.
const [loadedKey, setLoadedKey] = useState<string | null>(null);
const [phase, setPhase] = useState<ReplyPhase>('idle');
+ // Only a running reply accepts steering. Parked replies retain their
+ // streaming phase and currentReplyRef for confirmation and Stop.
+ const [activeReplyId, setActiveReplyId] = useState<string | null>(null);
const [error, setError] = useState<Error | null>(null);
// Pending subagent HITL cards projected onto this (leader) session.
const [subagentHitl, setSubagentHitl] = useState<SubagentHitlEntry[]>([]);
@@ -180,6 +183,7 @@ export function useMessages(
finishItem,
updateQueued,
deleteQueued,
+ steerQueued,
moveQueued,
reorderQueued,
} = useChatQueue(agentId, sessionId, setError);
@@ -272,6 +276,7 @@ export function useMessages(
clearInterruptTimer();
currentReplyRef.current = null;
setPhase('idle');
+ setActiveReplyId(null);
setError(failure);
toast.error(failure.message);
} else if (custom.name === 'chat_input_cancelled') {
@@ -281,7 +286,15 @@ export function useMessages(
clearInterruptTimer();
currentReplyRef.current = null;
setPhase('idle');
+ setActiveReplyId(null);
toast.info(message);
+ } else if (custom.name === 'chat_input_injected') {
+ const value = custom.value as ChatInputTerminalValue;
+ finishItem(value);
+ toast.success(t('chatQueue.injected'));
+ } else if (custom.name === 'chat_input_steer_failed') {
+ const value = custom.value as ChatInputTerminalValue;
+ toast.error(value.message ?? t('chatQueue.steerFailed'));
}
return;
}
@@ -307,6 +320,7 @@ export function useMessages(
msgsRef.current = [...msgsRef.current, msg];
currentReplyRef.current = msg;
}
+ setActiveReplyId(e.reply_id);
clearInterruptTimer();
setPhase('streaming');
} else {
@@ -334,6 +348,14 @@ export function useMessages(
currentReplyRef.current = updated;
}
}
+ if (
+ event.type === EventType.REQUIRE_USER_CONFIRM ||
+ event.type === EventType.REQUIRE_EXTERNAL_EXECUTION
+ ) {
+ setActiveReplyId((active) =>
+ !event.reply_id || active === event.reply_id ? null : active,
+ );
+ }
if (
event.type === EventType.REPLY_END &&
(!event.reply_id ||
@@ -342,6 +364,7 @@ export function useMessages(
) {
clearInterruptTimer();
setPhase('idle');
+ setActiveReplyId(null);
currentReplyRef.current = null;
}
}
@@ -393,6 +416,7 @@ export function useMessages(
setError(null);
clearInterruptTimer();
setPhase('idle');
+ setActiveReplyId(null);
setSubagentHitl([]);
audioManager?.disposeAll();
@@ -425,9 +449,13 @@ export function useMessages(
// while parked leaves the UI stuck on ``idle`` with no
// way to abort.
const tail = messages[messages.length - 1];
- if (is_running || hasPendingToolCall(tail)) {
+ const pendingToolCall = hasPendingToolCall(tail);
+ if (is_running || pendingToolCall) {
setPhase('streaming');
- if (hasPendingToolCall(tail)) {
+ if (is_running && !pendingToolCall && tail?.role === 'assistant') {
+ setActiveReplyId(tail.id);
+ }
+ if (pendingToolCall) {
// Prime the ref so continuation events (which
// arrive without a fresh REPLY_START) apply to
// the right msg.
@@ -712,6 +740,8 @@ export function useMessages(
reorderQueued,
phase: ownsConversation ? phase : ('idle' as ReplyPhase),
error: ownsConversation ? error : null,
+ activeReplyId: ownsConversation && phase === 'streaming' ? activeReplyId : null,
+ steerQueued,
send,
onUserConfirm,
onSubagentConfirm,
diff --git a/examples/web_ui/frontend/src/i18n/locales/en.json b/examples/web_ui/frontend/src/i18n/locales/en.json
index cd7e7ce6a..0bdc57bc1 100644
--- a/examples/web_ui/frontend/src/i18n/locales/en.json
+++ b/examples/web_ui/frontend/src/i18n/locales/en.json
@@ -115,8 +115,15 @@
"moveDown": "Move down",
"edit": "Edit",
"delete": "Delete",
+ "steer": "Steer current reply",
"save": "Save",
"cancel": "Cancel",
+ "stateQueued": "Queued",
+ "stateSteering": "Steering",
+ "stateSteered": "Steered",
+ "stateFailed": "Failed",
+ "injected": "The queued message was injected into the current reply.",
+ "steerFailed": "The queued message could not steer the current reply.",
"processFailed": "The queued message could not be processed.",
"processingCancelled": "Queued message processing was interrupted."
},
diff --git a/examples/web_ui/frontend/src/i18n/locales/zh.json b/examples/web_ui/frontend/src/i18n/locales/zh.json
index 6d25c0263..a0625bff3 100644
--- a/examples/web_ui/frontend/src/i18n/locales/zh.json
+++ b/examples/web_ui/frontend/src/i18n/locales/zh.json
@@ -115,8 +115,15 @@
"moveDown": "下移",
"edit": "编辑",
"delete": "删除",
+ "steer": "引导当前回复",
"save": "保存",
"cancel": "取消",
+ "stateQueued": "排队中",
+ "stateSteering": "引导中",
+ "stateSteered": "已引导",
+ "stateFailed": "失败",
+ "injected": "排队消息已注入当前回复。",
+ "steerFailed": "排队消息未能引导当前回复。",
"processFailed": "排队消息处理失败。",
"processingCancelled": "排队消息处理已中断。"
},
diff --git a/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx
index 0ae50a4ee..ecf0738ca 100644
--- a/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx
+++ b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx
@@ -264,12 +264,14 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatView
msgs,
loading: messagesLoading,
phase,
+ activeReplyId,
queuedCount,
queuedItems,
queueReorderDisabled,
send,
updateQueued,
deleteQueued,
+ steerQueued,
moveQueued,
reorderQueued,
onUserConfirm,
@@ -924,6 +926,7 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatView
git={workspaceStatus?.git ?? null}
onRefreshGit={refetchWorkspaceStatus}
phase={phase}
+ activeReplyId={activeReplyId}
queuedCount={queuedCount}
queuedItems={queuedItems}
queueReorderDisabled={queueReorderDisabled}
@@ -933,6 +936,7 @@ export function ChatViewport({ agentId, sessionId, onSessionsChanged }: ChatView
onInterrupt={interrupt}
onUpdateQueued={updateQueued}
onDeleteQueued={deleteQueued}
+ onSteerQueued={steerQueued}
onMoveQueued={moveQueued}
onReorderQueued={reorderQueued}
voiceState={realtimeVoice.state}
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index fc8f8f4ab..e2f946f63 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -9,6 +9,7 @@ import warnings
from asyncio import Queue
from copy import deepcopy
+from contextlib import aclosing
from fnmatch import fnmatch
from datetime import datetime
from typing import (
@@ -322,13 +323,13 @@ class Agent:
agent won't re-send the requiring events for the unconfirmed
or unexecuted tool calls.
"""
- async for chunk in self._reply(
- inputs=inputs,
- structured_schema=structured_schema,
- ):
- if isinstance(chunk, Msg) and not yield_final_msg:
- continue
- yield chunk
+ async with aclosing(
+ self._reply(inputs=inputs, structured_schema=structured_schema),
+ ) as stream:
+ async for chunk in stream:
+ if isinstance(chunk, Msg) and not yield_final_msg:
+ continue
+ yield chunk
async def reply(
self,
@@ -930,11 +931,14 @@ class Agent:
structured_schema: Type[BaseModel] | None = structured_schema,
) -> AsyncGenerator[AgentEvent | Msg, None]:
if index >= len(self._reply_middlewares):
- async for item in self._reply_impl(
- inputs=inputs,
- structured_schema=structured_schema,
- ):
- yield item
+ async with aclosing(
+ self._reply_impl(
+ inputs=inputs,
+ structured_schema=structured_schema,
+ ),
+ ) as stream:
+ async for item in stream:
+ yield item
else:
mw = self._reply_middlewares[index]
input_kwargs = {
@@ -945,28 +949,34 @@ class Agent:
async def next_handler(
**kwargs: Any,
) -> AsyncGenerator[AgentEvent | Msg, None]:
- async for item in execute_chain(
- index + 1,
- **{**input_kwargs, **kwargs},
- ):
+ async with aclosing(
+ execute_chain(
+ index + 1,
+ **{**input_kwargs, **kwargs},
+ ),
+ ) as stream:
+ async for item in stream:
+ yield item
+
+ async with aclosing(
+ mw.on_reply(
+ agent=self,
+ input_kwargs=input_kwargs,
+ next_handler=next_handler,
+ ),
+ ) as stream:
+ async for item in stream:
yield item
- async for item in mw.on_reply(
- agent=self,
- input_kwargs=input_kwargs,
- next_handler=next_handler,
- ):
- yield item
-
agen = execute_chain()
self._receive_reply_end = False
- async for item in agen:
- # Set before the yield: the suspended `_reply_impl` checks the
- # flag once resumed by the next pull
- if isinstance(item, ReplyEndEvent):
- self._receive_reply_end = True
- yield item
+ async with aclosing(agen):
+ async for item in agen:
+ # Set before yielding so the suspended loop can observe it.
+ if isinstance(item, ReplyEndEvent):
+ self._receive_reply_end = True
+ yield item
async def _close_unfinished_tool_calls(
self,
@@ -1096,6 +1106,10 @@ class Agent:
# - if incoming event and agent is waiting for an event
# - if event is None and agent is not waiting for an event
# ===================================================================
+ if event is not None:
+ # Receive cancellation redirected by the service before a
+ # continuation can apply a decision or execute a tool.
+ await asyncio.sleep(0)
is_awaiting = await self._check_incoming_event(event)
# ===================================================================
@@ -1121,6 +1135,10 @@ class Agent:
reply_id=self.state.reply_id,
name=self.name,
)
+ # A consumer may re-arm cancellation while registering or
+ # publishing REPLY_START. Receive it inside this cleanup scope
+ # even when subsequent model/tool awaits complete inline.
+ await asyncio.sleep(0)
# Update the structured output tool for new requirements or
# from the previous reply
diff --git a/src/agentscope/app/_bus_ops.py b/src/agentscope/app/_bus_ops.py
index 57eeea681..00b364bf6 100644
--- a/src/agentscope/app/_bus_ops.py
+++ b/src/agentscope/app/_bus_ops.py
@@ -59,6 +59,10 @@ class ChatQueueBusyError(RuntimeError):
"""Raised when a short queue mutation lock cannot be acquired."""
+class ChatSteeringUnavailableError(RuntimeError):
+ """Raised when a queued turn cannot steer the requested active reply."""
+
+
@asynccontextmanager
async def chat_input_mutation(
bus: "MessageBus",
@@ -359,6 +363,7 @@ async def enqueue_chat_input(
"agent_id": agent_id,
"created_at": datetime.now(timezone.utc).isoformat(),
"input": serialized,
+ "state": "queued",
}
async with _chat_input_user_quota(bus, user_id):
if (
@@ -451,6 +456,310 @@ async def list_chat_inputs(
return [_public_chat_input(payload) for payload in payloads]
+async def register_active_chat_reply(
+ bus: "MessageBus",
+ session_id: str,
+ reply_id: str,
+) -> None:
+ """Register the reply currently holding a session's run lock.
+
+ Internal lifecycle writes wait for the mutation lock instead of using the
+ bounded foreground timeout. The registry entry is the authoritative target
+ checked by the public Steer endpoint.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ session_id (`str`):
+ Session whose reply started or resumed.
+ reply_id (`str`):
+ Active reply identifier.
+ """
+ async with bus.acquire_lock(
+ MessageBusKeys.chat_input_mutation_lock(session_id),
+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,
+ ):
+ await bus.registry_set(
+ MessageBusKeys.chat_active_reply_registry(),
+ session_id,
+ reply_id,
+ )
+
+
+async def steer_chat_input(
+ bus: "MessageBus",
+ user_id: str,
+ session_id: str,
+ agent_id: str,
+ item_id: str,
+ reply_id: str,
+) -> list[dict]:
+ """Reserve one pending queue item for the requested active reply.
+
+ The item stays in the durable FIFO until middleware acknowledges actual
+ context injection. Repeating the same request is idempotent.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ user_id (`str`):
+ User that must own the pending item.
+ session_id (`str`):
+ Session that owns the queue and active reply.
+ agent_id (`str`):
+ Agent that must own the pending item.
+ item_id (`str`):
+ Pending queue item to steer with.
+ reply_id (`str`):
+ Reply observed as active by the client.
+
+ Returns:
+ `list[dict]`:
+ Complete public queue snapshot after reservation.
+
+ Raises:
+ `LookupError`:
+ The item is no longer pending.
+ `ChatSteeringUnavailableError`:
+ The reply is stale, idle, or the item targets another reply.
+ `ChatQueueBusyError`:
+ The foreground mutation lock cannot be acquired promptly.
+ """
+ async with chat_input_mutation(bus, session_id):
+ active_replies = await bus.registry_getall(
+ MessageBusKeys.chat_active_reply_registry(),
+ )
+ active_reply_id = active_replies.get(session_id)
+ is_running = await bus.is_locked(
+ MessageBusKeys.session_lock(session_id),
+ )
+ if not is_running or active_reply_id != reply_id:
+ raise ChatSteeringUnavailableError(
+ f"Reply '{reply_id}' is no longer active.",
+ )
+
+ payloads = await _read_chat_input_payloads(bus, session_id)
+ item = _owned_chat_input(
+ payloads,
+ user_id,
+ session_id,
+ agent_id,
+ item_id,
+ )
+ item_state = item.get("state", "queued")
+ target_reply_id = item.get("target_reply_id")
+ if item_state == "steering":
+ if target_reply_id != reply_id:
+ raise ChatSteeringUnavailableError(
+ f"Queued message '{item_id}' is steering another reply.",
+ )
+ return [_public_chat_input(payload) for payload in payloads]
+ if item_state not in ("queued", "failed"):
+ raise ChatSteeringUnavailableError(
+ f"Queued message '{item_id}' cannot be steered now.",
+ )
+
+ item["state"] = "steering"
+ item["target_reply_id"] = reply_id
+ item.pop("error", None)
+ await bus.queue_replace(
+ MessageBusKeys.chat_inputs(session_id),
+ [queue_entry(payload) for payload in payloads],
+ )
+ return await _notify_chat_queue_changed(bus, session_id, payloads)
+
+
+async def list_steering_chat_inputs(
+ bus: "MessageBus",
+ session_id: str,
+ reply_id: str,
+) -> list[dict]:
+ """Read items reserved for one reply without removing them.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ session_id (`str`):
+ Session whose queue should be inspected.
+ reply_id (`str`):
+ Active reply that must own the steering reservation.
+
+ Returns:
+ `list[dict]`:
+ Public copies of matching items in FIFO order.
+ """
+ async with bus.acquire_lock(
+ MessageBusKeys.chat_input_mutation_lock(session_id),
+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,
+ ):
+ payloads = await _read_chat_input_payloads(bus, session_id)
+ return [
+ _public_chat_input(payload)
+ for payload in payloads
+ if payload.get("state", "queued") == "steering"
+ and payload.get("target_reply_id") == reply_id
+ ]
+
+
+async def acknowledge_steering_chat_inputs(
+ bus: "MessageBus",
+ session_id: str,
+ reply_id: str,
+ item_ids: list[str],
+) -> list[dict]:
+ """Remove steering items after they were appended to agent context.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ session_id (`str`):
+ Session whose FIFO contains the items.
+ reply_id (`str`):
+ Reply that consumed the items.
+ item_ids (`list[str]`):
+ Exact queue item ids to acknowledge.
+
+ Returns:
+ `list[dict]`:
+ Public copies of the removed items.
+
+ Raises:
+ `LookupError`:
+ Any requested item is no longer reserved for this reply.
+ """
+ requested_ids = set(item_ids)
+ async with bus.acquire_lock(
+ MessageBusKeys.chat_input_mutation_lock(session_id),
+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,
+ ):
+ active_replies = await bus.registry_getall(
+ MessageBusKeys.chat_active_reply_registry(),
+ )
+ if active_replies.get(session_id) != reply_id:
+ raise LookupError(
+ f"Reply '{reply_id}' is no longer active.",
+ )
+ payloads = await _read_chat_input_payloads(bus, session_id)
+ removed = [
+ payload
+ for payload in payloads
+ if payload.get("id") in requested_ids
+ and payload.get("state", "queued") == "steering"
+ and payload.get("target_reply_id") == reply_id
+ ]
+ if {payload.get("id") for payload in removed} != requested_ids:
+ raise LookupError(
+ "One or more steering messages are no longer pending.",
+ )
+ remaining = [payload for payload in payloads if payload not in removed]
+ await bus.queue_replace(
+ MessageBusKeys.chat_inputs(session_id),
+ [queue_entry(payload) for payload in remaining],
+ )
+ for payload in removed:
+ await discard_input(bus, payload)
+ await _notify_chat_queue_changed(bus, session_id, remaining)
+ return [_public_chat_input(payload) for payload in removed]
+
+
+async def fail_steering_chat_input(
+ bus: "MessageBus",
+ session_id: str,
+ reply_id: str,
+ item_id: str,
+ error: str,
+) -> None:
+ """Keep a failed steering item in the FIFO with a visible error.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ session_id (`str`):
+ Session whose queue owns the item.
+ reply_id (`str`):
+ Reply the item attempted to steer.
+ item_id (`str`):
+ Failed queue item id.
+ error (`str`):
+ User-facing failure description.
+ """
+ async with bus.acquire_lock(
+ MessageBusKeys.chat_input_mutation_lock(session_id),
+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,
+ ):
+ payloads = await _read_chat_input_payloads(bus, session_id)
+ changed = False
+ for payload in payloads:
+ if (
+ payload.get("id") == item_id
+ and payload.get("state", "queued") == "steering"
+ and payload.get("target_reply_id") == reply_id
+ ):
+ payload["state"] = "failed"
+ payload["error"] = error
+ payload.pop("target_reply_id", None)
+ changed = True
+ break
+ if changed:
+ await bus.queue_replace(
+ MessageBusKeys.chat_inputs(session_id),
+ [queue_entry(payload) for payload in payloads],
+ )
+ await _notify_chat_queue_changed(bus, session_id, payloads)
+
+
+async def finish_active_chat_reply(
+ bus: "MessageBus",
+ session_id: str,
+ reply_id: str,
+) -> list[str]:
+ """Clear an active reply and restore its unconsumed steering items.
+
+ Args:
+ bus (`MessageBus`):
+ Application message bus.
+ session_id (`str`):
+ Session whose run is finishing.
+ reply_id (`str`):
+ Reply whose active registry entry should be cleared.
+
+ Returns:
+ `list[str]`:
+ Queue item ids restored to deferred-send state.
+ """
+ async with bus.acquire_lock(
+ MessageBusKeys.chat_input_mutation_lock(session_id),
+ ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS,
+ ):
+ active_replies = await bus.registry_getall(
+ MessageBusKeys.chat_active_reply_registry(),
+ )
+ if active_replies.get(session_id) != reply_id:
+ return []
+ await bus.registry_del(
+ MessageBusKeys.chat_active_reply_registry(),
+ session_id,
+ )
+ payloads = await _read_chat_input_payloads(bus, session_id)
+ restored_ids: list[str] = []
+ for payload in payloads:
+ if (
+ payload.get("state", "queued") == "steering"
+ and payload.get("target_reply_id") == reply_id
+ ):
+ payload["state"] = "queued"
+ payload.pop("target_reply_id", None)
+ payload.pop("error", None)
+ restored_ids.append(payload["id"])
+ if restored_ids:
+ await bus.queue_replace(
+ MessageBusKeys.chat_inputs(session_id),
+ [queue_entry(payload) for payload in payloads],
+ )
+ await _notify_chat_queue_changed(bus, session_id, payloads)
+ return restored_ids
+
+
async def update_chat_input(
bus: "MessageBus",
user_id: str,
@@ -497,8 +806,15 @@ async def update_chat_input(
agent_id,
item_id,
)
+ if item.get("state", "queued") == "steering":
+ raise LookupError(
+ f"Queued message '{item_id}' is currently steering.",
+ )
previous = dict(item)
item["input"] = serialized
+ item["state"] = "queued"
+ item.pop("target_reply_id", None)
+ item.pop("error", None)
item["input_ref"] = uuid.uuid4().hex
await bus.registry_set(
MessageBusKeys.chat_input_payloads(session_id),
@@ -553,6 +869,10 @@ async def delete_chat_input(
agent_id,
item_id,
)
+ if item.get("state", "queued") == "steering":
+ raise LookupError(
+ f"Queued message '{item_id}' is currently steering.",
+ )
payloads.remove(item)
await bus.queue_replace(
MessageBusKeys.chat_inputs(session_id),
@@ -600,6 +920,13 @@ async def reorder_chat_inputs(
"""
async with chat_input_mutation(bus, session_id):
payloads = await _read_chat_input_payloads(bus, session_id)
+ if any(
+ payload.get("state", "queued") == "steering"
+ for payload in payloads
+ ):
+ raise ValueError(
+ "The queue cannot be reordered while a message is steering.",
+ )
owned = [
payload
for payload in payloads
@@ -814,6 +1141,8 @@ def _public_chat_input(payload: dict) -> dict:
"id": payload["id"],
"created_at": payload["created_at"],
"input": payload["input"],
+ "state": payload.get("state", "queued"),
+ "error": payload.get("error"),
}
diff --git a/src/agentscope/app/_router/_chat.py b/src/agentscope/app/_router/_chat.py
index e3ba14d11..639db387f 100644
--- a/src/agentscope/app/_router/_chat.py
+++ b/src/agentscope/app/_router/_chat.py
@@ -35,6 +35,7 @@ from ._schema import (
ChatRequest,
ChatTriggerResponse,
ReorderChatQueueRequest,
+ SteerChatQueueItemRequest,
UpdateChatQueueItemRequest,
)
from .._manager import ChatRunRegistry
@@ -48,11 +49,13 @@ from ..storage import StorageBase
from .._bus_ops import (
ChatQueueBusyError,
ChatQueueFullError,
+ ChatSteeringUnavailableError,
delete_chat_input,
enqueue_chat_input,
enqueue_run_trigger,
list_chat_inputs,
reorder_chat_inputs,
+ steer_chat_input,
update_chat_input,
)
from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent
@@ -200,6 +203,72 @@ async def reorder_chat_queue(
return ChatQueueResponse(items=items)
+@chat_router.post(
+ "/queue/{item_id}/steer",
+ response_model=ChatQueueResponse,
+ summary="Steer an active reply with one pending user turn",
+)
+async def steer_chat_queue_item(
+ item_id: Annotated[
+ str,
+ Path(description="Stable id of the pending item to inject."),
+ ],
+ request: SteerChatQueueItemRequest,
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ message_bus: MessageBus = Depends(get_message_bus),
+) -> ChatQueueResponse:
+ """Reserve a pending item for non-interrupting reply steering.
+
+ Args:
+ item_id (`str`):
+ Stable id of the pending item to inject.
+ request (`SteerChatQueueItemRequest`):
+ Target session, agent, and active reply id.
+ user_id (`str`):
+ Injected authenticated user id.
+ storage (`StorageBase`):
+ Injected persistent session storage.
+ message_bus (`MessageBus`):
+ Injected message bus containing queue and active-reply state.
+
+ Returns:
+ `ChatQueueResponse`:
+ Complete queue snapshot with the selected item steering.
+
+ Raises:
+ `HTTPException`:
+ HTTP 404 for a missing session, HTTP 409 for a stale reply or
+ started item, or HTTP 503 when the queue is busy.
+ """
+ await _ensure_session(
+ storage,
+ user_id,
+ request.agent_id,
+ request.session_id,
+ )
+ try:
+ items = await steer_chat_input(
+ message_bus,
+ user_id,
+ request.session_id,
+ request.agent_id,
+ item_id,
+ request.reply_id,
+ )
+ except (LookupError, ChatSteeringUnavailableError) as exc:
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT,
+ detail=str(exc),
+ ) from exc
+ except ChatQueueBusyError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=str(exc),
+ ) from exc
+ return ChatQueueResponse(items=items)
+
+
@chat_router.patch(
"/queue/{item_id}",
response_model=ChatQueueResponse,
diff --git a/src/agentscope/app/_router/_schema/__init__.py b/src/agentscope/app/_router/_schema/__init__.py
index 8b02b8720..1ceb3e62b 100644
--- a/src/agentscope/app/_router/_schema/__init__.py
+++ b/src/agentscope/app/_router/_schema/__init__.py
@@ -17,6 +17,7 @@ from ._chat import (
ChatQueueItem,
ChatQueueResponse,
ReorderChatQueueRequest,
+ SteerChatQueueItemRequest,
UpdateChatQueueItemRequest,
)
from ._health import ComponentStatus, HealthResponse
@@ -176,6 +177,7 @@ __all__ = [
"ChatQueueItem",
"ChatQueueResponse",
"ReorderChatQueueRequest",
+ "SteerChatQueueItemRequest",
"UpdateChatQueueItemRequest",
# Credential
"CreateCredentialRequest",
diff --git a/src/agentscope/app/_router/_schema/_chat.py b/src/agentscope/app/_router/_schema/_chat.py
index b43cd7bda..dd705058d 100644
--- a/src/agentscope/app/_router/_schema/_chat.py
+++ b/src/agentscope/app/_router/_schema/_chat.py
@@ -69,6 +69,14 @@ class ChatQueueItem(BaseModel):
input: Msg | NonEmptyMsgList = Field(
description="One message or non-empty ordered message list.",
)
+ state: Literal["queued", "steering", "failed"] = Field(
+ default="queued",
+ description="Current deferred-send or steering state.",
+ )
+ error: str | None = Field(
+ default=None,
+ description="Visible steering failure, when state is failed.",
+ )
class ChatQueueResponse(BaseModel):
@@ -93,6 +101,20 @@ class UpdateChatQueueItemRequest(BaseModel):
)
+class SteerChatQueueItemRequest(BaseModel):
+ """Reserve one pending input for a currently active reply."""
+
+ agent_id: str = Field(
+ description="Agent that owns the target session.",
+ )
+ session_id: str = Field(
+ description="Session whose pending item will steer the reply.",
+ )
+ reply_id: str = Field(
+ description="Active reply that should consume the pending item.",
+ )
+
+
class ReorderChatQueueRequest(BaseModel):
"""Set the complete pending queue order."""
diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.py
index 5c7c6ab60..2c82b87df 100644
--- a/src/agentscope/app/_service/_chat.py
+++ b/src/agentscope/app/_service/_chat.py
@@ -24,8 +24,10 @@ from .._bus_ops import (
abandon_inbox_consumer,
deliver_to_inbox,
enqueue_run_trigger,
+ finish_active_chat_reply,
has_pending_inbox_or_release,
publish_session_event,
+ register_active_chat_reply,
register_inbox_consumer,
)
from ..message_bus import MessageBus, MessageBusKeys
@@ -44,6 +46,7 @@ from .._manager import BackgroundTaskManager, SchedulerManager
from ..workspace_manager import WorkspaceManagerBase
from ..middleware import (
InboxMiddleware,
+ SteeringMiddleware,
SOPStepSubmitMiddleware,
StateChangeMiddleware,
ToolOffloadMiddleware,
@@ -1085,6 +1088,7 @@ class ChatService:
# in-process retrigger plumbing is needed here.
# -------------------------------------------------------------
middlewares: list = [
+ SteeringMiddleware(self._message_bus),
InboxMiddleware(self._message_bus),
StateChangeMiddleware(
message_bus=self._message_bus,
@@ -1341,6 +1345,7 @@ class ChatService:
agent_id=agent_id,
)
reply_msg: Msg | None = None
+ active_reply_id: str | None = None
reply_msgs: list[Msg] = []
checkpoint_cursor: str | None = None
released = False
@@ -1399,6 +1404,23 @@ class ChatService:
elif reply_msg is not None:
reply_msg.append_event(event)
try:
+ if isinstance(event, ReplyStartEvent):
+ if (
+ active_reply_id is not None
+ and active_reply_id
+ != event.reply_id
+ ):
+ await finish_active_chat_reply(
+ self._message_bus,
+ session_id,
+ active_reply_id,
+ )
+ active_reply_id = event.reply_id
+ await register_active_chat_reply(
+ self._message_bus,
+ session_id,
+ event.reply_id,
+ )
checkpoint_cursor = (
await publish_session_event(
self._message_bus,
@@ -1427,6 +1449,7 @@ class ChatService:
else:
# Case B: continuation (UserConfirmResult
# / ExternalExecResult)
+ continuation_reply_id = agent.state.reply_id
reply_msg = await self._storage.get_message(
user_id,
session_id,
@@ -1445,44 +1468,69 @@ class ChatService:
elif input_msg:
reply_msg.append_event(input_msg)
- # Broadcast the applied decision so
- # observers that didn't make it (other tabs,
- # the channel card) close it.
- if isinstance(
- input_msg,
- (
- UserConfirmResultEvent,
- ExternalExecutionResultEvent,
- ),
- ):
+ try:
+ if (
+ active_reply_id is not None
+ and active_reply_id
+ != continuation_reply_id
+ ):
+ await finish_active_chat_reply(
+ self._message_bus,
+ session_id,
+ active_reply_id,
+ )
+ active_reply_id = continuation_reply_id
+ await register_active_chat_reply(
+ self._message_bus,
+ session_id,
+ continuation_reply_id,
+ )
+ # Broadcast the applied decision so
+ # observers that didn't make it (other tabs,
+ # the channel card) close it.
+ if isinstance(
+ input_msg,
+ (
+ UserConfirmResultEvent,
+ ExternalExecutionResultEvent,
+ ),
+ ):
+ checkpoint_cursor = (
+ await publish_session_event(
+ self._message_bus,
+ session_id,
+ input_msg.model_dump(mode="json"),
+ )
+ )
+
+ # Emit a synthetic REPLY_START so SSE clients
+ # can detect the continuation.
+ #
+ # IMPORTANT: The frontend SSE handler must
+ # NOT clear its accumulated message buffer
+ # upon receiving REPLY_START with the current
+ # reply_id. This signals a continuation (e.g.
+ # after an approval flow), not a fresh reply.
+ continuation_start = ReplyStartEvent(
+ session_id=session_id,
+ reply_id=continuation_reply_id,
+ name=agent_record.data.name,
+ )
checkpoint_cursor = (
await publish_session_event(
self._message_bus,
session_id,
- input_msg.model_dump(mode="json"),
+ continuation_start.model_dump(
+ mode="json",
+ ),
)
)
-
- # Emit a synthetic REPLY_START so SSE subscribers
- # (frontend, channel gateway) can detect the
- # continuation without requiring special handling.
- #
- # IMPORTANT: The frontend SSE handler must
- # NOT clear its accumulated message buffer
- # upon receiving a
- # REPLY_START with the same reply_id as the current
- # message. This event signals a continuation (e.g.
- # after an approval flow), not a fresh reply.
- continuation_start = ReplyStartEvent(
- session_id=session_id,
- reply_id=agent.state.reply_id,
- name=agent_record.data.name,
- )
- checkpoint_cursor = await publish_session_event(
- self._message_bus,
- session_id,
- continuation_start.model_dump(mode="json"),
- )
+ except asyncio.CancelledError:
+ # Resume the Agent so it closes pending tools
+ # and emits the interrupted terminal event.
+ current = asyncio.current_task()
+ if current is not None:
+ current.cancel()
async for event in agent.reply_stream(
inputs=input_msg,
@@ -1631,30 +1679,38 @@ class ChatService:
before_id=checkpoint_cursor,
)
finally:
- # A worker whose turn died never reached
- # ``TeamSay``. Sent from inside the shielded
- # write so an interrupt cannot drop it, and from
- # a ``finally`` so a storage failure cannot
- # either — the leader has to learn about the
- # dead turn even when recording it went wrong.
- # COMPLETED / EXCEED_MAX_ITERS stay silent:
- # those only escape the member middleware after
- # a successful report.
- for msg in reply_msgs:
- if msg.finished_reason in (
- ReplyFinishedReason.ERROR,
- ReplyFinishedReason.INTERRUPTED,
- ):
- await self._notify_leader_of_failure(
- user_id,
- team_ctx,
- worker_name,
- msg.finished_reason,
- msg.error.message
- if msg.error
- else "The turn stopped before it "
- "finished.",
+ try:
+ if active_reply_id is not None:
+ await finish_active_chat_reply(
+ self._message_bus,
+ session_id,
+ active_reply_id,
)
+ finally:
+ # A worker whose turn died never reached
+ # ``TeamSay``. Sent from inside the shielded
+ # write so an interrupt cannot drop it, and from
+ # a ``finally`` so a storage failure cannot
+ # either — the leader has to learn about the
+ # dead turn even when recording it went wrong.
+ # COMPLETED / EXCEED_MAX_ITERS stay silent:
+ # those only escape the member middleware after
+ # a successful report.
+ for msg in reply_msgs:
+ if msg.finished_reason in (
+ ReplyFinishedReason.ERROR,
+ ReplyFinishedReason.INTERRUPTED,
+ ):
+ await self._notify_leader_of_failure(
+ user_id,
+ team_ctx,
+ worker_name,
+ msg.finished_reason,
+ msg.error.message
+ if msg.error
+ else "The turn stopped before it "
+ "finished.",
+ )
persist_task = asyncio.create_task(_persist())
try:
diff --git a/src/agentscope/app/_service/_session.py b/src/agentscope/app/_service/_session.py
index 8c8c0b1e4..867f8fbe4 100644
--- a/src/agentscope/app/_service/_session.py
+++ b/src/agentscope/app/_service/_session.py
@@ -667,6 +667,10 @@ class SessionService:
await self._bus.queue_delete(
MessageBusKeys.chat_inputs(session_id),
)
+ await self._bus.registry_del(
+ MessageBusKeys.chat_active_reply_registry(),
+ session_id,
+ )
await self._bus.registry_del(
MessageBusKeys.chat_input_inflight_registry(),
session_id,
diff --git a/src/agentscope/app/message_bus/_base.py b/src/agentscope/app/message_bus/_base.py
index 8589df38f..a943d46b5 100644
--- a/src/agentscope/app/message_bus/_base.py
+++ b/src/agentscope/app/message_bus/_base.py
@@ -817,6 +817,10 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methods
MessageBusKeys.chat_input_inflight_registry(),
session_id,
)
+ await self.registry_del(
+ MessageBusKeys.chat_active_reply_registry(),
+ session_id,
+ )
await self.registry_drop(self._BG_TASKS_KEY.format(sid=session_id))
# Inbox -----------------------------------------------------------
diff --git a/src/agentscope/app/message_bus/_keys.py b/src/agentscope/app/message_bus/_keys.py
index e9623fa30..19c57a475 100644
--- a/src/agentscope/app/message_bus/_keys.py
+++ b/src/agentscope/app/message_bus/_keys.py
@@ -263,6 +263,7 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods
_CHAT_INPUT_MUTATION_LOCK = "agentscope:chat:inputs:mutation:{sid}"
_CHAT_INPUT_PENDING_REGISTRY = "agentscope:chat:pending"
_CHAT_INPUT_INFLIGHT_REGISTRY = "agentscope:chat:inflight"
+ _CHAT_ACTIVE_REPLY_REGISTRY = "agentscope:chat:active_reply"
_CHAT_INPUT_RECOVERY_LOCK = "agentscope:chat:recovery:lock"
_CHAT_INPUT_RECOVERY_STATE = "agentscope:chat:recovery:state"
_CHAT_INPUT_USER_QUOTA_LOCK = "agentscope:chat:quota:lock:{uid}"
@@ -368,6 +369,16 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods
"""
return cls._CHAT_INPUT_INFLIGHT_REGISTRY
+ @classmethod
+ def chat_active_reply_registry(cls) -> str:
+ """Return the registry containing each session's active reply id.
+
+ Returns:
+ `str`:
+ Global registry mapping session ids to active reply ids.
+ """
+ return cls._CHAT_ACTIVE_REPLY_REGISTRY
+
@classmethod
def chat_input_user_quota_lock(cls, user_id: str) -> str:
"""Return the per-user pending-turn quota mutex key.
diff --git a/src/agentscope/app/middleware/__init__.py b/src/agentscope/app/middleware/__init__.py
index 6f058d8f9..4888eaf96 100644
--- a/src/agentscope/app/middleware/__init__.py
+++ b/src/agentscope/app/middleware/__init__.py
@@ -2,6 +2,7 @@
"""The middlewares module."""
from ._inbox_middleware import InboxMiddleware
+from ._steering_middleware import SteeringMiddleware
from ._protocol import ProtocolMiddlewareBase, AGUIProtocolMiddleware
from ._sop_step_middleware import SOPStepSubmitMiddleware
from ._state_change_middleware import StateChangeMiddleware
@@ -11,6 +12,7 @@ from ._tool_offload_middleware import ToolOffloadMiddleware
__all__ = [
"InboxMiddleware",
+ "SteeringMiddleware",
"ProtocolMiddlewareBase",
"AGUIProtocolMiddleware",
"SOPStepSubmitMiddleware",
diff --git a/src/agentscope/app/middleware/_steering_middleware.py b/src/agentscope/app/middleware/_steering_middleware.py
new file mode 100644
index 000000000..4e5ec15d4
--- /dev/null
+++ b/src/agentscope/app/middleware/_steering_middleware.py
@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""Adapt the durable chat queue to SDK steering middleware."""
+from pydantic import TypeAdapter
+
+from .._bus_ops import (
+ acknowledge_steering_chat_inputs,
+ fail_steering_chat_input,
+ list_steering_chat_inputs,
+ publish_session_event,
+)
+from ..message_bus import MessageBus
+from ..._logging import logger
+from ...event import CustomEvent
+from ...message import Msg
+from ...middleware import (
+ SteeringInput,
+ SteeringMiddleware as SDKSteeringMiddleware,
+ SteeringSource,
+)
+
+_MESSAGE_INPUT_ADAPTER: TypeAdapter = TypeAdapter(Msg | list[Msg])
+
+
+class _ChatQueueSteeringSource(SteeringSource):
+ """Read reserved inputs; ChatService owns the active-reply lifecycle."""
+
+ def __init__(self, message_bus: MessageBus) -> None:
+ """Store the application's durable bus."""
+ self._bus = message_bus
+
+ async def read(
+ self,
+ session_id: str,
+ reply_id: str,
+ ) -> list[SteeringInput]:
+ """Hydrate reserved items, retaining invalid ones as failed."""
+ items = await list_steering_chat_inputs(
+ self._bus,
+ session_id,
+ reply_id,
+ )
+ inputs = []
+ for item in items:
+ try:
+ parsed = _MESSAGE_INPUT_ADAPTER.validate_python(item["input"])
+ except ValueError as exc:
+ error = f"The queued message could not be injected: {exc}"
+ await fail_steering_chat_input(
+ self._bus,
+ session_id,
+ reply_id,
+ item["id"],
+ error,
+ )
+ await self._notify(
+ session_id,
+ "chat_input_steer_failed",
+ item["id"],
+ self._message_ids(item["input"]),
+ error,
+ )
+ else:
+ inputs.append(
+ SteeringInput(
+ id=item["id"],
+ messages=parsed
+ if isinstance(parsed, list)
+ else [parsed],
+ ),
+ )
+ return inputs
+
+ async def acknowledge(
+ self,
+ session_id: str,
+ reply_id: str,
+ inputs: list[SteeringInput],
+ ) -> None:
+ """Remove injected inputs and publish the existing WebUI events."""
+ await acknowledge_steering_chat_inputs(
+ self._bus,
+ session_id,
+ reply_id,
+ [item.id for item in inputs],
+ )
+ for item in inputs:
+ await self._notify(
+ session_id,
+ "chat_input_injected",
+ item.id,
+ [message.id for message in item.messages],
+ )
+
+ async def reject(
+ self,
+ session_id: str,
+ reply_id: str,
+ item: SteeringInput,
+ error: str,
+ ) -> None:
+ """Keep unsupported content editable in the durable queue."""
+ await fail_steering_chat_input(
+ self._bus,
+ session_id,
+ reply_id,
+ item.id,
+ error,
+ )
+ await self._notify(
+ session_id,
+ "chat_input_steer_failed",
+ item.id,
+ [message.id for message in item.messages],
+ error,
+ )
+
+ async def _notify(
+ self,
+ session_id: str,
+ name: str,
+ item_id: str,
+ message_ids: list[str],
+ error: str | None = None,
+ ) -> None:
+ """Do not roll back a committed injection if notification fails."""
+ value: dict = {"queue_item_id": item_id, "message_ids": message_ids}
+ if error is not None:
+ value["message"] = error
+ try:
+ await publish_session_event(
+ self._bus,
+ session_id,
+ CustomEvent(name=name, value=value).model_dump(mode="json"),
+ )
+ except Exception:
+ logger.exception(
+ "Steering transition committed; notification failed for %s.",
+ item_id,
+ )
+
+ @staticmethod
+ def _message_ids(raw_input: object) -> list[str]:
+ """Extract available message ids from a malformed queued input."""
+ messages = raw_input if isinstance(raw_input, list) else [raw_input]
+ return [
+ str(message["id"])
+ for message in messages
+ if isinstance(message, dict) and message.get("id")
+ ]
+
+
+class SteeringMiddleware(SDKSteeringMiddleware):
+ """Use SDK steering with the application's queue and event protocol.
+
+ Args:
+ message_bus: Application message bus holding reserved chat inputs.
+ """
+
+ def __init__(self, message_bus: MessageBus) -> None:
+ """Preserve the service constructor and WebUI hint source."""
+ super().__init__(
+ _ChatQueueSteeringSource(message_bus),
+ hint_source="chat_input_steering",
+ )
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.py
index e2b7f11b6..6fafae112 100644
--- a/src/agentscope/middleware/__init__.py
+++ b/src/agentscope/middleware/__init__.py
@@ -12,6 +12,13 @@ from ._longterm_memory import (
from ._tracing import TracingMiddleware
from ._tts_middleware import TTSMiddleware
from ._model_router import ChatModelCandidate, ModelRouterMiddleware
+from ._steering import SteeringMiddleware
+from ._steering_queue import (
+ SteeringInput,
+ SteeringQueue,
+ SteeringReceipt,
+ SteeringSource,
+)
__all__ = [
"MiddlewareBase",
@@ -24,4 +31,9 @@ __all__ = [
"TTSMiddleware",
"ChatModelCandidate",
"ModelRouterMiddleware",
+ "SteeringInput",
+ "SteeringMiddleware",
+ "SteeringQueue",
+ "SteeringReceipt",
+ "SteeringSource",
]
diff --git a/src/agentscope/middleware/_steering.py b/src/agentscope/middleware/_steering.py
new file mode 100644
index 000000000..f0ec49b02
--- /dev/null
+++ b/src/agentscope/middleware/_steering.py
@@ -0,0 +1,264 @@
+# -*- coding: utf-8 -*-
+"""Inject steering inputs at normal Agent reasoning boundaries."""
+import asyncio
+from contextlib import aclosing
+from typing import Any, AsyncGenerator, Callable, TYPE_CHECKING
+
+from ._base import MiddlewareBase
+from ._steering_queue import SteeringInput, SteeringSource
+from ..event import (
+ ExternalExecutionResultEvent,
+ HintBlockEvent,
+ ReplyStartEvent,
+ UserConfirmResultEvent,
+)
+from ..message import AssistantMsg, DataBlock, HintBlock, Msg, TextBlock
+
+if TYPE_CHECKING:
+ from ..agent import Agent
+
+
+class SteeringMiddleware(MiddlewareBase):
+ """Guide active replies without interrupting model or tool calls.
+
+ Args:
+ source: Reply-scoped source of pending steering inputs.
+ hint_source: Source label attached to injected hint blocks.
+
+ The source is checked before reasoning and after a text-only response.
+ A new input can suppress that response's final candidate; the Agent then
+ performs another normal iteration, including compression and budgeting.
+ Inputs received during tools wait until the next reasoning call.
+ """
+
+ def __init__(
+ self,
+ source: SteeringSource,
+ *,
+ hint_source: str = "steering",
+ ) -> None:
+ """Store the input source and the hint event label."""
+ self._source = source
+ self._hint_source = hint_source
+
+ async def on_reply(
+ self,
+ agent: "Agent",
+ input_kwargs: dict,
+ next_handler: Callable[..., AsyncGenerator],
+ ) -> AsyncGenerator[Any, None]:
+ """Open and close input windows across reply and resume lifecycles."""
+ session_id = agent.state.session_id
+ active_reply_id: str | None = None
+ try:
+ if isinstance(
+ input_kwargs.get("inputs"),
+ (UserConfirmResultEvent, ExternalExecutionResultEvent),
+ ):
+ await self._source.start_reply(
+ session_id,
+ agent.state.reply_id,
+ )
+ active_reply_id = agent.state.reply_id
+ async with aclosing(next_handler(**input_kwargs)) as stream:
+ async for event in stream:
+ if isinstance(event, ReplyStartEvent):
+ if active_reply_id is not None:
+ await self._source.finish_reply(
+ session_id,
+ active_reply_id,
+ )
+ await self._source.start_reply(
+ session_id,
+ event.reply_id,
+ )
+ active_reply_id = event.reply_id
+ yield event
+ finally:
+ # Another middleware may swallow ReplyEndEvent to continue.
+ # Close when the invocation actually exits, not at that event.
+ if active_reply_id is not None:
+ await self._source.finish_reply(session_id, active_reply_id)
+
+ async def on_reasoning(
+ self,
+ agent: "Agent",
+ input_kwargs: dict,
+ next_handler: Callable[..., AsyncGenerator],
+ ) -> AsyncGenerator[Any, None]:
+ """Run one model call, yielding continuation control to the Agent."""
+ consumed = False
+ async for event in self._consume(agent):
+ consumed = True
+ yield event
+ if consumed:
+ # The Agent checked context before entering reasoning. Include
+ # newly injected text and attachments before calling the model.
+ await agent.compress_context()
+
+ terminal_messages: list[Msg] = []
+ async for event in next_handler(**input_kwargs):
+ if isinstance(event, Msg):
+ terminal_messages.append(event)
+ else:
+ yield event
+
+ # The forced finalization call must still be allowed to terminate.
+ # Its late inputs stay pending and become unconsumed at reply end.
+ if (
+ terminal_messages
+ and agent.state.cur_iter < agent.react_config.max_iters
+ ):
+ consumed = False
+ async for event in self._consume(agent):
+ consumed = True
+ yield event
+ if consumed:
+ return
+
+ for message in terminal_messages:
+ yield message
+
+ async def _consume(
+ self,
+ agent: "Agent",
+ ) -> AsyncGenerator[HintBlockEvent, None]:
+ """Validate inputs and acknowledge only a successful context append."""
+ session_id = agent.state.session_id
+ reply_id = agent.state.reply_id
+ items = await self._source.read(session_id, reply_id)
+ prepared: list[SteeringInput] = []
+ hints: list[HintBlock] = []
+ for item in items:
+ try:
+ item_hints = self._to_hints(item.id, item.messages)
+ except ValueError as exc:
+ await self._source.reject(
+ session_id,
+ reply_id,
+ item,
+ f"The steering input could not be injected: {exc}",
+ )
+ else:
+ prepared.append(item)
+ hints.extend(item_hints)
+ if not prepared:
+ return
+
+ rollback = self._append_hints(agent, hints)
+ acknowledgement = asyncio.create_task(
+ self._source.acknowledge(session_id, reply_id, prepared),
+ )
+ cancellation: asyncio.CancelledError | None = None
+ # Cancellation is not evidence that acknowledgement failed: the
+ # source may already have removed the inputs. Resolve its outcome
+ # before either rolling back or allowing reply persistence to run.
+ while not acknowledgement.done():
+ try:
+ await asyncio.shield(acknowledgement)
+ except asyncio.CancelledError as exc:
+ if cancellation is None:
+ cancellation = exc
+ except Exception:
+ break
+ try:
+ acknowledgement.result()
+ except BaseException as exc:
+ rollback()
+ if cancellation is not None:
+ raise cancellation from exc
+ raise
+ # Project every committed hint before propagating cancellation. The
+ # service persists replies built from events, not the agent context.
+ for hint in hints:
+ yield HintBlockEvent(
+ reply_id=reply_id,
+ block_id=hint.id,
+ source=hint.source,
+ hint=hint.hint,
+ )
+ # Receive any further cancellation redirected by the event consumer
+ # before the Agent leaves reasoning and starts interruption cleanup.
+ try:
+ await asyncio.sleep(0)
+ except asyncio.CancelledError as exc:
+ if cancellation is None:
+ cancellation = exc
+ if cancellation is not None:
+ raise cancellation
+
+ def _to_hints(self, item_id: str, messages: list[Msg]) -> list[HintBlock]:
+ """Convert one steering input into correlated multimodal hints.
+
+ Args:
+ item_id (`str`):
+ Source input identifier used to derive stable block ids.
+ messages (`list[Msg]`):
+ Parsed messages carried by the steering input.
+
+ Returns:
+ `list[HintBlock]`:
+ One hint per message, preserving text and data blocks.
+
+ Raises:
+ `ValueError`:
+ A message is empty or contains a block unsupported by hints.
+ """
+ if not messages:
+ raise ValueError("Steering requires at least one message.")
+ hints: list[HintBlock] = []
+ for index, message in enumerate(messages):
+ content = [
+ block
+ for block in message.content
+ if isinstance(block, (TextBlock, DataBlock))
+ ]
+ if not content or len(content) != len(message.content):
+ raise ValueError(
+ f"Message '{message.id}' contains unsupported content.",
+ )
+ hints.append(
+ HintBlock(
+ id=f"{item_id}:{index}",
+ hint=content,
+ source=self._hint_source,
+ ),
+ )
+ return hints
+
+ @staticmethod
+ def _append_hints(
+ agent: "Agent",
+ hints: list[HintBlock],
+ ) -> Callable[[], None]:
+ """Append hints synchronously and return an exact rollback callback."""
+ if agent.state.context:
+ last_message = agent.state.context[-1]
+ if (
+ last_message.role == "assistant"
+ and last_message.name == agent.name
+ and last_message.id == agent.state.reply_id
+ ):
+ original_length = len(last_message.content)
+ last_message.content.extend(hints)
+
+ def rollback_extension() -> None:
+ del last_message.content[original_length:]
+
+ return rollback_extension
+
+ injected_message = AssistantMsg(
+ id=agent.state.reply_id,
+ name=agent.name,
+ content=list(hints),
+ )
+ agent.state.context.append(injected_message)
+
+ def rollback_message() -> None:
+ if (
+ agent.state.context
+ and agent.state.context[-1] is injected_message
+ ):
+ agent.state.context.pop()
+
+ return rollback_message
diff --git a/src/agentscope/middleware/_steering_queue.py b/src/agentscope/middleware/_steering_queue.py
new file mode 100644
index 000000000..f647e5c98
--- /dev/null
+++ b/src/agentscope/middleware/_steering_queue.py
@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+"""Input sources and receipts for cooperative reply steering."""
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .._utils._common import _generate_id
+from ..message import Msg
+
+
+@dataclass(frozen=True)
+class SteeringInput:
+ """One ordered steering input with a source-owned identifier.
+
+ Args:
+ id: Identifier used to acknowledge or reject this input.
+ messages: Messages whose text and data blocks guide the reply.
+ """
+
+ id: str
+ messages: list[Msg]
+
+
+class SteeringSource(ABC):
+ """Supply reply-scoped inputs without coupling agents to a transport.
+
+ Reads must be non-destructive. Acknowledgement removes only the supplied
+ inputs and must raise before committing if it cannot accept the change.
+ The middleware waits for acknowledgement in a shielded task, including
+ when its caller is repeatedly cancelled. Sources must finish committing
+ before returning and must not report post-commit cleanup or notification
+ failures as acknowledgement failures. Cancellation is propagated only
+ after the middleware has resolved whether to retain or roll back hints.
+ Committed hint events are yielded before cancellation is propagated so
+ event consumers can persist the same inputs as the agent context.
+ Lifecycle hooks are optional for externally managed sources.
+ """
+
+ async def start_reply(self, session_id: str, reply_id: str) -> None:
+ """Open an input window when a reply starts or resumes."""
+
+ async def finish_reply(self, session_id: str, reply_id: str) -> None:
+ """Close an input window and settle its unconsumed inputs."""
+
+ @abstractmethod
+ async def read(
+ self,
+ session_id: str,
+ reply_id: str,
+ ) -> list[SteeringInput]:
+ """Read pending inputs for this reply in arrival order."""
+
+ @abstractmethod
+ async def acknowledge(
+ self,
+ session_id: str,
+ reply_id: str,
+ inputs: list[SteeringInput],
+ ) -> None:
+ """Acknowledge inputs appended to context without consuming others."""
+
+ @abstractmethod
+ async def reject(
+ self,
+ session_id: str,
+ reply_id: str,
+ item: SteeringInput,
+ error: str,
+ ) -> None:
+ """Record an input that cannot be injected into context."""
+
+
+@dataclass
+class SteeringReceipt:
+ """Track acceptance separately from context injection.
+
+ Args:
+ id: Identifier assigned to the accepted input.
+
+ Attributes:
+ status: Pending, injected, unconsumed or failed. Injection means the
+ input reached context, not that a model followed the instruction.
+ error: Validation error for a failed input, otherwise None.
+ """
+
+ id: str
+ status: Literal["pending", "injected", "unconsumed", "failed"] = field(
+ default="pending",
+ init=False,
+ )
+ error: str | None = field(default=None, init=False)
+ _done: asyncio.Event = field(
+ default_factory=asyncio.Event,
+ init=False,
+ repr=False,
+ )
+
+ async def wait(self) -> str:
+ """Wait for a terminal status; cancelling this wait keeps delivery."""
+ await self._done.wait()
+ return self.status
+
+ def _finish(
+ self,
+ status: Literal["injected", "unconsumed", "failed"],
+ error: str | None = None,
+ ) -> None:
+ """Settle a receipt after its input leaves the source."""
+ self.status = status
+ self.error = error
+ self._done.set()
+
+
+# Receipts are settled only by their owning queue.
+# pylint: disable=protected-access
+class SteeringQueue(SteeringSource):
+ """An in-process source used on the same event loop as the agent.
+
+ Attach it to a SteeringMiddleware, then submit after ReplyStartEvent.
+ The queue is not persistent or thread-safe. A reply that ends or parks
+ leaves unconsumed inputs with the caller rather than starting a new turn.
+ """
+
+ def __init__(self) -> None:
+ """Initialize isolated input windows for active replies."""
+ self._pending: dict[
+ tuple[str, str],
+ dict[str, tuple[SteeringInput, SteeringReceipt]],
+ ] = {}
+
+ def submit(
+ self,
+ inputs: Msg | list[Msg],
+ *,
+ session_id: str,
+ reply_id: str,
+ ) -> SteeringReceipt:
+ """Accept copied messages for an active reply without waiting.
+
+ Args:
+ inputs: One message or a non-empty list of messages.
+ session_id: Session of the active reply.
+ reply_id: Reply observed by the caller.
+
+ Returns:
+ A receipt that can be awaited with its wait method.
+
+ Raises:
+ ValueError: The reply is inactive or the message list is empty.
+ """
+ key = (session_id, reply_id)
+ if key not in self._pending:
+ raise ValueError(f"Reply '{reply_id}' is not accepting steering.")
+ messages = inputs if isinstance(inputs, list) else [inputs]
+ if not messages:
+ raise ValueError("Steering requires at least one message.")
+ item = SteeringInput(
+ id=_generate_id(),
+ messages=[message.model_copy(deep=True) for message in messages],
+ )
+ receipt = SteeringReceipt(item.id)
+ self._pending[key][item.id] = (item, receipt)
+ return receipt
+
+ async def start_reply(self, session_id: str, reply_id: str) -> None:
+ """Open a reply window, rejecting overlapping uses of its identity."""
+ key = (session_id, reply_id)
+ if key in self._pending:
+ raise ValueError(f"Reply '{reply_id}' is already accepting input.")
+ self._pending[key] = {}
+
+ async def finish_reply(self, session_id: str, reply_id: str) -> None:
+ """Return all remaining inputs to their callers as unconsumed."""
+ for _, receipt in self._pending.pop(
+ (session_id, reply_id),
+ {},
+ ).values():
+ receipt._finish("unconsumed")
+
+ async def read(
+ self,
+ session_id: str,
+ reply_id: str,
+ ) -> list[SteeringInput]:
+ """Return pending inputs without transferring ownership."""
+ pending = self._pending.get((session_id, reply_id), {})
+ return [item for item, _ in pending.values()]
+
+ async def acknowledge(
+ self,
+ session_id: str,
+ reply_id: str,
+ inputs: list[SteeringInput],
+ ) -> None:
+ """Settle the specified inputs after context injection."""
+ pending = self._pending.get((session_id, reply_id), {})
+ if any(item.id not in pending for item in inputs):
+ raise LookupError("The steering inputs are no longer pending.")
+ for item in inputs:
+ _, receipt = pending.pop(item.id)
+ receipt._finish("injected")
+
+ async def reject(
+ self,
+ session_id: str,
+ reply_id: str,
+ item: SteeringInput,
+ error: str,
+ ) -> None:
+ """Settle one invalid input without affecting other pending inputs."""
+ pending = self._pending.get((session_id, reply_id), {})
+ entry = pending.pop(item.id, None)
+ if entry is not None:
+ entry[1]._finish("failed", error)
diff --git a/tests/service_steering_middleware_test.py b/tests/service_steering_middleware_test.py
new file mode 100644
index 000000000..e258e2062
--- /dev/null
+++ b/tests/service_steering_middleware_test.py
@@ -0,0 +1,1014 @@
+# -*- coding: utf-8 -*-
+"""Tests for queued-message steering state and reasoning boundaries."""
+import asyncio
+import json
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, patch
+
+import fakeredis.aioredis
+
+from agentscope.app import _bus_ops
+from agentscope.app._bus_ops import (
+ ChatSteeringUnavailableError,
+ acknowledge_steering_chat_inputs,
+ enqueue_chat_input,
+ fail_steering_chat_input,
+ finish_active_chat_reply,
+ list_chat_inputs,
+ register_active_chat_reply,
+ steer_chat_input,
+)
+from agentscope.app.message_bus import (
+ InMemoryMessageBus,
+ MessageBus,
+ MessageBusKeys,
+ RedisMessageBus,
+)
+from agentscope.app.middleware import SteeringMiddleware
+from agentscope.app.middleware import _steering_middleware as _steering_adapter
+from agentscope.event import HintBlockEvent
+from agentscope.message import (
+ AssistantMsg,
+ HintBlock,
+ Msg,
+ ToolCallBlock,
+ UserMsg,
+)
+
+_STEERING_HINT_SOURCE = "chat_input_steering"
+
+
+def _make_agent() -> SimpleNamespace:
+ """Build the state shape used by SteeringMiddleware."""
+ return SimpleNamespace(
+ name="agent",
+ state=SimpleNamespace(
+ session_id="session",
+ reply_id="reply",
+ cur_iter=0,
+ context=[UserMsg(name="user", content="initial")],
+ ),
+ react_config=SimpleNamespace(max_iters=10),
+ compress_context=AsyncMock(),
+ )
+
+
+async def _collect(generator: AsyncGenerator) -> list:
+ """Collect one asynchronous event generator."""
+ return [event async for event in generator]
+
+
+def _without_timestamps(value: Any) -> Any:
+ """Remove volatile timestamps while retaining the complete structure."""
+ if isinstance(value, dict):
+ return {
+ key: _without_timestamps(item)
+ for key, item in value.items()
+ if key not in {"created_at", "finished_at"}
+ }
+ if isinstance(value, list):
+ return [_without_timestamps(item) for item in value]
+ return value
+
+
+def _message_structures(messages: list[Msg]) -> list[dict]:
+ """Serialize complete messages without volatile timestamps."""
+ return [
+ _without_timestamps(message.model_dump(mode="json"))
+ for message in messages
+ ]
+
+
+def _hint_event_structure(event: HintBlockEvent) -> dict:
+ """Serialize a complete hint event without generated identity fields."""
+ payload = _without_timestamps(event.model_dump(mode="json"))
+ payload.pop("id")
+ return payload
+
+
+def _expected_hint_message(item_id: str, message: Msg) -> Msg:
+ """Build the current-reply context message for one steered input."""
+ return AssistantMsg(
+ id="reply",
+ name="agent",
+ content=[
+ HintBlock(
+ id=f"{item_id}:0",
+ source=_STEERING_HINT_SOURCE,
+ hint=list(message.content),
+ ),
+ ],
+ )
+
+
+def _expected_hint_event(item_id: str, message: Msg) -> dict:
+ """Build the stable complete event structure for one steering hint."""
+ return _hint_event_structure(
+ HintBlockEvent(
+ reply_id="reply",
+ block_id=f"{item_id}:0",
+ source=_STEERING_HINT_SOURCE,
+ hint=list(message.content),
+ ),
+ )
+
+
+async def _custom_events(bus: MessageBus) -> list[dict]:
+ """Read complete custom events without generated identity fields."""
+ entries = await bus.log_read(MessageBusKeys.session_events("session"))
+ events: list[dict] = []
+ for _entry_id, payload in entries:
+ if payload.get("type") != "CUSTOM":
+ continue
+ stable = _without_timestamps(payload)
+ stable.pop("id")
+ events.append(stable)
+ return events
+
+
+@asynccontextmanager
+async def _cancellation_bus(backend: str) -> AsyncGenerator[MessageBus, None]:
+ """Exercise the same cancellation boundaries with both bus backends."""
+ if backend == "memory":
+ async with InMemoryMessageBus() as bus:
+ yield bus
+ else:
+ redis = fakeredis.aioredis.FakeRedis(decode_responses=True)
+ try:
+ redis_bus = RedisMessageBus()
+ with patch.object(redis_bus, "_client", redis):
+ yield redis_bus
+ finally:
+ await redis.aclose()
+
+
+class TestSteeringCancellation(IsolatedAsyncioTestCase):
+ """Cancellation must not undo context after the queue commit."""
+
+ async def test_cancellation_waits_for_acknowledgement_outcome(
+ self,
+ ) -> None:
+ """Persist only after commit resolution, even on repeated Stop."""
+ for backend in ("memory", "redis"):
+ for boundary in (
+ "before_commit",
+ "before_commit_failure",
+ "commit_response",
+ "payload_cleanup",
+ "queue_notification",
+ "injection_notification",
+ ):
+ for cancellations in (1, 3):
+ with self.subTest(
+ backend=backend,
+ boundary=boundary,
+ cancellations=cancellations,
+ ):
+ async with _cancellation_bus(backend) as bus:
+ await self._check_cancellation(
+ bus,
+ boundary,
+ cancellations,
+ )
+
+ async def _check_cancellation(
+ self,
+ bus: MessageBus,
+ boundary: str,
+ cancellations: int,
+ ) -> None:
+ """Cancel at a controlled await, then release its actual outcome."""
+ agent = _make_agent()
+ initial = agent.state.context[0]
+ messages = [
+ UserMsg("user", text) for text in ("first", "guide", "last")
+ ]
+ items = [
+ await enqueue_chat_input(bus, "user", "session", "agent", msg)
+ for msg in messages
+ ]
+ entered = asyncio.Event()
+ release = asyncio.Event()
+ ack_cancelled = asyncio.Event()
+ finished = asyncio.Event()
+ persisted: list = []
+ restored: list = []
+ model_calls: list = []
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ model_calls.append("called")
+ yield AssistantMsg(id="reply", name="agent", content="unused")
+
+ async def run() -> None:
+ try:
+ await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+ finally:
+ persisted.extend(_message_structures(agent.state.context))
+ restored.extend(
+ await finish_active_chat_reply(bus, "session", "reply"),
+ )
+ finished.set()
+
+ target: Any
+ if boundary in (
+ "before_commit",
+ "before_commit_failure",
+ "commit_response",
+ ):
+ target, operation = bus, "queue_replace"
+ elif boundary == "payload_cleanup":
+ target, operation = _bus_ops, "discard_input"
+ elif boundary == "queue_notification":
+ target, operation = _bus_ops, "_notify_chat_queue_changed"
+ else:
+ target, operation = _steering_adapter, "publish_session_event"
+
+ original = getattr(target, operation)
+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ items[1]["id"],
+ "reply",
+ )
+ with patch.object(target, operation) as mocked:
+
+ async def blocked(*args: Any, **kwargs: Any) -> Any:
+ if entered.is_set():
+ return await original(*args, **kwargs)
+ result = None
+ if boundary == "commit_response":
+ result = await original(*args, **kwargs)
+ entered.set()
+ try:
+ await release.wait()
+ except asyncio.CancelledError:
+ ack_cancelled.set()
+ raise
+ if boundary == "before_commit_failure":
+ raise RuntimeError("commit rejected")
+ if boundary == "commit_response":
+ return result
+ return await original(*args, **kwargs)
+
+ mocked.side_effect = blocked
+ task = asyncio.create_task(run())
+ try:
+ await asyncio.wait_for(entered.wait(), timeout=2)
+ for _ in range(cancellations):
+ task.cancel("stop")
+ await asyncio.sleep(0)
+ self.assertFalse(ack_cancelled.is_set())
+ self.assertFalse(finished.is_set())
+ finally:
+ release.set()
+ with self.assertRaises(asyncio.CancelledError) as raised:
+ await asyncio.wait_for(task, timeout=2)
+ self.assertEqual(raised.exception.args, ("stop",))
+
+ rejected = boundary == "before_commit_failure"
+ expected_context = [initial]
+ if not rejected:
+ expected_context.append(
+ _expected_hint_message(items[1]["id"], messages[1]),
+ )
+ self.assertEqual(persisted, _message_structures(expected_context))
+ self.assertEqual(_message_structures(agent.state.context), persisted)
+ self.assertEqual(model_calls, [])
+ self.assertEqual(restored, [items[1]["id"]] if rejected else [])
+ self.assertEqual(
+ await list_chat_inputs(bus, "session"),
+ items if rejected else [items[0], items[2]],
+ )
+ remaining = items if rejected else [items[0], items[2]]
+ self.assertEqual(
+ await bus.registry_getall(
+ MessageBusKeys.chat_input_payloads("session"),
+ ),
+ {item["id"]: json.dumps(item["input"]) for item in remaining},
+ )
+ self.assertEqual(
+ await _custom_events(bus),
+ []
+ if rejected
+ else [
+ {
+ "metadata": {},
+ "type": "CUSTOM",
+ "name": "chat_input_injected",
+ "value": {
+ "queue_item_id": items[1]["id"],
+ "message_ids": [messages[1].id],
+ },
+ },
+ ],
+ )
+
+
+class TestSteeringQueueState(IsolatedAsyncioTestCase):
+ """Queue reservations remain durable until injection or fallback."""
+
+ async def test_steering_preserves_reference_storage(self) -> None:
+ """Steer, failure and fallback keep payloads out of the FIFO."""
+ bus = InMemoryMessageBus()
+ message = UserMsg(name="user", content="guide")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ message,
+ )
+ expected = {
+ "id": item["id"],
+ "user_id": "user",
+ "session_id": "session",
+ "agent_id": "agent",
+ "created_at": item["created_at"],
+ "input_ref": item["id"],
+ "state": "queued",
+ }
+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):
+ await register_active_chat_reply(bus, "session", "reply")
+ for transition in ("steer", "fail", "steer", "finish"):
+ with self.subTest(transition=transition):
+ if transition == "steer":
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ expected["state"] = "steering"
+ expected["target_reply_id"] = "reply"
+ expected.pop("error", None)
+ elif transition == "fail":
+ await fail_steering_chat_input(
+ bus,
+ "session",
+ "reply",
+ item["id"],
+ "invalid",
+ )
+ expected["state"] = "failed"
+ expected["error"] = "invalid"
+ expected.pop("target_reply_id")
+ else:
+ await finish_active_chat_reply(bus, "session", "reply")
+ expected["state"] = "queued"
+ expected.pop("target_reply_id")
+ entries = await bus.queue_read(
+ MessageBusKeys.chat_inputs("session"),
+ )
+ self.assertEqual(
+ [entry for _, entry in entries],
+ [expected],
+ )
+ self.assertEqual(
+ await bus.registry_getall(
+ MessageBusKeys.chat_input_payloads("session"),
+ ),
+ {
+ item["id"]: json.dumps(
+ message.model_dump(mode="json"),
+ ),
+ },
+ )
+
+ async def test_notification_failure_keeps_steering_committed(self) -> None:
+ """A failed broadcast cannot reject reservation or acknowledgement."""
+ bus = InMemoryMessageBus()
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg("user", "guide"),
+ )
+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):
+ await register_active_chat_reply(bus, "session", "reply")
+ with patch.object(
+ _bus_ops,
+ "_publish_chat_queue_changed",
+ side_effect=ConnectionError("offline"),
+ ):
+ reserved = await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ self.assertEqual(reserved, [{**item, "state": "steering"}])
+ removed = await acknowledge_steering_chat_inputs(
+ bus,
+ "session",
+ "reply",
+ [item["id"]],
+ )
+ self.assertEqual(removed, reserved)
+ self.assertEqual(await list_chat_inputs(bus, "session"), [])
+ self.assertEqual(
+ await bus.registry_getall(
+ MessageBusKeys.chat_input_payloads("session"),
+ ),
+ {},
+ )
+
+ async def test_reserve_is_idempotent_and_finish_restores(self) -> None:
+ """Repeated Steer targets once and ReplyEnd restores deferred send."""
+ bus = InMemoryMessageBus()
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg(name="user", content="guide"),
+ )
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ first = await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ second = await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ steering_item = {
+ **item,
+ "state": "steering",
+ "error": None,
+ }
+ self.assertEqual(first, [steering_item])
+ self.assertEqual(second, [steering_item])
+
+ restored = await finish_active_chat_reply(
+ bus,
+ "session",
+ "reply",
+ )
+ self.assertEqual(restored, [item["id"]])
+
+ self.assertEqual(await list_chat_inputs(bus, "session"), [item])
+
+ async def test_acknowledge_non_head_preserves_other_items(self) -> None:
+ """Injecting one selected item never changes other FIFO entries."""
+ bus = InMemoryMessageBus()
+ first = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg(name="user", content="first"),
+ )
+ selected = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg(name="user", content="selected"),
+ )
+ third = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg(name="user", content="third"),
+ )
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ selected["id"],
+ "reply",
+ )
+ removed = await acknowledge_steering_chat_inputs(
+ bus,
+ "session",
+ "reply",
+ [selected["id"]],
+ )
+ self.assertEqual(
+ removed,
+ [
+ {
+ **selected,
+ "state": "steering",
+ "error": None,
+ },
+ ],
+ )
+
+ self.assertEqual(
+ await list_chat_inputs(bus, "session"),
+ [first, third],
+ )
+ self.assertEqual(
+ await bus.registry_getall(
+ MessageBusKeys.chat_input_payloads("session"),
+ ),
+ {
+ first["id"]: json.dumps(first["input"]),
+ third["id"]: json.dumps(third["input"]),
+ },
+ )
+
+ async def test_stale_reply_is_rejected_without_changing_item(self) -> None:
+ """A client reply id must match the server-side active registry."""
+ bus = InMemoryMessageBus()
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ UserMsg(name="user", content="guide"),
+ )
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "current")
+ with self.assertRaises(ChatSteeringUnavailableError):
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "stale",
+ )
+
+ self.assertEqual(await list_chat_inputs(bus, "session"), [item])
+
+
+class TestSteeringMiddleware(IsolatedAsyncioTestCase):
+ """Steering is consumed before or after a model call as needed."""
+
+ async def test_injection_notification_failure_keeps_committed_hint(
+ self,
+ ) -> None:
+ """A failed terminal event cannot roll back an acknowledged hint."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ message = UserMsg("user", "guide")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ message,
+ )
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ yield AssistantMsg(id="reply", name="agent", content="done")
+
+ async with bus.acquire_lock(MessageBusKeys.session_lock("session")):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ with patch(
+ "agentscope.app.middleware._steering_middleware."
+ "publish_session_event",
+ side_effect=ConnectionError("offline"),
+ ):
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+ self.assertEqual(await list_chat_inputs(bus, "session"), [])
+ self.assertEqual(
+ _message_structures(agent.state.context[1:]),
+ _message_structures([_expected_hint_message(item["id"], message)]),
+ )
+ self.assertEqual(
+ [
+ _hint_event_structure(event)
+ for event in events
+ if isinstance(event, HintBlockEvent)
+ ],
+ [_expected_hint_event(item["id"], message)],
+ )
+
+ async def test_pre_call_steering_reaches_one_model_call(self) -> None:
+ """An already reserved item is visible to the immediate model call."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ initial = agent.state.context[0]
+ guide = UserMsg(name="user", content="guide")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ guide,
+ )
+ calls = 0
+ response = AssistantMsg(
+ id="reply",
+ name="agent",
+ content="done",
+ )
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ nonlocal calls
+ calls += 1
+ self.assertEqual(
+ _message_structures(agent.state.context),
+ _message_structures(
+ [initial, _expected_hint_message(item["id"], guide)],
+ ),
+ )
+ agent.state.context.append(response)
+ yield response
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+
+ self.assertEqual(calls, 1)
+ self.assertEqual(
+ [
+ _hint_event_structure(event)
+ if isinstance(event, HintBlockEvent)
+ else event
+ for event in events
+ ],
+ [_expected_hint_event(item["id"], guide), response],
+ )
+ self.assertEqual(await list_chat_inputs(bus, "session"), [])
+
+ async def test_hint_does_not_attach_to_previous_reply(self) -> None:
+ """A same-agent tail from an older reply remains unchanged."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ previous = AssistantMsg(
+ id="previous-reply",
+ name="agent",
+ content="previous response",
+ )
+ agent.state.context = [previous]
+ guide = UserMsg(name="user", content="guide current reply")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ guide,
+ )
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ self.assertEqual(
+ _message_structures(agent.state.context),
+ _message_structures(
+ [
+ previous,
+ _expected_hint_message(item["id"], guide),
+ ],
+ ),
+ )
+ yield AssistantMsg(id="reply", name="agent", content="done")
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+
+ self.assertEqual(
+ _message_structures(agent.state.context),
+ _message_structures(
+ [previous, _expected_hint_message(item["id"], guide)],
+ ),
+ )
+
+ async def test_post_call_steering_continues_model_only_reply(self) -> None:
+ """A mid-stream steer yields continuation to the Agent's next round."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ guide = UserMsg(name="user", content="new direction")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ guide,
+ )
+ calls = 0
+ responses: list[Msg] = []
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ nonlocal calls
+ calls += 1
+ response = AssistantMsg(
+ id="reply",
+ name="agent",
+ content=f"response {calls}",
+ )
+ responses.append(response)
+ agent.state.context.append(response)
+ if calls == 1:
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ yield response
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+ self.assertEqual(calls, 1)
+ self.assertEqual(
+ [event for event in events if isinstance(event, Msg)],
+ [],
+ )
+ events.extend(
+ await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ ),
+ )
+
+ self.assertEqual(calls, 2)
+ self.assertEqual(
+ [
+ _hint_event_structure(event)
+ if isinstance(event, HintBlockEvent)
+ else event
+ for event in events
+ ],
+ [_expected_hint_event(item["id"], guide), responses[1]],
+ )
+ self.assertEqual(
+ await _custom_events(bus),
+ [
+ {
+ "metadata": {},
+ "type": "CUSTOM",
+ "name": "chat_input_injected",
+ "value": {
+ "queue_item_id": item["id"],
+ "message_ids": [guide.id],
+ },
+ },
+ ],
+ )
+
+ async def test_post_call_tool_path_does_not_repeat_reasoning(self) -> None:
+ """A tool-bound response leaves steering for the next reasoning."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ initial = agent.state.context[0]
+ guide = UserMsg(name="user", content="guide after tool")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ guide,
+ )
+ calls = 0
+
+ async def tool_model_call(**_kwargs: object) -> AsyncGenerator:
+ nonlocal calls
+ calls += 1
+ agent.state.context.append(
+ AssistantMsg(
+ id="reply",
+ name="agent",
+ content=[
+ ToolCallBlock(
+ id="tool",
+ name="work",
+ input="{}",
+ ),
+ ],
+ ),
+ )
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ return
+ yield # pragma: no cover
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ tool_model_call,
+ ),
+ )
+ self.assertEqual(events, [])
+
+ async def after_tool(**_kwargs: object) -> AsyncGenerator:
+ yield AssistantMsg(id="reply", name="agent", content="done")
+
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(agent, {}, after_tool),
+ )
+
+ self.assertEqual(calls, 1)
+ self.assertEqual(
+ [
+ _hint_event_structure(event)
+ for event in events
+ if isinstance(event, HintBlockEvent)
+ ],
+ [_expected_hint_event(item["id"], guide)],
+ )
+ expected_tool_message = AssistantMsg(
+ id="reply",
+ name="agent",
+ content=[
+ ToolCallBlock(id="tool", name="work", input="{}"),
+ _expected_hint_message(item["id"], guide).content[0],
+ ],
+ )
+ self.assertEqual(
+ _message_structures(agent.state.context),
+ _message_structures([initial, expected_tool_message]),
+ )
+
+ async def test_unsupported_content_stays_failed_in_queue(self) -> None:
+ """Preparation failures remain visible and never discard the item."""
+ bus = InMemoryMessageBus()
+ agent = _make_agent()
+ original = UserMsg(name="user", content="will be corrupted")
+ item = await enqueue_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ original,
+ )
+ await bus.registry_set(
+ MessageBusKeys.chat_input_payloads("session"),
+ item["id"],
+ json.dumps({"invalid": "message"}),
+ )
+
+ async def model_call(**_kwargs: object) -> AsyncGenerator:
+ response = AssistantMsg(
+ id="reply",
+ name="agent",
+ content="done",
+ )
+ agent.state.context.append(response)
+ yield response
+
+ async with bus.acquire_lock(
+ MessageBusKeys.session_lock("session"),
+ ttl_secs=60,
+ ):
+ await register_active_chat_reply(bus, "session", "reply")
+ await steer_chat_input(
+ bus,
+ "user",
+ "session",
+ "agent",
+ item["id"],
+ "reply",
+ )
+ events = await _collect(
+ SteeringMiddleware(bus).on_reasoning(
+ agent,
+ {},
+ model_call,
+ ),
+ )
+
+ queued = await list_chat_inputs(bus, "session")
+ error = queued[0]["error"]
+ self.assertIsInstance(error, str)
+ self.assertEqual(
+ queued,
+ [
+ {
+ **item,
+ "input": {"invalid": "message"},
+ "state": "failed",
+ "error": error,
+ },
+ ],
+ )
+ self.assertEqual(
+ [event for event in events if isinstance(event, Msg)],
+ [agent.state.context[-1]],
+ )
+ self.assertEqual(
+ await _custom_events(bus),
+ [
+ {
+ "metadata": {},
+ "type": "CUSTOM",
+ "name": "chat_input_steer_failed",
+ "value": {
+ "queue_item_id": item["id"],
+ "message_ids": [],
+ "message": error,
+ },
+ },
+ ],
+ )
diff --git a/tests/service_wakeup_dispatcher_test.py b/tests/service_wakeup_dispatcher_test.py
index 1b39fe374..3e9a08926 100644
--- a/tests/service_wakeup_dispatcher_test.py
+++ b/tests/service_wakeup_dispatcher_test.py
@@ -1771,6 +1771,8 @@ class TestChatEndpointQueue(IsolatedAsyncioTestCase):
"id": response.queue_item_id,
"created_at": items[0]["created_at"],
"input": message.model_dump(mode="json"),
+ "state": "queued",
+ "error": None,
},
],
)
@@ -1820,6 +1822,8 @@ class TestChatEndpointQueue(IsolatedAsyncioTestCase):
"id": response.queue_item_id,
"created_at": items[0]["created_at"],
"input": message.model_dump(mode="json"),
+ "state": "queued",
+ "error": None,
},
],
)